Gemini 图像与文本生成接口文档（预览与生产）

统一消息/生成接口 — 包含 Gemini 的图像生成与通用文本生成（generateContent）示例与说明。

接口概览

方法	路径	说明
POST	`/v3/chat/gc/v1beta/models/{model}:generateContent`	通用生成接口（文本 / 图像 / 多模态），通过 `model` 路径区分模型
POST	`/v3/chat/gc/v1beta/models/gemini-3-pro-image-preview:generateContent`	图像生成（预览示例）

鉴权

二选一，任选其一：

Header	说明
`x-api-key: <API_KEY>`	使用 API Key
`Authorization: Bearer <token>`	使用 Bearer Token

示例（请将示例中的 x-api-key 替换为你的实际 Key）：

bash

curl -X POST "https://api.agentpivot.ai/v3/chat/gc/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "contents": [{"role":"user","parts":[{"text":"用一句话介绍自己"}]}],
    "generationConfig": {"maxOutputTokens": 256}
  }'

文本生成（`generateContent`）

此接口以 contents 字段接收多段消息（带 role 与 parts），按序拼接为提示发送给模型并返回候选 candidates。常见用于对话式提示、few-shot 示例或带上下文的生成任务。

请求

Content-Type：application/json
Path 参数：model，例如 gemini-2.5-flash 或 gemini-3-flash-preview

请求 Body 常用字段：

字段	类型	必填	说明
`contents`	array	是	消息序列，每项含 `role` 与 `parts`，按顺序组成提示（prompt）。
`generationConfig`	object	否	生成配置（如 `maxOutputTokens` 等）。
`stream`	boolean	否	是否请求流式输出（若后端支持）。

contents 单项结构说明：

字段	类型	说明
`role`	string	消息角色：`user` / `assistant` / `system` / `model` / `tool`
`parts`	array	每项为一个分段对象，常见为 `{ "text": "..." }`

示例：

json

{
  "contents": [
    {"role": "user", "parts": [{"text": "1+1等于多少？"}]},
    {"role": "model", "parts": [{"text": "1+1等于2。"}]},
    {"role": "user", "parts": [{"text": "再加1呢？"}]}
  ],
  "generationConfig": {"maxOutputTokens": 1024}
}

`generationConfig`（常见字段）

字段	类型	默认	说明
`maxOutputTokens`	number	—	最多生成的 token 数
`temperature`	number	1.0	采样温度，范围 `0~2`
`topP`	number	1.0	nucleus 采样阈值
`candidateCount`	number	1	返回候选回复数量
`stopSequences`	array	[]	停用序列

注意：不同后端代理可能支持不同子字段，实际以服务端为准。

行为说明

contents 中的 parts 会按序拼接形成输入提示；role 指定语境（如 system 用于指令）。
使用 candidateCount 可获取多个候选答案；客户端可基于置信度或自定义策略选择。
maxOutputTokens 与服务端限额共同决定最大输出长度，可能会被截断。
若启用流式（stream: true），响应可能为 SSE 或 chunked 数据流（视后端实现）。

响应（示例）

json

{
  "requestId": "req-abc123",
  "model": "gemini-2.5-flash",
  "created": 1710000000,
  "candidates": [
    {
      "index": 0,
      "content": [
        {"type": "output_text", "text": "1+1等于2。"}
      ]
    }
  ],
  "usage": {"prompt_tokens": 12, "output_tokens": 5, "total_tokens": 17}
}

响应字段说明：requestId（请求 ID）、candidates（候选输出数组）、content（分段输出，例如 type: output_text）。

流式请求（示例）

若后端支持 stream 参数，客户端可以 SSE / chunked 方式接收分块输出，提高感知实时性。下面给出 curl 与 Python 的流式示例：

curl 示例（SSE）:

bash

export API_KEY="YOUR_API_KEY"

curl -N -X POST "https://api.agentpivot.ai/v3/chat/gc/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role":"user","parts":[{"text":"请逐步输出 1 到 5，每个数字单独一条消息。"}]}],
    "generationConfig": {"maxOutputTokens": 64},
    "stream": true
  }'

# 输出示例（SSE 事件行）
# data: {"choices":[{"delta":{"content":"1"},"index":0}]}
# data: {"choices":[{"delta":{"content":"\n2"},"index":0}]}
# data: [DONE]

Python 示例（使用 requests 逐行处理 SSE 格式）：

python

import os
import requests

API_KEY = os.getenv("API_KEY")
url = "https://api.agentpivot.ai/v3/chat/gc/v1beta/models/gemini-2.5-flash:generateContent"
payload = {
  "contents": [{"role": "user", "parts": [{"text": "请逐步输出 1 到 5，每个数字单独一条消息。"}]}],
  "generationConfig": {"maxOutputTokens": 64},
  "stream": True
}
headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}

with requests.post(url, headers=headers, json=payload, stream=True) as resp:
    for raw in resp.iter_lines(decode_unicode=True):
        if not raw:
            continue
        # SSE 行通常以 "data: " 开头
        if raw.startswith("data: "):
            data = raw[len("data: "):]
            if data.strip() == "[DONE]":
                break
            print("chunk:", data)

图像生成

（保留原图像生成示例）

bash

curl -X POST "https://api.agentpivot.ai/v3/chat/gc/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "生成一张跑车的展示图片。"}]
    }],
    "generationConfig": {
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "1K"}
    }
  }'

响应通常包含 outputs 数组，含 mime_type、image_url 或 base64 等字段。

支持模型

文本 / 通用模型

模型名称
gemini-3-flash-preview
gemini-3.1-flash-lite-preview
gemini-3.1-pro-preview
gemini-2.5-flash
gemini-2.5-flash-lite
gemini-2.5-flash-lite-preview-09-2025
gemini-2.5-pro

图像模型

模型名称
gemini-3-pro-image-preview
gemini-3.1-flash-image-preview
gemini-2.5-flash-image

测试脚本

bash

export API_KEY="YOUR_API_KEY"

curl -X POST "https://api.agentpivot.ai/v3/chat/gc/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role":"user","parts":[{"text":"用一句话介绍自己"}]}],
    "generationConfig": {"maxOutputTokens": 256}
  }'

注意事项

请勿在公开仓库中提交真实的 API Key。
generationConfig 的字段及默认值可能随后端实现不同而变化；若请求被拒绝或报错，请参见返回的错误信息或联系后端运维。
若需要流式或更低延迟输出，请与服务端确认是否支持 stream 参数与 SSE/chunked 传输。

文本生成（generateContent）
流式请求示例
图像生成
支持模型

如需添加更多语言示例（Java/Go）、高级流式客户端示例或对接说明，我可以继续补充。

Gemini 图像与文本生成接口文档（预览与生产） ​

接口概览 ​

鉴权 ​

文本生成（generateContent） ​

请求 ​

generationConfig（常见字段） ​

行为说明 ​

响应（示例） ​

流式请求（示例） ​

图像生成 ​

支持模型 ​

文本 / 通用模型 ​

图像模型 ​

测试脚本 ​

注意事项 ​

Gemini 图像与文本生成接口文档（预览与生产）

接口概览

鉴权

文本生成（`generateContent`）

请求

`generationConfig`（常见字段）

行为说明

响应（示例）

流式请求（示例）

图像生成

支持模型

文本 / 通用模型

图像模型

测试脚本

注意事项