Gemini 原生
生成內容
使用 Google Gemini API 格式生成內容
搭配 列出模型 所返回的模型,使用 Gemini 的請求與回應格式。系統支援 ProtoJSON 的 lowerCamelCase 以及對應的 proto snake_case 欄位名稱。支援的可選欄位與數值取決於所選的模型。
路徑參數
模型名稱(例如 gemini-2.5-pro、gemini-3.5-flash)。
查詢參數
API key(標頭驗證的替代方案)。
身分驗證
Gemini 端點支援多種身分驗證方式:
?key=YOUR_API_KEY查詢參數x-goog-api-key: YOUR_API_KEY標頭Authorization: Bearer YOUR_API_KEY標頭
請求內文
包含 parts 與選用 role 的對話內容。多媒體部分請使用 inlineData / inline_data 或 fileData / file_data。由 TokenLab 建立的檔案與 Cache ID 僅能在其所屬的 Workspace 中使用。
給模型的系統指令。
生成設定,例如 temperature、topP、topK、maxOutputTokens、stopSequences、candidateCount、responseModalities、responseMimeType、responseSchema 以及 thinkingConfig。亦支援對應的 snake_case 名稱。支援的數值與組合取決於模型。
安全過濾器設定。
Gemini 工具,例如 functionDeclarations。支援的工具類型取決於模型。
工具設定,例如 functionCallingConfig。
使用 Create cached content 建立的快取內容名稱,例如 cachedContents/abc123。此設定僅在建立它的 Workspace 中有效。
上方顯示的所有 lowerCamelCase 欄位亦可使用其官方 proto 的 snake_case 拼法,例如 system_instruction、generation_config、safety_settings、tool_config、cached_content、file_data.file_uri 以及 inline_data.mime_type。
支援的方法
相容 Gemini 的 API 包含 列出模型、取得模型、generateContent、streamGenerateContent、countTokens、Files 以及快取內容。目前不支援 Gemini Interactions 與 Live。
呼叫模型前請先參閱該模型的 取得模型 回應:supportedGenerationMethods 列出了該模型支援的操作。
回應
生成的候選內容。
Token 使用量資訊。
請求
curl -X POST "https://api.tokenlab.sh/v1beta/models/gemini-2.5-pro:generateContent?key=sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"parts": [{"text": "Hello, Gemini!"}]
}
],
"generationConfig": {
"temperature": 0.7,
"maxOutputTokens": 1024
}
}'錯誤
400 INVALID_ARGUMENT:請求內文無效,或模型不接受 Gemini 請求。401 UNAUTHENTICATED:API key 遺失或無效。402 RESOURCE_EXHAUSTED:餘額不足以支付此請求。503 UNAVAILABLE:目前沒有適用於該模型的可用路由。請稍後重試。
多媒體輸入
將多媒體放置於 contents[].parts[] 中,可作為內嵌 Base64 位元組(inlineData 或 inline_data)或公開的 https URL(fileData 或 file_data)。支援圖片、音訊與影片。
圖片
使用內嵌圖片位元組:
{
"contents": [
{
"role": "user",
"parts": [
{ "text": "Please describe this image." },
{
"inlineData": {
"mimeType": "image/jpeg",
"data": "/9j/4AAQSkZJRgABAQ..."
}
}
]
}
]
}使用圖片 URL:
{
"contents": [
{
"role": "user",
"parts": [
{ "text": "Please describe this image." },
{
"fileData": {
"mimeType": "image/jpeg",
"fileUri": "https://example.com/demo.jpg"
}
}
]
}
]
}音訊
使用音訊 URL,此處使用 proto 的 snake_case 名稱:
{
"contents": [
{
"role": "user",
"parts": [
{ "text": "Transcribe and summarize this audio." },
{
"file_data": {
"mime_type": "audio/mpeg",
"file_uri": "https://example.com/sample.mp3"
}
}
]
}
]
}影片
使用影片 URL:
{
"contents": [
{
"role": "user",
"parts": [
{ "text": "Describe this video briefly." },
{
"fileData": {
"mimeType": "video/mp4",
"fileUri": "https://example.com/sample.mp4"
}
}
]
}
]
}回應
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{"text": "Hello! How can I assist you today?"}
]
},
"finishReason": "STOP",
"safetyRatings": [
{"category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE"}
]
}
],
"usageMetadata": {
"promptTokenCount": 5,
"candidatesTokenCount": 10,
"totalTokenCount": 15
}
}Token 計數與 Embeddings
計算 Token 數量(POST /v1beta/models/{model}:countTokens)需要 API key 且不計費。請使用計數進行規劃;生成請求的費用取決於該回應中的 usageMetadata。
Embedding 模型請使用 建立 Embedding(POST /v1/embeddings)。僅在模型的 取得模型 回應將其列於 supportedGenerationMethods 時,才呼叫 embedContent 或 batchEmbedContents。
API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。
位置: header
路徑參數
模型名稱 (例如 gemini-2.5-pro)
查詢參數
API 金鑰 (標頭驗證的替代方案)
請求標頭
單次請求傳遞策略。會覆寫 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified,並可能在輸出、請求接受或建立持久性資源前切換至 Official 模式一次。
可選值
- "auto"
- "verified"
- "official"
請求主體
application/json
原生的 Gemini GenerateContent 請求。ProtoJSON 的 lowerCamelCase 與原始 proto 的 snake_case 名稱皆可接受並會被保留,包含混合請求。若同一欄位同時存在兩種拼寫,TokenLab 不會合併它們或選擇本機優先順序。未知欄位將以盡力而為的方式轉發。
回應
application/json
application/json
application/json
application/json
application/json
application/json