Generate Content API 完整指南

Generate Content API 是 Gemini 的核心生成接口，适合文本生成、多轮对话、图像理解、函数调用、流式输出和结构化结果生成等场景。

在 Xikapi 中，请使用 Gemini 兼容路径，并将请求域名替换为：

https://xikapi.com

常用请求地址：

https://xikapi.com/v1beta/models/{model}:generateContent

为什么使用 Generate Content API

Generate Content API 使用 contents、parts、systemInstruction、tools、generationConfig 等字段组织请求，适合把 Gemini 接入到聊天助手、知识库问答、业务系统和多模态应用中。

它的常见优势包括：

• 支持文本和图像等多模态输入
• 支持多轮消息上下文
• 支持函数调用
• 支持结构化输出
• 支持流式输出
• 请求结构适合服务端统一封装

基础文本生成

curl "https://xikapi.com/v1beta/models/gemini-3.5-flash:generateContent?key=$XIKAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          { "text": "Explain in three sentences what Gemini is best suited for" }
        ]
      }
    ]
  }'

JavaScript：

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  apiKey: process.env.XIKAPI_API_KEY,
  httpOptions: {
    baseUrl: "https://xikapi.com"
  }
});

const response = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: "Introduce the Gemini Generate Content API"
});

console.log(response.text);

Python：

from google import genai
from google.genai import types

client = genai.Client(
    api_key="YOUR_XIKAPI_API_KEY",
    http_options=types.HttpOptions(base_url="https://xikapi.com"),
)

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Introduce the Gemini Generate Content API",
)

print(response.text)

systemInstruction

系统级要求可以放在 systemInstruction 中，用来控制角色、语气、边界和格式。

{
  "systemInstruction": {
    "parts": [
      {
        "text": "You are a precise technical documentation assistant. Keep answers concise and accurate."
      }
    ]
  },
  "contents": [
    {
      "parts": [
        {
          "text": "Explain why API keys should not be stored in frontend code"
        }
      ]
    }
  ]
}

contents 和 parts

contents 表示对话内容，parts 表示同一条消息中的文本、图片、函数调用结果等内容块。

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "My system needs knowledge-base Q&A" }
      ]
    },
    {
      "role": "model",
      "parts": [
        { "text": "You can split documents, retrieve relevant chunks, and use Gemini to generate answers." }
      ]
    },
    {
      "role": "user",
      "parts": [
        { "text": "What are good document chunking practices?" }
      ]
    }
  ]
}

多轮对话

服务端通常需要保存历史消息，并在下一轮请求中把必要上下文重新传给 Gemini。

{
  "contents": [
    {
      "role": "user",
      "parts": [{ "text": "Summarize this contract" }]
    },
    {
      "role": "model",
      "parts": [{ "text": "This contract mainly covers scope of services, fees, and breach clauses." }]
    },
    {
      "role": "user",
      "parts": [{ "text": "Focus on payment risks" }]
    }
  ]
}

generationConfig

generationConfig 用来控制输出长度、随机性、停止序列、响应格式等生成参数。

{
  "generationConfig": {
    "temperature": 0.2,
    "maxOutputTokens": 1024,
    "stopSequences": ["</answer>"]
  },
  "contents": [
    {
      "parts": [
        { "text": "Classify this text as complaint, inquiry, or praise" }
      ]
    }
  ]
}

图像输入

图像可以作为 inlineData 放入 parts 中，适合截图分析、票据识别、图表理解和图片问答。

{
  "contents": [
    {
      "parts": [
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "BASE64_IMAGE_DATA"
          }
        },
        {
          "text": "Analyze the main content of this image"
        }
      ]
    }
  ]
}

函数调用

函数调用让 Gemini 在需要外部信息或业务动作时返回函数调用请求，由服务端执行函数并回填结果。

{
  "tools": [
    {
      "functionDeclarations": [
        {
          "name": "get_order_status",
          "description": "Check order status",
          "parameters": {
            "type": "OBJECT",
            "properties": {
              "order_id": {
                "type": "STRING",
                "description": "Order ID"
              }
            },
            "required": ["order_id"]
          }
        }
      ]
    }
  ],
  "contents": [
    {
      "parts": [
        { "text": "Check the status of order A1001" }
      ]
    }
  ]
}

流式输出

流式输出适合前端实时展示。请求路径使用 streamGenerateContent。

curl "https://xikapi.com/v1beta/models/gemini-3.5-flash:streamGenerateContent?key=$XIKAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          { "text": "Write a short article about API integration" }
        ]
      }
    ]
  }'

错误处理

常见错误包括：

状态码	含义	排查方向
400	请求参数错误	检查 JSON、模型名、字段类型
401	鉴权失败	检查 API Key 是否正确
403	权限不足	检查模型权限或账户权限
413	请求过大	压缩图片、裁剪上下文、拆分文档
429	触发限流	降低并发、增加重试、检查额度
500/503	服务异常	稍后重试，记录请求 ID

接入建议

• API Key 只放在服务端
• 生产环境显式设置 maxOutputTokens
• 多轮对话只保留必要历史
• 图像和长文档任务注意请求体大小
• 函数调用结果必须经过权限校验
• 所有 Gemini 兼容请求地址统一使用 https://xikapi.com/v1beta/...