how-tos

Gemini 4 Carbon APIガイド:cURL、Python、Gemini Nativeで最初のリクエストを送る

Poyo.ai Team
5 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ネイティブ形式でServer-Sent Eventsを使う

すべてのリクエストで 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 の1行を変えるだけです。

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 に入ります。思考モデルは 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 は文字列として定義されているため、OpenAI形式の画像配列を /v1/chat/completions に送らないでください。PDF、音声、動画については、PoYoのドキュメントに個別の例はありません。パイプラインを構築する前に、まず小さなファイルを1つ送ってレスポンスを確認してください。メディアはプロンプトとしてカウントされます。usageMetadata.promptTokensDetails で、プロンプトトークンのモダリティ別の内訳を確認できます。

最大出力の設定

形式フィールド出力が途中で切れたことを示すシグナル
Chat Completionsmax_tokensfinish_reason: "length"
Gemini NativegenerationConfig.maxOutputTokensSTOP 以外の finishReason

Googleは、同期リクエストのデフォルトの出力上限を65,536トークン、入力と出力で共有するコンテキストを1,048,576トークンとしています。Googleの料金ページによれば思考トークンは出力料金で課金されるため、usage の出力トークン数は表示されるテキストより大きくなることがあります。PoYoの公開スキーマには思考レベルのフィールドがなく、ドキュメントに記載された長さの制御手段は最大出力のフィールドです。

使用量を読み取ってリクエストの費用を計算する

PoYoでの gemini-4-carbon の料金は、入力100万トークンあたり$1.60、出力100万トークンあたり$8.00、キャッシュ読み取り100万トークンあたり$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を呼び出すには?

OpenAI SDKで base_url="https://api.poyo.ai/v1"、PoYoのキー、model="gemini-4-carbon" を使います。ネイティブのリクエストは、requests で /v1beta/models/gemini-4-carbon:generateContent にPOSTします。

Gemini 4 Carbon APIはストリーミングに対応していますか?

はい。Chat Completionsで "stream": true を設定するか、ネイティブ形式で :streamGenerateContent を呼び出します。どちらも data: [DONE] で終わるServer-Sent Eventsを返します。

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: