how-tos

Gemini 4 Carbon API: Hướng dẫn gửi yêu cầu đầu tiên bằng cURL, Python và Gemini Native

Poyo.ai Team
11 min read
Share:

Hướng dẫn Gemini 4 Carbon API: yêu cầu đầu tiên bằng cURL và Python

Hướng dẫn Gemini 4 Carbon API này đưa bạn từ lúc có API key đến một yêu cầu chạy được bằng cURL, OpenAI SDK cho Python và định dạng generateContent gốc của Google, tất cả đều dùng model ID gemini-4-carbon. Mỗi ví dụ bám theo schema yêu cầu PoYo công bố tính đến ngày 16 tháng 11 năm 2026. Bạn có thể thử prompt trên trang model Gemini 4 Carbon trước.

Mới làm quen với model này? Hãy bắt đầu với tổng quan Gemini 4 Carbon API để nắm các giới hạn và vị trí của model.

Trước khi bắt đầu

Tạo một khóa trong dashboard của PoYo và giữ nó trên máy chủ của bạn:

export POYO_API_KEY="your-poyo-key"
Định dạngEndpointDùng khi
Chat CompletionsPOST https://api.poyo.ai/v1/chat/completionsBạn đã dùng OpenAI SDK, message chỉ có văn bản
Gemini NativePOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContentBạn cần part hình ảnh hoặc tệp (inlineData)
Gemini Native streamingPOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContentĐịnh dạng gốc với server-sent events

Mọi yêu cầu đều gửi Authorization: Bearer $POYO_API_KEY. Trên PoYo, gemini-4-carbon không hỗ trợ /v1/responses hay /v1/messages.

Yêu cầu Gemini 4 Carbon API đầu tiên bằng cURL

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 và messages là bắt buộc. Các trường tùy chọn trong schema của PoYo: temperature (0–2), top_p (0–1, dùng trường này hoặc temperature, không dùng cả hai), max_tokens, stream, stop (tối đa 4 chuỗi), frequency_penalty và presence_penalty (−2 đến 2), và n. content của mỗi message là một chuỗi.

Phản hồi là một đối tượng chat.completion tiêu chuẩn: văn bản nằm trong choices[0].message.content, lý do dừng nằm trong choices[0].finish_reason, và số token nằm trong usage.prompt_tokens, usage.completion_tokens và usage.total_tokens.

Python với OpenAI SDK

Trỏ SDK tới PoYo và không cần thay đổi gì khác:

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)

Chuyển từ gemini-4-argon, hoặc bất kỳ model nào khác hỗ trợ Chat Completions trên PoYo, chỉ cần đổi một dòng ở model.

Streaming với OpenAI SDK

Với stream=True, PoYo gửi các sự kiện chat.completion.chunk và kết thúc bằng data: [DONE]. Văn bản đến trong choices[0].delta.content, và chunk cuối cùng mang finish_reason cùng 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)

Định dạng generateContent gốc của Gemini

Endpoint gốc nhận model trong đường dẫn URL. Phần thân dùng contents (mỗi phần tử có role là user hoặc model và một mảng parts), cùng generationConfig tùy chọn (temperature, topP, topK, maxOutputTokens, stopSequences) và 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}
  }'

Phản hồi là đối tượng GenerateContentResponse của Google, được trả về trực tiếp. Văn bản nằm trong candidates[].content.parts[].text và số token nằm trong usageMetadata. Các model có thinking có thể thêm part với thought: true hoặc thoughtSignature, vì vậy hãy bỏ qua các part không có văn bản:

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"])

Streaming ở định dạng gốc

Đổi phương thức thành :streamGenerateContent. Phản hồi có kiểu text/event-stream: mỗi dòng data: là một GenerateContentResponse từng phần, sự kiện cuối cùng mang finishReason, và luồng kết thúc bằng data: [DONE]. Tham số truy vấn alt=sse được chấp nhận nhưng không bắt buộc.

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)

Đầu vào đa phương thức qua Gemini 4 Carbon API

Google liệt kê văn bản, hình ảnh, âm thanh, video và PDF là các loại đầu vào của Gemini 4 Carbon. Trên PoYo, đầu vào dạng tệp đi qua định dạng gốc dưới dạng một part inlineData có mimeType và data mã hóa base64. Tài liệu của PoYo có một ví dụ hình ảnh và khuyên đặt chỉ dẫn văn bản trước các part media:

{
  "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}
}

Schema Chat Completions của PoYo mô tả content là một chuỗi, vì vậy đừng gửi mảng hình ảnh kiểu OpenAI tới /v1/chat/completions. Với PDF, âm thanh và video, tài liệu của PoYo không có ví dụ riêng; hãy gửi thử một tệp nhỏ trước và kiểm tra phản hồi rồi mới xây pipeline dựa trên nó. Media được tính vào prompt: usageMetadata.promptTokensDetails phân tách token prompt theo từng phương thức.

Thiết lập đầu ra tối đa

Định dạngTrườngDấu hiệu đầu ra bị cắt
Chat Completionsmax_tokensfinish_reason: "length"
Gemini NativegenerationConfig.maxOutputTokensfinishReason khác STOP

Google liệt kê 65,536 token đầu ra là mức trần đồng bộ mặc định và ngữ cảnh 1,048,576 token dùng chung cho đầu vào và đầu ra. Trang giá của Google cho biết token thinking được tính theo giá đầu ra, nên số token đầu ra trong usage có thể lớn hơn phần văn bản nhìn thấy. Schema PoYo công bố không có trường mức thinking; trường đầu ra tối đa là cơ chế kiểm soát độ dài được tài liệu hóa.

