how-tos

Gemini 4 Carbon API 指南:用 cURL、Python 和 Gemini Native 发出第一个请求

Poyo.ai Team
6 min read
Share:

Gemini 4 Carbon API 指南:用 cURL 和 Python 发出第一个请求

这篇 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 CompletionsPOST https://api.poyo.ai/v1/chat/completions已在使用 OpenAI SDK,纯文本消息
Gemini NativePOST 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 Completionsmax_tokensfinish_reason: "length"
Gemini NativegenerationConfig.maxOutputTokensfinishReason 不是 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 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 日):用非流式 /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
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,让被截断的回答可见。
  • 把每个响应的用量块与你分配的请求 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。

Share: