how-tos

Gemini 4 Carbon API 가이드: cURL, Python, Gemini Native로 첫 요청 보내기

Poyo.ai Team
8 min read
Share:

Gemini 4 Carbon API 가이드: cURL과 Python으로 첫 요청 보내기

이 Gemini 4 Carbon API 가이드는 API 키 발급부터 cURL, Python OpenAI SDK, Google 네이티브 generateContent 형식으로 동작하는 요청을 보내기까지의 과정을 모델 ID gemini-4-carbon 기준으로 안내합니다. 모든 예제는 2026년 11월 16일 기준 PoYo가 공개한 요청 스키마를 따릅니다. 먼저 Gemini 4 Carbon 모델 페이지에서 프롬프트를 테스트해 볼 수 있습니다.

이 모델이 처음이라면 제한과 포지셔닝을 다룬 Gemini 4 Carbon API 개요부터 읽어 보세요.

시작하기 전에

PoYo 대시보드에서 키를 생성하고 서버에 보관하세요.

export POYO_API_KEY="your-poyo-key"
형식엔드포인트이런 경우에 사용
Chat CompletionsPOST https://api.poyo.ai/v1/chat/completions이미 OpenAI SDK를 사용 중이고, 텍스트 전용 메시지인 경우
Gemini NativePOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContent이미지나 파일 파트(inlineData)가 필요한 경우
Gemini Native 스트리밍POST https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContent서버 전송 이벤트(SSE)를 쓰는 네이티브 형식

모든 요청은 Authorization: Bearer $POYO_API_KEY를 보냅니다. PoYo에서 gemini-4-carbon은 /v1/responses와 /v1/messages를 지원하지 않습니다.

cURL로 첫 Gemini 4 Carbon API 요청 보내기

curl https://api.poyo.ai/v1/chat/completions \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-carbon",
    "messages": [
      {"role": "system", "content": "You are a code reviewer. Be specific and cite line numbers."},
      {"role": "user", "content": "Review this function for race conditions: ..."}
    ],
    "max_tokens": 8192,
    "temperature": 1
  }'

model과 messages는 필수입니다. PoYo 스키마의 선택 필드는 temperature(0–2), top_p(0–1, temperature와 둘 중 하나만 사용), max_tokens, stream, stop(최대 4개 시퀀스), frequency_penalty와 presence_penalty(−2~2), n입니다. 각 메시지의 content는 문자열입니다.

응답은 표준 chat.completion 객체입니다. 텍스트는 choices[0].message.content에, 종료 원인은 choices[0].finish_reason에, 토큰 수는 usage.prompt_tokens, usage.completion_tokens, usage.total_tokens에 있습니다.

OpenAI SDK를 사용하는 Python

SDK가 PoYo를 가리키도록 설정하기만 하면 나머지는 바꿀 필요가 없습니다.

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.poyo.ai/v1", api_key=os.environ["POYO_API_KEY"])

resp = client.chat.completions.create(
    model="gemini-4-carbon",
    messages=[
        {"role": "system", "content": "You are a senior backend engineer."},
        {"role": "user", "content": "Write a migration plan from Celery 4 to Celery 5."},
    ],
    max_tokens=8192,
)

print(resp.choices[0].message.content)
print(resp.choices[0].finish_reason, resp.usage.prompt_tokens, resp.usage.completion_tokens)

gemini-4-argon이나 PoYo에서 Chat Completions를 지원하는 다른 모델에서 옮겨 올 때는 model 한 줄만 바꾸면 됩니다.

OpenAI SDK로 스트리밍하기

stream=True로 설정하면 PoYo는 chat.completion.chunk 이벤트를 보내고 data: [DONE]으로 끝냅니다. 텍스트는 choices[0].delta.content로 도착하며, 마지막 청크에 finish_reason과 usage가 담깁니다.

stream = client.chat.completions.create(
    model="gemini-4-carbon",
    messages=[{"role": "user", "content": "Explain the CAP theorem with one example per trade-off."}],
    max_tokens=4096,
    stream=True,
)

usage = None
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if getattr(chunk, "usage", None):
        usage = chunk.usage
print("\n", usage)

Gemini 네이티브 generateContent 형식

네이티브 엔드포인트는 모델을 URL 경로로 받습니다. 본문은 contents(각각 role이 user 또는 model이고 parts 배열을 가짐)를 사용하며, 선택적으로 generationConfig(temperature, topP, topK, maxOutputTokens, stopSequences)와 safetySettings를 넣습니다.

curl "https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContent" \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "List three risks of running database migrations during peak traffic."}]}
    ],
    "generationConfig": {"maxOutputTokens": 2048, "temperature": 0.7}
  }'

응답은 Google의 GenerateContentResponse 객체가 그대로 반환됩니다. 텍스트는 candidates[].content.parts[].text에, 토큰 수는 usageMetadata에 있습니다. 사고(thinking) 모델은 thought: true나 thoughtSignature가 있는 파트를 추가할 수 있으므로, 텍스트가 없는 파트는 건너뛰세요.