Đọc usage và tính chi phí của một yêu cầu

PoYo định giá gemini-4-carbon ở mức $1.60 cho mỗi 1M token đầu vào, $8.00 cho mỗi 1M token đầu ra và $0.08 cho mỗi 1M token đọc cache (1 tín dụng = $0.005).

Định dạngToken đầu vàoToken đầu ra (gồm thinking)
Chat Completionsusage.prompt_tokensusage.total_tokens − usage.prompt_tokens
Gemini NativeusageMetadata.promptTokenCounttotalTokenCount − promptTokenCount (câu trả lời cộng 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

Ví dụ đo thực tế (môi trường production của PoYo, 16/11/2026): một yêu cầu /v1/chat/completions không streaming nhờ gemini-4-carbon review một hàm Python 40 dòng đã trả về prompt_tokens: 480, completion_tokens: 1094 và total_tokens: 1574 trong 6,3 giây, không có thinking token nào được báo cáo. PoYo tính 1,904 credit, đúng bằng con số công thức cho ra.

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)

Cách tính này áp giá đầu vào đầy đủ cho mọi token prompt. Token đọc cache được tính $0.08 cho mỗi 1M, nhưng schema phản hồi của PoYo không mô tả trường token được cache, nên hãy coi công thức này là giới hạn trên. Các kịch bản chi phí ở quy mô lớn có trong Giá Gemini 4 Carbon API.

Các lỗi nên xử lý

Các endpoint LLM trên PoYo trả về mã trạng thái HTTP thật:

HTTPNguyên nhânCách xử lý
400Thiếu trường hoặc trường không hợp lệ; thân phản hồi {"code": 400, "error": {"type": "validation_error", ...}}Sửa yêu cầu; đọc error.details
400Sai định dạng cho model này; thông báo liệt kê các URI được hỗ trợDùng Chat Completions hoặc Gemini Native
400Lỗi Gemini Native, theo cấu trúc của Google {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}}Sửa contents / generationConfig
401Thiếu API key hoặc key không hợp lệKiểm tra header Authorization
402Không đủ tín dụngNạp thêm trước khi thử lại
404Model ID không xác định (model_not_found)Kiểm tra chính tả: gemini-4-carbon
500 / 502 / 503Lỗi máy chủ hoặc lỗi upstreamThử lại với exponential backoff

Tài liệu của PoYo cho biết các endpoint LLM hiện chưa bị giới hạn tốc độ, nhưng danh sách mã lỗi chung của PoYo có 429. Hãy xử lý mã này bằng cách chờ rồi thử lại. Với OpenAI SDK, bắt openai.APIStatusError và rẽ nhánh theo status_code. Xem mã lỗi PoYo để biết đầy đủ nội dung phản hồi.

Danh sách kiểm tra trước khi phát hành

  • Giữ POYO_API_KEY ở phía máy chủ; không bao giờ đưa nó vào mã trình duyệt hay ứng dụng di động.
  • Luôn đặt max_tokens hoặc maxOutputTokens, và ghi log finish_reason / finishReason để thấy được các câu trả lời bị cắt.
  • Lưu khối usage của mỗi phản hồi cạnh request ID do bạn gán, để có thể đối soát chi tiêu theo từng tính năng.
  • Đặt ngữ cảnh dài, ổn định (tệp trong repository, tài liệu) lên trước và câu hỏi thay đổi ở cuối, để implicit caching có cơ hội được áp dụng.
  • Chỉ thử lại với phản hồi 5xx và 429; lỗi 400 sẽ tiếp tục thất bại cho đến khi thân yêu cầu được sửa.

Với vòng lặp agent, đầu ra công cụ và các mẫu ngữ cảnh dài, hãy đọc tiếp Gemini 4 Carbon API cho coding agent. Để quyết định khi nào Argon là đủ, hãy đọc Gemini 4 Carbon API vs Gemini 4 Argon.

Câu hỏi thường gặp

Làm sao gọi Gemini 4 Carbon API bằng Python?

Dùng OpenAI SDK với base_url="https://api.poyo.ai/v1", khóa PoYo của bạn và model="gemini-4-carbon". Với yêu cầu định dạng gốc, gửi POST tới /v1beta/models/gemini-4-carbon:generateContent bằng requests.

Gemini 4 Carbon API có hỗ trợ streaming không?

Có. Đặt "stream": true trên Chat Completions, hoặc gọi :streamGenerateContent ở định dạng gốc. Cả hai đều trả về server-sent events kết thúc bằng data: [DONE].

Làm sao gửi hình ảnh tới Gemini 4 Carbon API?

Dùng endpoint gốc của Gemini với một part inlineData (mimeType cùng data base64) đặt sau part văn bản. Chat Completions trên PoYo chỉ nhận content dạng chuỗi.

Làm sao giới hạn số token đầu ra của Gemini 4 Carbon API?

Đặt max_tokens (Chat Completions) hoặc generationConfig.maxOutputTokens (định dạng gốc). Token thinking được tính như đầu ra, vì vậy hãy so sánh số token đầu ra trong usage với phần văn bản nhìn thấy khi chọn mức trần.

Vì sao Gemini 4 Carbon API trả về 400 trên /v1/responses?

Trên PoYo, gemini-4-carbon chỉ hỗ trợ Chat Completions và Gemini Native. Các định dạng khác trả về 400 kèm danh sách các URI được hỗ trợ.

Share: