Gemini 原生

生成内容

使用 Google Gemini API 格式生成内容

POST
/v1beta/models/{model}:generateContent

使用列出模型返回的模型,以 Gemini 请求和响应格式调用。支持 ProtoJSON lowerCamelCase 和对应的 proto snake_case 字段名;可选字段和取值以所选模型为准。

路径参数

modelstringpath必填

模型名称(例如:gemini-2.5-pro,gemini-3.5-flash)。

查询参数

keystringquery

API 密钥(可替代请求头身份验证)。

身份验证

Gemini 端点支持多种身份验证方法:

  • ?key=YOUR_API_KEY 查询参数
  • x-goog-api-key: YOUR_API_KEY 请求头
  • Authorization: Bearer YOUR_API_KEY 请求头

请求体

contentsarray必填

对话内容,包含 parts 和可选的 role。媒体字段使用 inlineData / inline_data 或 fileData / file_data。TokenLab 创建的 Files 和 Cache ID 只能在所属工作区使用。

systemInstructionobject

模型的系统指令。

generationConfigobject

生成设置包括 temperature、topP、topK、maxOutputTokens、stopSequences、candidateCount、responseModalities、responseMimeType、responseSchema 和 thinkingConfig,也支持对应的 snake_case 名称。取值范围与组合以所选模型为准。

safetySettingsarray

安全过滤设置。

toolsarray

Gemini 工具,例如 functionDeclarations。支持的工具类型以所选模型为准。

toolConfigobject

工具配置,例如 functionCallingConfig。

cachedContentstring

通过创建 Gemini 缓存内容创建的缓存名称,例如 cachedContents/abc123。只能在创建它的工作区使用。

上面列出的每个 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 列出该模型接受的操作。

响应

candidatesarray

生成的候选内容。

usageMetadataobject

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 密钥缺失或无效。
  • 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"
          }
        }
      ]
    }
  ]
}

响应

Response
{
  "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 计数与 Embedding

统计 Token 数(POST /v1beta/models/{model}:countTokens)需要 API 密钥且不收费。计数用于请求规划;生成请求的费用以该响应的 usageMetadata 为准。

Embedding 模型请使用创建 Embedding 向量(POST /v1/embeddings)。只有当模型的获取模型响应在 supportedGenerationMethods 中列出 embedContent 或 batchEmbedContents 时,才调用这两个接口。

授权

AuthorizationBearer <token>

API Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。

位置: header

路径参数

model*string

模型名称 (例如 gemini-2.5-pro)

查询参数

key?string

API 密钥 (请求头身份验证的替代方案)

请求头

X-TokenLab-Delivery-Policy?string

单次请求的交付策略。覆盖 API 密钥和 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