import os, requests

URL = "https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContent"
HEADERS = {"Authorization": f"Bearer {os.environ['POYO_API_KEY']}"}

body = {
    "contents": [{"role": "user", "parts": [{"text": "Summarize the trade-offs of event sourcing."}]}],
    "generationConfig": {"maxOutputTokens": 2048},
}
r = requests.post(URL, headers=HEADERS, json=body, timeout=600)
r.raise_for_status()
data = r.json()

text = "".join(
    p["text"]
    for c in data.get("candidates", [])
    for p in c.get("content", {}).get("parts", [])
    if "text" in p and not p.get("thought")
)
print(text)
print(data["usageMetadata"])

네이티브 스트리밍

메서드를 :streamGenerateContent로 바꾸세요. 응답은 text/event-stream이며, 각 data: 줄은 부분 GenerateContentResponse이고, 마지막 이벤트에 finishReason이 담기며, 스트림은 data: [DONE]으로 끝납니다. alt=sse 쿼리 파라미터는 허용되지만 필수는 아닙니다.

import json

STREAM_URL = "https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContent"
usage = {}
with requests.post(STREAM_URL, headers=HEADERS, json=body, stream=True, timeout=600) as r:
    r.raise_for_status()
    for line in r.iter_lines(decode_unicode=True):
        if not line or not line.startswith("data: "):
            continue
        payload = line[len("data: "):]
        if payload == "[DONE]":
            break
        event = json.loads(payload)
        for cand in event.get("candidates", []):
            for part in cand.get("content", {}).get("parts", []):
                if "text" in part and not part.get("thought"):
                    print(part["text"], end="", flush=True)
        usage = event.get("usageMetadata", usage)
print("\n", usage)

Gemini 4 Carbon API의 멀티모달 입력

Google은 Gemini 4 Carbon의 입력 유형으로 텍스트, 이미지, 오디오, 동영상, PDF를 명시합니다. PoYo에서 파일 입력은 네이티브 형식을 통해 mimeType과 base64 data를 가진 inlineData 파트로 보냅니다. PoYo 문서는 이미지 예제를 제시하며, 텍스트 지시를 미디어 파트보다 앞에 두도록 권장합니다.

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "Read this architecture diagram and list every service that writes to the database."},
        {"inlineData": {"mimeType": "image/png", "data": "BASE64_IMAGE_DATA"}}
      ]
    }
  ],
  "generationConfig": {"maxOutputTokens": 4096}
}

PoYo의 Chat Completions 스키마는 content를 문자열로 문서화하므로, /v1/chat/completions에 OpenAI 스타일의 이미지 배열을 보내지 마세요. PDF, 오디오, 동영상에 대해서는 PoYo 문서에 별도 예제가 없습니다. 파이프라인을 구축하기 전에 작은 파일 하나를 먼저 보내 응답을 확인하세요. 미디어는 프롬프트 토큰에 포함되며, usageMetadata.promptTokensDetails에서 모달리티별 프롬프트 토큰 내역을 볼 수 있습니다.

최대 출력 설정

형식필드출력이 잘렸다는 신호
Chat Completionsmax_tokensfinish_reason: "length"
Gemini NativegenerationConfig.maxOutputTokensSTOP이 아닌 finishReason

Google은 기본 동기 출력 상한을 65,536 토큰으로, 컨텍스트를 입력과 출력이 공유하는 1,048,576 토큰으로 명시합니다. Google 가격 페이지에 따르면 사고 토큰은 출력 요금으로 과금되므로, usage의 출력 토큰 수가 눈에 보이는 텍스트보다 클 수 있습니다. PoYo가 공개한 스키마에는 사고 수준 필드가 없으며, 문서화된 길이 제어 수단은 최대 출력 필드입니다.

usage 읽기와 요청 비용 계산

PoYo의 gemini-4-carbon 가격은 100만 토큰당 입력 $1.60, 출력 $8.00, 캐시 읽기 $0.08입니다(1크레딧 = $0.005).

형식입력 토큰출력 토큰 (사고 포함)
Chat Completionsusage.prompt_tokensusage.total_tokens − usage.prompt_tokens
Gemini NativeusageMetadata.promptTokenCounttotalTokenCount − promptTokenCount (답변 + thoughtsTokenCount)
INPUT_USD, OUTPUT_USD = 1.60, 8.00  # PoYo, per 1M tokens

def carbon_cost_usd(input_tokens: int, output_tokens: int) -> float:
    return (input_tokens * INPUT_USD + output_tokens * OUTPUT_USD) / 1_000_000

def carbon_cost_credits(input_tokens: int, output_tokens: int) -> float:
    return carbon_cost_usd(input_tokens, output_tokens) / 0.005

