API文档

OpenAI 格式调用

使用 OpenAI 兼容格式通过 Python、JavaScript 或 HTTP 请求调用 AI 模型的完整示例与参数说明。

我们的接口完全兼容 OpenAI /v1/chat/completions 标准，您只需将原有代码中的 base_url 和 api_key 替换为我们平台的配置，即可零成本迁移，无需改动任何业务逻辑。

接入配置

配置项	值
Base URL	`https://api.zestai.pro/v1`
API Key	您在控制台创建的 `sk-` 开头的令牌

访问模型广场可以查看所有可用模型名称，直接复制模型 ID 使用即可。

快速示例

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",  # 替换为您的令牌
    base_url="https://api.zestai.pro/v1",
)

response = client.chat.completions.create(
    model="gemini-3-flash-preview",  # 替换为您想使用的模型
    messages=[
        {"role": "system", "content": "你是一个有帮助的助手。"},
        {"role": "user", "content": "你好，请介绍一下你自己。"},
    ],
)

print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-your-api-key", // 替换为您的令牌
  baseURL: "https://api.zestai.pro/v1",
});

const response = await client.chat.completions.create({
  model: "gemini-3-flash-preview", // 替换为您想使用的模型
  messages: [
    { role: "system", content: "你是一个有帮助的助手。" },
    { role: "user", content: "你好，请介绍一下你自己。" },
  ],
});

console.log(response.choices[0].message.content);

POST https://api.zestai.pro/v1/chat/completions

Headers

Key	Value
`Content-Type`	`application/json`
`Authorization`	`Bearer sk-your-api-key`

Body

{
  "model": "gemini-3-flash-preview",
  "messages": [
    { "role": "system", "content": "你是一个有帮助的助手。" },
    { "role": "user", "content": "你好，请介绍一下你自己。" }
  ]
}

流式输出（Streaming）

流式输出可以让模型像打字一样逐字返回内容，显著提升用户体验，适合聊天类应用场景。

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.zestai.pro/v1",
)

stream = client.chat.completions.create(
    model="gemini-3-flash-preview",
    messages=[{"role": "user", "content": "写一首关于秋天的诗。"}],
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="", flush=True)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-your-api-key",
  baseURL: "https://api.zestai.pro/v1",
});

const stream = await client.chat.completions.create({
  model: "gemini-3-flash-preview",
  messages: [{ role: "user", content: "写一首关于秋天的诗。" }],
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content ?? "";
  process.stdout.write(content);
}

开启流式输出时，响应为 SSE（Server-Sent Events）格式，每行以 data: 开头，结束时发送 data: [DONE]。

POST https://api.zestai.pro/v1/chat/completions

Headers

Key	Value
`Content-Type`	`application/json`
`Authorization`	`Bearer sk-your-api-key`

Body

{
  "model": "gemini-3-flash-preview",
  "messages": [
    { "role": "user", "content": "写一首关于秋天的诗。" }
  ],
  "stream": true
}

多轮对话

通过在 messages 数组中传入历史消息，即可实现上下文连续的多轮对话。

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.zestai.pro/v1",
)

# 维护对话历史
history = [{"role": "system", "content": "你是一个有帮助的助手。"}]

def chat(user_input: str):
    history.append({"role": "user", "content": user_input})
    response = client.chat.completions.create(
        model="gemini-3-flash-preview",
        messages=history,
    )
    reply = response.choices[0].message.content
    history.append({"role": "assistant", "content": reply})
    return reply

print(chat("我叫小明。"))
print(chat("你还记得我叫什么名字吗？"))

图像理解（多模态）

支持视觉能力的模型（如 gpt-4o、gemini-2.5-pro 等）可以直接传入图片进行理解与分析。

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.zestai.pro/v1",
)

response = client.chat.completions.create(
    model="gemini-3-flash-preview",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "请描述这张图片的内容。"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.jpg",
                        # 也可以使用 base64：
                        # "url": "data:image/jpeg;base64,{base64_image}"
                    },
                },
            ],
        }
    ],
)

print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-your-api-key",
  baseURL: "https://api.zestai.pro/v1",
});

const response = await client.chat.completions.create({
  model: "gemini-3-flash-preview",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "请描述这张图片的内容。" },
        {
          type: "image_url",
          image_url: { url: "https://example.com/image.jpg" },
        },
      ],
    },
  ],
});

console.log(response.choices[0].message.content);

图片 URL 和 base64 两种方式均支持，base64 格式为 data:{mime_type};base64,{data}。

POST https://api.zestai.pro/v1/chat/completions

Headers

Key	Value
`Content-Type`	`application/json`
`Authorization`	`Bearer sk-your-api-key`

Body（URL 方式）

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "请描述这张图片的内容。" },
        {
          "type": "image_url",
          "image_url": { "url": "https://example.com/image.jpg" }
        }
      ]
    }
  ]
}

Body（base64 方式）

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "请描述这张图片的内容。" },
        {
          "type": "image_url",
          "image_url": { "url": "data:image/jpeg;base64,<base64 编码的图片字符串>" }
        }
      ]
    }
  ]
}

请求参数说明

以下为 /v1/chat/completions 接口支持的常用参数：

必填参数

参数	类型	说明
`model`	`string`	模型 ID，例如 `gpt-4o`、`gemini-3-flash-preview`、`claude-sonnet-4-20250514`
`messages`	`array`	对话消息数组，每条消息包含 `role` 和 `content` 两个字段

`messages[].role` 可选值

值	说明
`system`	系统提示词，用于设定模型的行为角色与背景，建议放在数组首位
`user`	用户发送的消息
`assistant`	模型上一轮的回复，用于构造多轮对话历史

常用可选参数

参数	类型	默认值	说明
`stream`	`boolean`	`false`	是否开启流式输出（SSE）
`max_tokens`	`integer`	模型默认值	限制模型单次回复的最大 Token 数量
`temperature`	`number`	`1.0`	随机性控制，范围 `0~2`。越低越确定，越高越随机创意
`top_p`	`number`	`1.0`	核采样概率，与 `temperature` 二选一使用，请勿同时修改两者
`n`	`integer`	`1`	单次请求生成的候选回复数量
`stop`	`string / array`	`null`	遇到指定字符串时停止生成，例如 `["\n", "END"]`
`presence_penalty`	`number`	`0`	范围 `-2~2`，正值降低模型重复已出现词语的概率
`frequency_penalty`	`number`	`0`	范围 `-2~2`，正值降低模型重复高频词语的概率

响应结构

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1711000000,
  "model": "gemini-3-flash-preview",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！我是一个 AI 助手，很高兴为你服务。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 30,
    "completion_tokens": 25,
    "total_tokens": 55
  }
}

字段	说明
`choices[].message.content`	模型生成的回复内容
`choices[].finish_reason`	停止原因：`stop`（正常结束）、`length`（达到 max_tokens）、`content_filter`（内容过滤）
`usage.prompt_tokens`	输入消耗的 Token 数
`usage.completion_tokens`	输出消耗的 Token 数
`usage.total_tokens`	本次请求总 Token 消耗（计费依据）

建议在生产环境中对 429 和 5xx 错误实现指数退避重试策略，以提升服务稳定性。

CC Switch 配置教程

学习如何将ZestAI API 集成到 CC Switch 中，实现多工具统一管理。

Gemini 原生格式调用

使用 Google Gemini 原生 SDK（google-genai / @google/genai）通过 Python、JavaScript 或 HTTP 请求调用 Gemini 模型的完整示例与参数说明。