
这篇 Gemini 4 Carbon API 指南带你从拿到 API 密钥开始,用 cURL、Python OpenAI SDK 和 Google 原生 generateContent 格式发出可用的请求,模型 ID 均为 gemini-4-carbon。每个示例都遵循 PoYo 截至 2026 年 11 月 16 日公布的请求 schema。可以先在 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 | 需要图像或文件 part(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 schema 中的可选字段: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 中到达,最后一个 chunk 带有 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 的 part,因此要跳过没有文本的 part:
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 上,文件输入走原生格式,以 inlineData part 传入,包含 mimeType 和 base64 编码的 data。PoYo 文档给出了图像示例,并建议把文本指令放在媒体 part 之前:
{
"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 schema 把 content 定义为字符串,所以不要向 /v1/chat/completions 发送 OpenAI 风格的图像数组。对于 PDF、音频和视频,PoYo 文档没有单独示例;先发一个小文件并检查响应,再在此基础上搭建流水线。媒体会计入提示:usageMetadata.promptTokensDetails 会按模态拆分提示 token。
设置最大输出
| 格式 | 字段 | 输出被截断的信号 |
|---|---|---|
| Chat Completions | max_tokens | finish_reason: "length" |
| Gemini Native | generationConfig.maxOutputTokens | finishReason 不是 STOP |
Google 列出的默认同步输出上限为 65,536 token,上下文为 1,048,576 token,由输入和输出共享。Google 价格页说明思考 token 按输出价格计费,因此 usage 中的输出计数可能大于可见文本。PoYo 公布的 schema 中没有思考等级字段;最大输出字段是文档中说明的长度控制手段。
读取用量并计算请求费用
PoYo 对 gemini-4-carbon 的定价为每 1M 输入 token $1.60、每 1M 输出 token $8.00、每 1M 缓存读取 token $0.08(1 积分 = $0.005)。
| 格式 | 输入 token | 输出 token(含思考) |
|---|---|---|
| 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 日):用非流式 /v1/chat/completions 请求让 gemini-4-carbon 审查一个 40 行的 Python 函数,6.3 秒返回 prompt_tokens: 480、completion_tokens: 1094 和 total_tokens: 1574,没有报告思考 token。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)
这里把每个提示 token 都按完整输入价格计算。缓存读取 token 按每 1M $0.08 计费,但 PoYo 的响应 schema 没有说明缓存 token 字段,所以请把这个公式视为上限。规模化的费用场景见 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,让被截断的回答可见。 - 把每个响应的用量块与你分配的请求 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 原生接口,在文本 part 之后加一个 inlineData part(mimeType 加 base64 data)。PoYo 上的 Chat Completions 只接受字符串内容。
如何限制 Gemini 4 Carbon API 的输出 token?
设置 max_tokens(Chat Completions)或 generationConfig.maxOutputTokens(原生)。思考 token 按输出计费,所以确定上限时要对比 usage 中的输出计数与可见文本。
为什么 Gemini 4 Carbon API 在 /v1/responses 上返回 400?
在 PoYo 上,gemini-4-carbon 只支持 Chat Completions 和 Gemini Native。其他格式会返回 400,并列出支持的 URI。