실측 예시(PoYo 프로덕션, 2026년 11월 16일): gemini-4-carbon에 40줄짜리 Python 함수 리뷰를 요청한 비스트리밍 /v1/chat/completions 요청은 6.3초 만에 prompt_tokens: 480, completion_tokens: 1094, total_tokens: 1574를 반환했고, thinking 토큰은 보고되지 않았습니다. PoYo는 1.904 크레딧을 청구했으며, 공식으로 계산한 값과 같습니다.

input:     480 × $1.60 / 1,000,000 = $0.000768   (0.1536 credits)
output:  1,094 × $8.00 / 1,000,000 = $0.008752   (1.7504 credits)
total:                               $0.009520   (1.9040 credits)

이 계산은 모든 프롬프트 토큰에 전체 입력 요금을 적용합니다. 캐시 읽기 토큰은 100만 토큰당 $0.08로 과금되지만, PoYo 응답 스키마에는 캐시된 토큰 필드가 문서화되어 있지 않으므로 이 공식은 상한값으로 보세요. 대규모 사용 시의 비용 시나리오는 Gemini 4 Carbon API 가격에 있습니다.

처리해야 할 오류

PoYo의 LLM 엔드포인트는 실제 HTTP 상태 코드를 반환합니다.

HTTP원인대응
400필드 누락 또는 잘못된 필드, 본문 {"code": 400, "error": {"type": "validation_error", ...}}요청을 수정하고 error.details 확인
400이 모델에 맞지 않는 형식, 메시지에 지원 URI 목록 포함Chat Completions 또는 Gemini Native 사용
400Gemini Native 오류, Google 형식 {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}}contents / generationConfig 수정
401API 키 누락 또는 무효Authorization 헤더 확인
402크레딧 부족충전 후 재시도
404알 수 없는 모델 ID (model_not_found)철자 확인: gemini-4-carbon
500 / 502 / 503서버 또는 업스트림 오류지수 백오프로 재시도

PoYo 문서에 따르면 LLM 엔드포인트에는 현재 속도 제한이 없지만, PoYo의 일반 오류 코드에는 429가 포함되어 있습니다. 대기 후 재시도로 처리하세요. OpenAI SDK에서는 openai.APIStatusError를 잡아 status_code로 분기하세요. 전체 응답 본문은 PoYo 오류 코드를 참고하세요.

배포 전 체크리스트

  • POYO_API_KEY는 서버에만 두고, 브라우저나 모바일 코드에 절대 포함하지 마세요.
  • 항상 max_tokens 또는 maxOutputTokens를 설정하고, finish_reason / finishReason을 로그로 남겨 잘린 답변을 확인할 수 있게 하세요.
  • 모든 응답의 usage 블록을 직접 부여한 요청 ID와 함께 저장해 기능별 지출을 대조할 수 있게 하세요.
  • 길고 변하지 않는 컨텍스트(저장소 파일, 문서)는 앞에, 바뀌는 질문은 마지막에 두세요. 그래야 암시적 캐싱이 적용될 가능성이 생깁니다.
  • 5xx와 429 응답만 재시도하세요. 400은 본문을 바꾸기 전까지 계속 실패합니다.

에이전트 루프, 도구 출력, 긴 컨텍스트 패턴은 코딩 에이전트를 위한 Gemini 4 Carbon API에서 이어집니다. Argon으로 충분한 경우를 판단하려면 Gemini 4 Carbon API vs Gemini 4 Argon을 읽어 보세요.

자주 묻는 질문

Python에서 Gemini 4 Carbon API를 어떻게 호출하나요?

base_url="https://api.poyo.ai/v1", PoYo 키, model="gemini-4-carbon"으로 OpenAI SDK를 사용하세요. 네이티브 요청은 requests로 /v1beta/models/gemini-4-carbon:generateContent에 POST하면 됩니다.

Gemini 4 Carbon API는 스트리밍을 지원하나요?

예. Chat Completions에서 "stream": true를 설정하거나, 네이티브 형식에서 :streamGenerateContent를 호출하세요. 둘 다 data: [DONE]으로 끝나는 서버 전송 이벤트를 반환합니다.

Gemini 4 Carbon API에 이미지를 어떻게 보내나요?

Gemini 네이티브 엔드포인트를 사용해 텍스트 파트 뒤에 inlineData 파트(mimeType과 base64 data)를 넣으세요. PoYo의 Chat Completions는 문자열 content만 받습니다.

Gemini 4 Carbon API의 출력 토큰을 어떻게 제한하나요?

max_tokens(Chat Completions) 또는 generationConfig.maxOutputTokens(네이티브)를 설정하세요. 사고 토큰은 출력으로 과금되므로, 상한을 정할 때 usage의 출력 토큰 수와 눈에 보이는 텍스트를 비교해 보세요.

Gemini 4 Carbon API가 /v1/responses에서 400을 반환하는 이유는 무엇인가요?

PoYo에서 gemini-4-carbon은 Chat Completions와 Gemini Native만 지원합니다. 다른 형식은 지원되는 URI 목록과 함께 400을 반환합니다.

Share: