
この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 Completions | POST https://api.poyo.ai/v1/chat/completions | すでにOpenAI SDKを使っており、テキストのみのメッセージを送る |
| Gemini Native | POST 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 Completions | max_tokens | finish_reason: "length" |
| Gemini Native | generationConfig.maxOutputTokens | STOP 以外の 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 Completions | usage.prompt_tokens | usage.total_tokens − usage.prompt_tokens |
| Gemini Native | usageMetadata.promptTokenCount | totalTokenCount − 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を使う |
| 400 | Gemini Nativeのエラー。Google形式の {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}} | contents / generationConfig を修正 |
| 401 | APIキーがない、または無効 | 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が返ります。