开发者文档 2026.07
智脑API平台接入文档
本文档面向 API 开发者、Codex / Claude Code 用户、IDE 插件和桌面客户端使用者。
接入时请优先使用 https://api.zhinaoapi.ai/v1 作为 OpenAI Compatible Base URL;网页、控制台和价格页面继续访问 https://zhinaoapi.ai。
统一 API 入口
平台兼容 OpenAI Chat / Responses / Images、Claude Messages 和 Grok 等常用接口。每个 API Key 绑定一个分组,只能调用该分组当前可用的模型与能力。
专用 API 域名
API 调用统一走 api.zhinaoapi.ai,与官网静态页面分离,减少 CDN、页面缓存和流式长连接相互影响。
计费状态实时同步
账户余额按实际用量扣减,充值开放状态看控制台。各模型当前费率可在 API 价格页查看。
一键接入工具
API 密钥页面提供 Claude Code、Codex、Cursor、OpenClaw、桌面客户端等一键接入配置,适合非开发用户快速启用。
本栏会直接读取后台公开设置,避免域名、注册和购买状态被文档写死。最后同步:正在读取…
| 配置 | 当前状态 |
|---|---|
| API Base URL | https://api.zhinaoapi.ai |
| 注册 / 邮箱验证 | 注册开放 / 需要邮箱验证 |
| 余额充值 | 读取中,请以控制台为准 |
| 系统版本 | v0.1.160 |
若后台稍后调整,上述状态会在刷新本页后更新。账户余额按实际用量扣减,充值开放状态看控制台;模型价格与分组倍率可查看 API 价格页。
本平台是第三方 AI API 网关,不是 OpenAI、Anthropic、xAI 或其他模型厂商的官方网站。后台当前公开条款明确:本服务不面向中国大陆地区居民、个人开发者或未取得相关资质的主体提供公开 API 中转、代理调用或转售服务;用户应在注册、充值、调用和向第三方提供服务前自行确认所在地法律法规、上游政策及所需资质。最终以注册/登录页面展示的最新服务条款、使用政策和支持地区说明为准。
快速开始
先确认使用场景,再复制正确的 Base URL 和 API Key。普通代码调用看下面三步;客户端工具建议直接使用「API 密钥」页面的一键接入。
注册账号并登录
访问 https://zhinaoapi.ai 完成注册和邮箱验证后登录,进入后台可查看余额、用量记录和渠道状态。注册与邮箱验证开关以本页上方实时状态为准。
创建 API 密钥
在控制台进入「API 密钥」页面,点击「创建 API 密钥」。系统会生成一个以 sk- 开头的密钥,请妥善保管;如需给 Claude Code、Codex、Cursor、OpenClaw 等工具配置,可直接点击该页面的「一键接入」。
API Key 是您账户的访问凭证,请勿在客户端代码、公开仓库或聊天中泄露。如不慎泄露,请立即在控制台删除并重新生成。
发起第一次请求
普通 OpenAI Compatible 项目使用 https://api.zhinaoapi.ai/v1;下面用 Chat Completions 做最小测试,将 sk-YOUR_API_KEY 替换为您的实际密钥:
curl https://api.zhinaoapi.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-YOUR_API_KEY" \
-d '{
"model": "gpt-5.5",
"messages": [
{"role": "user", "content": "你好,请介绍一下你自己。"}
]
}'
如果返回了包含 choices 字段的 JSON 响应,说明 Chat Completions 接入成功;如果您的客户端明确支持 Responses API,再使用 /v1/responses。
小白接入教程
从注册、创建密钥到 Codex 与 Claude 的完整图文操作流程。
API 基础信息
Seedance 异步视频是本页 API 域名说明的例外:请使用已验证的 https://zhinaoapi.ai/api/v3/contents/generations/tasks,具体方法、分组和路径见 Seedance 视频生成接入。普通聊天、Grok 视频和 SSE 仍遵循各自的专用 API 域名说明。
官网、注册、登录、后台和文档访问 https://zhinaoapi.ai;终端、插件、SDK、Codex、Claude Code、Trae、Cursor、OpenClaw 等 API 调用请使用 https://api.zhinaoapi.ai。不要把 zhinaoapi.ai、www.zhinaoapi.ai 或 localhost 当作 API Base URL,否则流式请求可能出现重连、超时、空转或 4xx/5xx 错误。
接入地址
| 配置项 | 值 |
|---|---|
| Base URL | https://api.zhinaoapi.ai/v1 |
| Chat Completions | https://api.zhinaoapi.ai/v1/chat/completions |
| Responses | https://api.zhinaoapi.ai/v1/responses |
| Images | https://api.zhinaoapi.ai/v1/images/generations / https://api.zhinaoapi.ai/v1/images/edits |
| Grok Videos | https://api.zhinaoapi.ai/v1/videos/generations / https://api.zhinaoapi.ai/v1/videos/{request_id} |
| 协议 | HTTPS(必须) |
| 请求格式 | JSON(Content-Type: application/json) |
Chat Completions 与 Responses 怎么选
| 接口 | 适合场景 | 说明 |
|---|---|---|
/v1/chat/completions | 通用聊天、旧版 SDK、Trae / Cherry Studio / ChatBox 等常见客户端 | 兼容面最广。客户端只支持 OpenAI Chat 模式时,优先使用这个接口。 |
/v1/responses | Codex、Agent 类工具、支持 Responses 的新版客户端 | 能力更完整,但要求客户端真正支持 Responses 协议。客户端不支持时强行配置会报错。 |
/v1/messages | Claude Code、Claude 兼容客户端 | Claude 工具通常使用 Anthropic Messages 协议,Base URL 一般填写 https://api.zhinaoapi.ai,不带 /v1。 |
身份认证
所有 API 请求均需在 HTTP 请求头中携带 Bearer Token 进行身份验证:
Authorization: Bearer sk-YOUR_API_KEY
如果您的项目已经使用 OpenAI SDK,通常只需要修改 base_url 和 api_key。但不同客户端对 Chat、Responses、Claude Messages 的支持不同,遇到异常时请先确认该工具到底支持哪一种协议。
支持的模型
平台已支持 GPT-5.6、Claude、Grok 以及图像和视频生成等主流模型。调用时只需要在请求里的 model 字段填写完整模型 ID,并使用对应分组的 API Key 发起请求。
gpt-5.6-sol、claude-opus-4-8、grok-4.5 等模型均按完整模型 ID 接入。客户端里请原样填写完整模型 ID,不要只填系列名称,也不要把网站地址或分组名称填到 model 字段。Grok 模型必须使用归属「Grok分组」的 API Key。
Codex / OpenAI 系列
| 模型标识 | 类型 | 说明 | 适用场景 |
|---|---|---|---|
gpt-5.6-sol |
GPT | GPT-5.6 系列高能力模型,偏复杂推理和高质量输出 | 复杂代码任务、深度分析、Agent 工作流 |
gpt-5.6-luna |
GPT | GPT-5.6 系列均衡模型,质量与速度兼顾 | 日常开发、长上下文对话、通用生产调用 |
gpt-5.6-terra |
GPT | GPT-5.6 系列稳定模型,适合持续任务 | 批量处理、工具调用、持续对话 |
gpt-5.5 |
GPT | 上一代旗舰模型,兼容性好 | 复杂推理、长文档分析、专业写作 |
gpt-5.4 |
GPT | 高性能旗舰模型,稳定可靠 | 通用对话、复杂分析、生产环境调用 |
gpt-5.4-mini |
GPT | 5.4 系列轻量版,性价比高 | 日常对话、内容生成、翻译 |
gpt-5.3-codex |
GPT | 代码专精模型 | 代码生成、Debug、代码审查 |
gpt-5.3-codex-spark |
GPT | Codex 轻量模型,响应更快 | 快速代码修改、轻量审查、IDE 辅助 |
gpt-image-2 |
Image | 图像生成与编辑模型,按量余额扣费 | 文生图、图片编辑、多图创作 |
gpt-5.2 |
GPT | 上一代旗舰,能力均衡 | 通用对话、文案创作 |
gpt-5.2-chat-latest |
GPT | 5.2 系列聊天别名 | 兼容旧客户端、普通聊天 |
gpt-5.2-pro |
GPT | 5.2 系列增强版 | 复杂分析、长任务、专业输出 |
codex-auto-review |
Codex | 代码审查专用模型 | 自动审查、变更总结、代码质量检查 |
Grok 系列
| 模型标识 | 类型 | 说明 | 适用场景 |
|---|---|---|---|
grok-4.5 | Grok | 当前默认高能力文本模型 | 通用对话、复杂推理、代码与工具调用 |
grok-4.3 | Grok | 稳定文本模型 | 日常对话、内容生成、兼容性调用 |
grok-build-0.1 | Code | 面向开发任务的 Build 模型 | 代码生成、修改、调试和工程任务 |
grok-composer-2.5-fast | Code | 快速 Composer 模型 | 代码规划、文件修改、快速迭代 |
grok-4.20-0309-reasoning | Reasoning | 推理版本 | 复杂分析、多步骤问题、严谨推理 |
grok-4.20-0309-non-reasoning | Fast | 非推理版本 | 低延迟对话、摘要和内容生成 |
grok-4.20-multi-agent-0309 | Agent | 多智能体版本 | 复杂任务拆解和 Agent 工作流 |
grok-imagine | Image | 高质量图片生成别名 | 文生图,实际按高质量图片模型处理 |
grok-imagine-image | Image | 标准图片生成 | 海报、插画、概念图 |
grok-imagine-image-quality | Image HQ | 高质量图片生成 | 高细节、高质量视觉输出 |
grok-imagine-edit | Edit | 图片编辑 | 基于图片 URL 的改图、风格和内容调整 |
grok-imagine-video | Video | 视频生成模型 | 文生视频、视频编辑与扩展 |
grok-imagine-video-1.5 | Video 1.5 | 增强视频模型 | 文生、图生与参考图视频任务;参考图最高 720p |
Claude 系列
| 模型标识 | 类型 | 说明 | 适用场景 |
|---|---|---|---|
claude-fable-5 |
Claude | Claude 5 系列高能力模型 | 复杂创作、长文本理解、深度对话 |
claude-sonnet-5 |
Claude | Claude Sonnet 5,速度与质量均衡 | 日常开发、代码辅助、长任务协作 |
claude-opus-4-8 |
Claude | Opus 4.8,当前常用旗舰模型 | 复杂分析、深度推理、专业创作 |
claude-opus-4-6 |
Claude | Opus 4.6,超长上下文 | 长文处理、研究辅助 |
claude-opus-4-5-20251101 |
Claude | Opus 4.5,综合性能卓越 | 深度对话、研究辅助 |
claude-sonnet-4-6 |
Claude | Sonnet 最新版,能力与速度兼顾 | 日常开发、代码辅助、文案 |
claude-sonnet-4-5-20250929 |
Claude | Sonnet 4.5,性价比优秀 | 批量处理、内容生成 |
claude-haiku-4-5-20251001 |
Claude | Haiku 极速版,响应飞快 | 高并发对话、快速分类、摘要 |
GPT-5.6 系列请按完整 ID 选择:偏复杂推理可试 gpt-5.6-sol,日常均衡可试 gpt-5.6-luna,持续任务可试 gpt-5.6-terra。Grok 通用接入优先从 grok-4.5 开始,代码任务可选 Build / Composer,媒体任务必须改用对应 Imagine 模型和媒体端点。Claude Code 或 Claude 客户端优先选择 Claude Opus / Sonnet 系列。
Grok 接入指南
Grok 使用 OpenAI 兼容的 Bearer 鉴权。先在控制台创建归属「Grok分组」的 API Key,再把 Base URL 设置为 https://api.zhinaoapi.ai/v1。建议先用 grok-4.5 完成文本验证,再调用图片或视频。
Grok 模型只能由 Grok 分组的密钥调度。使用 Codex、Claude 或其他分组的密钥请求 Grok,通常会返回 404 model_not_found 或“当前分组没有可用账号”。媒体接口还需要该分组已开通图片或视频能力;单纯加长 HTTP 超时不能解决权限或模型不可用问题。
接入地址与接口
| 能力 | 请求地址 | 推荐模型 |
|---|---|---|
| Chat Completions | POST /v1/chat/completions | grok-4.5、grok-4.3、Build / Composer |
| Responses | POST /v1/responses | grok-4.5、推理和多智能体模型 |
| Claude 兼容调用 | POST /v1/messages | 系统转换为 Grok Responses,适合 Messages 协议客户端 |
| 图片生成 | POST /v1/images/generations | grok-imagine-image / grok-imagine-image-quality |
| 图片编辑 | POST /v1/images/edits | grok-imagine-edit |
| 视频生成 | POST /v1/videos/generations | grok-imagine-video / grok-imagine-video-1.5 |
| 视频编辑 / 扩展 | POST /v1/videos/edits / POST /v1/videos/extensions | Grok Imagine Video 系列 |
| 查询 / 下载视频 | GET /v1/videos/{request_id} / GET /v1/videos/{request_id}/content | 使用提交任务后返回的 request_id |
cURL:先完成文本验证
将示例密钥替换为真实的 Grok 分组 API Key。返回 JSON 中出现 choices 即表示文本接入成功;不要把密钥放到网页前端、公开仓库或截图里。
curl https://api.zhinaoapi.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-YOUR_GROK_KEY" \
-d '{
"model": "grok-4.5",
"messages": [
{"role": "user", "content": "只回复:Grok 接入成功"}
],
"max_tokens": 64,
"stream": false
}'
Python:Responses API
已安装官方 OpenAI Python SDK 的项目,只需替换 base_url 和 api_key。环境变量名可自行调整。
from openai import OpenAI
import os
client = OpenAI(
api_key=os.environ["NINE_M8M_API_KEY"],
base_url="https://api.zhinaoapi.ai/v1",
)
response = client.responses.create(
model="grok-4.5",
input="用三句话说明这个接口已连接成功。",
)
print(response.output_text)
Node.js:Chat Completions
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.NINE_M8M_API_KEY,
baseURL: "https://api.zhinaoapi.ai/v1",
});
const completion = await client.chat.completions.create({
model: "grok-4.5",
messages: [{ role: "user", content: "你好,Grok!" }],
});
console.log(completion.choices[0].message.content);
图片生成与编辑
图片生成使用 /images/generations;改图使用 /images/edits。图片参数里的 resolution 是图片档位,和视频的 480p / 720p / 1080p 不是同一组值。
| 参数 | 图片生成写法 | 说明 |
|---|---|---|
model | grok-imagine-image | 高质量图片可改为 grok-imagine-image-quality |
prompt | 字符串 | 描述主体、场景、镜头、风格和文字要求 |
resolution | "1k" 或 "2k" | 图片分辨率档位;未填写时由上游采用默认值 |
aspect_ratio | "1:1"、"16:9"、"9:16" 等 | 支持 1:1、16:9、9:16、4:3、3:4、3:2、2:3、2:1、1:2、19.5:9、9:19.5、20:9、9:20 |
n | 整数,例如 1 | 生成张数,范围 1–10,默认 1;测试时建议先用 1 张 |
response_format | "url" 或 "b64_json" | 返回图片链接或 Base64;需要直接保存二进制时可选 b64_json |
image | {"url":"https://..."} | 仅用于编辑;最多可给 3 张源图,推荐使用一张清晰、公开可读取的 HTTPS 图片 |
curl https://api.zhinaoapi.ai/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-YOUR_GROK_KEY" \
-d '{
"model": "grok-imagine-image",
"prompt": "一座未来城市的夜景,电影级光影,干净的构图",
"resolution": "2k",
"aspect_ratio": "16:9",
"n": 1
}'
# 把 example.com/source.jpg 换成真实、可公开读取的图片地址
curl https://api.zhinaoapi.ai/v1/images/edits \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-YOUR_GROK_KEY" \
-d '{
"model": "grok-imagine-edit",
"prompt": "保留主体,把背景改成雪山日出",
"image": {"url": "https://example.com/source.jpg"}
}'
视频生成:先分清首帧图和参考图
视频接口是异步任务:提交后先得到 request_id,再查询状态。图片地址请换成真实图片;推荐公网可直接读取的 HTTPS URL。上游也接受 data:image/...;base64,... 形式的数据 URL,但不要传本机磁盘路径、网页预览页地址或需要登录才能访问的链接。
| 目标 | 模型和字段 | 该字段的作用 |
|---|---|---|
| 文生视频 | grok-imagine-video 或 grok-imagine-video-1.5;不传图片 | 由 prompt 决定画面和运动 |
| 固定第一帧(图生视频) | grok-imagine-video-1.5 + "image":{"url":"..."} | image 是首帧,适合让已有图片动起来 |
| 人物 / 商品 / 风格参考 | grok-imagine-video-1.5 + "reference_images":[{"url":"..."}] | 参考图指导内容或风格,不会锁定视频第一帧 |
| 首帧 + 参考图 | 同时传 image 和 reference_images | image 固定开头,参考图补充人物、服装、商品或美术风格 |
REST 请求应写 "image":{"url":"..."} 和 "reference_images":[{"url":"..."}]。不要把 URL 直接写成字符串数组,也不要写 SDK 专用的 image_url、reference_image_urls。使用多张参考图时,按数组顺序在提示词中写 <IMAGE_0>、<IMAGE_1> 来说明每张图的用途。
视频参数:秒数、分辨率与参考图
| 参数 | 写法 | 规则与建议 |
|---|---|---|
model | 字符串 | 纯文生视频优先 grok-imagine-video;图生视频或参考图使用 grok-imagine-video-1.5 |
prompt | 字符串 | 描述主体、动作、镜头和节奏。纯文生和参考图模式必填;多参考图用 <IMAGE_0> 等标记对应对象 |
duration | 整数秒,例如 8 或 10 | 范围 1–15,默认 8。它控制成片时长,和 HTTP 请求超时无关;本站示例统一使用 duration,不要写 seconds |
resolution | "480p"、"720p"、"1080p" | 视频分辨率。带 reference_images 时最高只能使用 720p;不确定时从 480p 或 720p 开始 |
aspect_ratio | "16:9"、"9:16"、"1:1" 等 | 支持 1:1、16:9、9:16、4:3、3:4、3:2、2:3;竖屏短视频常用 9:16 |
image | {"url":"https://.../first.jpg"} | 首帧图片。图生视频请用对象格式,不要传本机路径 |
reference_images | [{"url":"..."},{"url":"..."}] | 最多 7 张,只用于 grok-imagine-video-1.5;参考人物、商品或风格时按顺序在提示词里标记 |
cURL:文生视频
curl https://api.zhinaoapi.ai/v1/videos/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-YOUR_GROK_KEY" \
-d '{
"model": "grok-imagine-video",
"prompt": "海浪拍打礁石,电影镜头,缓慢推进",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
cURL:图生视频(固定首帧)
# image 是“固定第一帧”的图片,不是参考图数组
curl https://api.zhinaoapi.ai/v1/videos/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-YOUR_GROK_KEY" \
-d '{
"model": "grok-imagine-video-1.5",
"prompt": "保持人物外观不变,人物轻轻转头微笑,镜头缓慢推近",
"image": {"url": "https://example.com/first-frame.jpg"},
"duration": 8,
"resolution": "720p",
"aspect_ratio": "9:16"
}'
cURL:参考图生成视频(人物与风格)
这个示例有两张参考图:第 0 张是人物,第 1 张是视觉风格。参考图模式最多 7 张,最高 720p;提示词中的编号必须和数组顺序对应。
curl https://api.zhinaoapi.ai/v1/videos/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-YOUR_GROK_KEY" \
-d '{
"model": "grok-imagine-video-1.5",
"prompt": "让 <IMAGE_0> 中的人物穿着相同服装,在雨后的城市街道缓慢行走;画面采用 <IMAGE_1> 的霓虹电影风格。",
"reference_images": [
{"url": "https://example.com/person.jpg"},
{"url": "https://example.com/style.jpg"}
],
"duration": 10,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
Python:提交、轮询并下载视频
视频生成提交接口只负责创建任务,不能把一次 HTTP 请求当作“等待视频完成”。下面的标准库示例每 5 秒查询一次,最多等待 10 分钟;完成后读取 video.url,并下载视频文件。
import json
import os
import time
from pathlib import Path
from urllib.request import Request, urlopen
API_ROOT = "https://api.zhinaoapi.ai"
API_BASE = API_ROOT + "/v1"
API_KEY = os.environ["NINE_M8M_API_KEY"]
def api_request(method, path, payload=None):
data = None if payload is None else json.dumps(payload).encode("utf-8")
request = Request(
API_BASE + path,
data=data,
method=method,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
)
with urlopen(request, timeout=60) as response:
return json.load(response)
job = api_request("POST", "/videos/generations", {
"model": "grok-imagine-video-1.5",
"prompt": "让 <IMAGE_0> 中的人物在阳光下缓慢转身。",
"reference_images": [{"url": "https://example.com/person.jpg"}],
"duration": 8,
"resolution": "720p",
"aspect_ratio": "9:16",
})
request_id = job["request_id"]
print("任务已创建:", request_id)
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
state = api_request("GET", f"/videos/{request_id}")
if state.get("status") == "done":
video_url = state["video"]["url"]
if video_url.startswith("/"):
video_url = API_ROOT + video_url
download = Request(video_url, headers={"Authorization": f"Bearer {API_KEY}"})
with urlopen(download, timeout=120) as response:
Path("grok-video.mp4").write_bytes(response.read())
print("已下载:grok-video.mp4")
break
print("仍在处理,5 秒后再次查询…")
time.sleep(5)
else:
raise TimeoutError("10 分钟内未完成;请保留 request_id 后稍后继续查询。")
仅查询或下载已完成视频
# 查询任务;完成时状态为 done,结果地址在 video.url
curl https://api.zhinaoapi.ai/v1/videos/REQUEST_ID \
-H "Authorization: Bearer sk-YOUR_GROK_KEY"
# 任务完成后也可通过本站内容端点下载
curl -L https://api.zhinaoapi.ai/v1/videos/REQUEST_ID/content \
-H "Authorization: Bearer sk-YOUR_GROK_KEY" \
-o grok-video.mp4
"duration": 10 的含义是“生成约 10 秒的视频”,不是“等 10 秒后超时”。单次提交或轮询请求建议使用 30~60 秒 HTTP 超时;由轮询循环负责等待任务完成。不要在同一条请求上长时间挂起,也不要使用官网域名 https://zhinaoapi.ai 调用媒体接口。
常见错误与排查
| 错误或现象 | 常见原因 | 处理方法 |
|---|---|---|
401 | API Key 缺失、错误或已停用 | 重新复制密钥,确认 Header 是 Authorization: Bearer ... |
404 model_not_found | 模型名不完整,或密钥不属于 Grok 分组 | 核对完整模型 ID,并在 API 密钥页面确认分组和模型权限 |
400 参数错误 | duration 不是 1–15 的整数、参考图结构写错、参考图配了 1080p,或模型不匹配 | 按上方 JSON 对照;参考图必须是对象数组,且使用 grok-imagine-video-1.5 与 480p / 720p |
| 图片读取失败 | URL 是本地路径、预览页、私有链接或临时链接已失效 | 改为上游可直接读取的图片原文件 HTTPS URL;先在无登录浏览器窗口验证地址能打开图片 |
403 permission_error | 媒体生成权限未开启 | 为 Grok 分组开启对应图片 / 视频能力,或联系管理员 |
429 | 上游限流或并发已满 | 等待 1、2、4 秒进行指数退避重试,不要同时重复提交相同任务 |
503 grok_media_no_eligible_account | 当前没有可用于媒体生成的 Grok 账号 | 稍后重试;持续出现时查看渠道状态或联系管理员 |
| 轮询很久仍未完成 | 视频任务仍在上游队列或处理 | 保存 request_id,稍后继续查询;不要重新提交同一任务,避免重复扣费 |
Seedance 视频生成接入
Seedance 文生视频、参考图视频使用异步任务 API:创建任务 → 保存任务 ID → 轮询状态 → 下载 MP4。本节包含模型、参数、计费、鉴权和 cURL / Python / Node.js 完整示例;不是聊天流式接口。
登录 智脑控制台,创建或选择绑定「seedance视频分组」的 API Key。使用用户自己的 Key,格式为 Authorization: Bearer sk-...;不要填写其他分组的 Key,也不需要上游账号或 Cookie。请在自己的服务端保管 Key,不要写入公开网页或代码仓库。
模型与当前支持范围
| 请求中的 model | 类型 | 允许 duration | 输出分辨率 | 成功视频价格 |
|---|---|---|---|---|
seedance2.0fast | Seedance 2.0 Fast | 5 / 10 / 15 秒 | 720p | ¥0.50 / 条 |
seedance2.5 | Seedance 2.5 | 5 / 10 / 30 秒 | 720p | ¥0.50 / 条 |
优先原样填写上表模型 ID,不要自行猜测 doubao-seedance-*、ep-* 或把分组名称填入 model。可用别名以模型广场为准,不能根据别名推定模型能力。普通 2.0 与 Mini 不属于本节已验证接入的两款模型。两款模型均已完成 5 秒 720p 文生视频验证;其他时长与参考图属于当前接口支持范围,不代表所有组合都已经逐项验收。
API 地址与调用流程
| 操作 | 方法和完整地址 | 说明 |
|---|---|---|
| 创建任务 | POST https://zhinaoapi.ai/api/v3/contents/generations/tasks | 提交一次,响应中取 id |
| 查询任务 | GET https://zhinaoapi.ai/api/v3/contents/generations/tasks/{id} | 同一个用户、同一个 API Key、同一分组查询 |
| 下载视频 | 成功响应中的 content.video_url | 使用返回的完整签名 URL,不附带 Sub2 API Key |
本节使用已验证的 Seedance 公网任务地址,路径从 /api/v3 开始;不要拼接 /v1,不要使用 /v1/chat/completions、/v1/responses、/v1/videos/generations 或 SSE 方式提交。普通聊天和 Grok 视频的 Base URL / 请求格式与本节不同。
- 准备绑定「seedance视频分组」的 API Key,确保余额和 Key 配额充足。
- 向创建端点 POST JSON,立即保存返回的
id。5 秒指成片时长,不是响应等待时间。 - 使用同一个 Key 每 15~30 秒 GET 任务状态,直到
succeeded或failed等终态。不要持续高频查询。 - 成功后取
content.video_url下载并保存 MP4。链接有时效且代表下载权限,请勿公开分享。
创建响应超时、断线或 5xx 时,上游可能已经接受任务。目前不提供可依赖的创建幂等键;不要自动重复 POST,也不要让反向代理重试创建请求。已有任务 ID 时只重试 GET;没有拿到 ID 时请保存时间、错误响应和请求日志供客服核查,避免重复创建与扣费。
创建参数表
| 字段 | 类型 / 必填 | 当前支持值与说明 |
|---|---|---|
model | string / 必填 | seedance2.0fast 或 seedance2.5 |
content | array / 必填 | 至少一条非空文本;可追加最多 10 张参考图片,数组总项数最多 12 |
content[].type | string / 必填 | text 或 image_url,不支持音频 / 视频引用 |
content[].text | string / 文本项必填 | 提示词。多条文本合并后最多 10,000 字符;建议描述主体、运动、镜头、风格和声音 |
content[].image_url.url | string / 图片项必填 | 可直接访问的公网 HTTP(S) 图片地址,或 data:image/...;base64,...;推荐 HTTPS |
content[].role | string / 可选 | 图片仅支持 reference_image 或省略;不能指定首帧 / 尾帧约束 |
duration | integer / 可选 | 默认 5;Fast 支持 5/10/15,2.5 支持 5/10/30。请使用 JSON 数字,不是字符串 |
resolution | string / 可选 | 仅 720p,默认 720p;不能传 1080p、480p 或 4K |
ratio | string / 可选 | 16:9、9:16、1:1、4:3、3:4、adaptive;默认 16:9 |
generate_audio | boolean / 建议省略 | 当前不支持 false,不能通过参数关闭生成音频;声音效果以实际模型结果为准 |
当前接入不支持 seed、callback_url、service_tier、execution_expires_after、video_url / audio_url 参考、首尾帧和取消任务。不要把火山官方所有参数直接照搬到这个兼容接入。服务端 JSON 请求体上限为 24 MiB;Base64 会增加体积,多图场景优先使用公开 HTTPS 图片地址。
最小文生视频请求
export SUB2_API_KEY='sk-YOUR_SEEDANCE_GROUP_KEY'
curl --fail-with-body --silent --show-error --max-time 90 \
'https://zhinaoapi.ai/api/v3/contents/generations/tasks' \
-H "Authorization: Bearer $SUB2_API_KEY" \
-H 'Content-Type: application/json' \
--data '{
"model": "seedance2.0fast",
"duration": 5,
"resolution": "720p",
"ratio": "16:9",
"content": [
{"type": "text", "text": "海浪轻轻拍打沙滩,固定镜头,自然光,画面平稳。"}
]
}'
Linux / macOS / Bash 使用 export;Windows PowerShell 使用 $env:SUB2_API_KEY = 'sk-...'。PowerShell 里调用 cURL 请写 curl.exe;完整 Python / Node.js 示例可以跨平台运行。
{
"id": "video_0123456789abcdef0123456789abcdef",
"status": "queued"
}
参考图视频示例
将下面占位图片地址换成实际可访问的 HTTPS 图片。用户电脑的路径、localhost、私有 IP 和需要登录 / Cookie 的图片页面不可用。图片是参考,不是保证严格匹配的第一帧;多图可添加多个相同结构的 image_url 项。
{
"model": "seedance2.5",
"duration": 5,
"resolution": "720p",
"ratio": "9:16",
"content": [
{"type": "text", "text": "参考图片中的人物在花园里缓慢转身,镜头平稳推进,保持人物外观一致。"},
{"type": "image_url", "image_url": {"url": "https://YOUR_PUBLIC_IMAGE_HOST/reference.jpg"}, "role": "reference_image"}
]
}
任务查询与响应字段
export SEEDANCE_TASK_ID='创建响应里的实际 id'
curl --fail-with-body --silent --show-error \
"https://zhinaoapi.ai/api/v3/contents/generations/tasks/$SEEDANCE_TASK_ID" \
-H "Authorization: Bearer $SUB2_API_KEY"
| 字段 / 状态 | 含义 | 客户端处理 |
|---|---|---|
id | 异步任务唯一 ID | 持久保存,避免重复创建 |
queued / running | 排队 / 生成中 | 继续间隔查询;尚未扣费 |
succeeded | 已生成视频 | 读取 content.video_url,首次成功查询计费一次 |
failed | 生成失败 | 停止轮询,保存 error.code / error.message;不扣费 |
cancelled / expired | 兼容其他上游的终态 | 停止轮询;当前接入不提供主动取消 |
content.video_url | 成功任务的视频签名地址 | 按返回的完整 URL 下载,不改查询参数 |
duration / resolution / ratio | 任务输出设置 | 可用于展示;不要依赖响应一定含 token usage |
{
"id": "video_0123456789abcdef0123456789abcdef",
"status": "succeeded",
"duration": 5,
"resolution": "720p",
"ratio": "16:9",
"content": {
"video_url": "https://dola-pool.zhinaoapi.ai/seedance-media/video_0123456789abcdef0123456789abcdef?expires=EXPIRES&signature=SIGNATURE"
}
}
¥0.50 / 条与结果保存
- 本节两款模型按成功视频条数计费,不按 token 或秒数计费。每条扣 0.5 账户余额;当前充值比例为 ¥1 = $1 站内余额,因此对应 ¥0.50。站内 $ 标记不是额外按美元汇率换算。
- 创建、排队、生成中的任务不扣费;第一次 GET 到
succeeded且返回视频地址时扣费一次。失败不扣费,重复查询同一个成功任务不重复扣费。 - 必须用客户端轮询完成结果,当前不提供回调结算。账户余额与 Key 配额都应至少覆盖一次调用;首次建议用一条 5 秒任务验证。
- 生成可能需要数分钟到十几分钟,排队与账号额度会影响速度;不承诺固定出片时间。客户端等待超时并不会取消已经提交的任务。
- 任务归属记录通常保留约 24 小时;请及时查询并下载,不要将查询端点当永久的视频仓库。成功结果的签名链接通常有效 24 小时。
- 下载链接无需 Basic 登录,也不要附带
Authorization: Bearer;签名链接本身具有读取权限。不要将完整链接发到公共日志、论坛或代码仓库。 - 链接过期且任务仍可查询时,用创建任务的同一个 Key 重新 GET 取得新链接;不要重新 POST。签名参数不能删改,下载中转不得附加管理员认证信息。
cURL:完整创建、轮询、下载
Bash 示例需要 curl 与 jq。保存为 seedance-curl.sh,设置 SUB2_API_KEY 后运行 bash seedance-curl.sh。继续已有任务时同时设置 SEEDANCE_TASK_ID;此时不会再次创建。
#!/usr/bin/env bash
# Bash + curl + jq. POST is executed at most once; GET may be retried manually.
set -euo pipefail
: "${SUB2_API_KEY:?请先设置 SUB2_API_KEY 为 Seedance 分组的 API Key}"
base='https://zhinaoapi.ai/api/v3/contents/generations/tasks'
# To resume, export SEEDANCE_TASK_ID to the saved ID before running this script.
task_id="${SEEDANCE_TASK_ID:-}"
if [[ -z "$task_id" ]]; then
if ! created=$(curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 90 \
"$base" -H "Authorization: Bearer $SUB2_API_KEY" -H 'Content-Type: application/json' \
--data '{"model":"seedance2.0fast","duration":5,"resolution":"720p","ratio":"16:9","content":[{"type":"text","text":"海浪轻轻拍打沙滩,固定镜头,自然光,画面平稳。"}]}'); then
printf '%s\n' '创建失败或响应不明确。不要自动再次 POST,请保存错误并核查。' >&2
exit 1
fi
task_id=$(printf '%s' "$created" | jq -er '.id | select(type == "string" and length > 0)')
fi
printf '任务 ID(请保存):%s\n' "$task_id"
for ((attempt=0; attempt<180; attempt++)); do
# No --retry-all-errors and no retries on the create request.
if ! result=$(curl --fail-with-body --silent --show-error --max-time 90 \
"$base/$task_id" -H "Authorization: Bearer $SUB2_API_KEY"); then
printf '%s\n' '查询失败,保留 task_id 排查;不要重新创建任务。' >&2
exit 1
fi
status=$(printf '%s' "$result" | jq -r '.status // "unknown"')
printf '任务状态:%s\n' "$status"
if [[ "$status" == 'succeeded' ]]; then
video_url=$(printf '%s' "$result" | jq -er '.content.video_url | select(type == "string" and length > 0)')
output="seedance-$task_id.mp4"
if [[ -e "$output" ]]; then
printf '输出文件已存在,请更换文件名:%s\n' "$output" >&2
exit 1
fi
# Signed URL: do not send the Sub2 API key to the download host.
curl --fail-with-body --silent --show-error --location --proto '=https' --proto-redir '=https' \
--max-time 180 "$video_url" --output "$output"
printf '视频已保存:%s\n' "$output"
exit 0
fi
case "$status" in
failed|cancelled|canceled|expired)
printf '%s\n' "$result" | jq '{status,error}'
exit 1
;;
esac
sleep 15
done
printf '%s\n' '本地等待到期;任务未必结束。用相同 API Key 和 SEEDANCE_TASK_ID 继续查询。' >&2
exit 1
Python:标准库完整示例
Python 3.9+,不需要安装第三方包。保存为 seedance-example.py;默认创建 Fast / 5 秒 / 720p 视频。程序会打印任务 ID,请立即保存。使用同一 Key 恢复查询、下载,不会再次扣同一个任务的费用。
export SUB2_API_KEY='sk-YOUR_SEEDANCE_GROUP_KEY'
python3 seedance-example.py --output demo.mp4
# 恢复已有任务;不要因等待超时再次创建
python3 seedance-example.py --task-id '保存的任务 id' --output resumed.mp4
# 可选:换 2.5,添加实际公开参考图
python3 seedance-example.py --model seedance2.5 --duration 5 --ratio 9:16 \
--image-url 'https://YOUR_PUBLIC_IMAGE_HOST/reference.jpg' --output reference.mp4
#!/usr/bin/env python3
"""Python 3.9+; no third-party packages. Never automatically repeat POST."""
import argparse
import json
import os
import shutil
import time
from pathlib import Path
from urllib.error import HTTPError, URLError
from urllib.parse import quote, urlsplit
from urllib.request import Request, urlopen
ORIGIN = "https://zhinaoapi.ai"
ENDPOINT = ORIGIN + "/api/v3/contents/generations/tasks"
class APIError(RuntimeError):
def __init__(self, status, body):
super().__init__(f"HTTP {status}: {body[:1000]}")
self.status = status
def api(method, url, key, body=None):
encoded = json.dumps(body, ensure_ascii=False).encode("utf-8") if body is not None else None
headers = {"Authorization": "Bearer " + key, "Accept": "application/json"}
if encoded is not None:
headers["Content-Type"] = "application/json"
request = Request(url, data=encoded, headers=headers, method=method)
try:
with urlopen(request, timeout=90) as response:
return json.load(response)
except HTTPError as error:
raise APIError(error.code, error.read(65536).decode("utf-8", errors="replace")) from None
def create_once(key, model, duration, ratio, prompt, image_url):
content = [{"type": "text", "text": prompt}]
if image_url:
content.append({"type": "image_url", "image_url": {"url": image_url}, "role": "reference_image"})
body = {"model": model, "duration": duration, "resolution": "720p", "ratio": ratio, "content": content}
try:
result = api("POST", ENDPOINT, key, body)
except Exception as error:
raise RuntimeError(
"创建任务失败或响应不明确。不要自动再次 POST;上游可能已经接受任务。"
"请保存错误并向客服核查。 " + str(error)
) from None
task_id = result.get("id")
if not isinstance(task_id, str) or not task_id:
raise RuntimeError("创建响应缺少任务 ID;不要重复提交,请核查。")
return task_id
def wait_for_video(key, task_id, minutes):
url = ENDPOINT + "/" + quote(task_id, safe="")
deadline = time.monotonic() + minutes * 60
while time.monotonic() < deadline:
try:
result = api("GET", url, key)
except APIError as error:
if error.status not in (408, 429, 500, 502, 503, 504):
raise
print("查询暂不可用,20 秒后重试 GET;不会创建新任务。", flush=True)
time.sleep(20)
continue
except (URLError, TimeoutError):
print("查询网络异常,20 秒后重试 GET。", flush=True)
time.sleep(20)
continue
status = result.get("status", "unknown")
print("任务状态:", status, flush=True)
if status == "succeeded":
video_url = result.get("content", {}).get("video_url")
if not isinstance(video_url, str) or not video_url:
raise RuntimeError("成功响应缺少 content.video_url;请联系支持。")
return video_url
if status in ("failed", "cancelled", "canceled", "expired"):
raise RuntimeError("任务未成功:" + json.dumps(result.get("error", status), ensure_ascii=False))
time.sleep(15)
raise TimeoutError("本地等待到期,任务未必结束;保存 ID,下次使用 --task-id 继续查询,不要新建。")
def download(video_url, filename):
# Signed media URLs already authorize access. Never send the Sub2 API key.
if urlsplit(video_url).scheme != "https":
raise RuntimeError("拒绝非 HTTPS 视频地址。")
target = Path(filename)
if target.exists():
raise FileExistsError("输出文件已存在;请选择新文件名:" + str(target))
try:
with urlopen(Request(video_url), timeout=180) as response, target.open("xb") as output:
content_type = response.headers.get("Content-Type", "").split(";", 1)[0].strip()
if content_type not in ("video/mp4", "application/octet-stream"):
raise RuntimeError("视频下载返回了意外类型:" + content_type)
shutil.copyfileobj(response, output)
except HTTPError as error:
if error.code == 403:
raise RuntimeError("签名链接可能已过期;用同一个 Key 重新 GET 任务获取新链接,不要 POST。") from None
raise
print("视频已保存:", target, flush=True)
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--task-id", help="恢复查询已有任务,不创建新任务")
parser.add_argument("--model", choices=("seedance2.0fast", "seedance2.5"), default="seedance2.0fast")
parser.add_argument("--duration", type=int, default=5)
parser.add_argument("--ratio", choices=("16:9", "9:16", "1:1", "4:3", "3:4", "adaptive"), default="16:9")
parser.add_argument("--prompt", default="海浪轻轻拍打沙滩,固定镜头,自然光,画面平稳。")
parser.add_argument("--image-url", help="可选:无需登录的公网 HTTPS 参考图 URL")
parser.add_argument("--output", default="seedance-output.mp4")
parser.add_argument("--wait-minutes", type=int, default=45)
args = parser.parse_args()
key = os.getenv("SUB2_API_KEY", "").strip()
if not key:
parser.error("请先设置 SUB2_API_KEY 环境变量为绑定 Seedance 分组的 Key")
allowed = (5, 10, 15) if args.model == "seedance2.0fast" else (5, 10, 30)
if args.duration not in allowed or args.wait_minutes <= 0:
parser.error("模型时长不支持,或等待时间不是正数")
task_id = args.task_id or create_once(key, args.model, args.duration, args.ratio, args.prompt, args.image_url)
print("任务 ID(请立即保存):", task_id, flush=True)
video_url = wait_for_video(key, task_id, args.wait_minutes)
download(video_url, args.output)
if __name__ == "__main__":
main()
Node.js:无需 npm 的完整示例
Node.js 20+,使用内置 fetch。保存为 seedance-example.mjs,设置 Key 后运行。修改模型 / 时长可设置 SEEDANCE_MODEL、SEEDANCE_DURATION;参考图用 SEEDANCE_IMAGE_URL,比例用 SEEDANCE_RATIO。
export SUB2_API_KEY='sk-YOUR_SEEDANCE_GROUP_KEY'
node seedance-example.mjs
# 恢复查询已创建任务,不会 POST 新任务
export SEEDANCE_TASK_ID='保存的任务 id'
export SEEDANCE_OUTPUT='resumed.mp4'
node seedance-example.mjs
// Node.js 20+; no npm dependencies. Never automatically repeat POST.
import { createWriteStream, existsSync } from 'node:fs';
import { pipeline } from 'node:stream/promises';
import { Readable } from 'node:stream';
const endpoint = 'https://zhinaoapi.ai/api/v3/contents/generations/tasks';
const key = (process.env.SUB2_API_KEY || '').trim();
const taskToResume = process.env.SEEDANCE_TASK_ID || '';
const model = process.env.SEEDANCE_MODEL || 'seedance2.0fast';
const duration = Number(process.env.SEEDANCE_DURATION || 5);
const imageUrl = process.env.SEEDANCE_IMAGE_URL || '';
const output = process.env.SEEDANCE_OUTPUT || 'seedance-output.mp4';
const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
class APIError extends Error {
constructor(status, body) {
super(`HTTP ${status}: ${body.slice(0, 1000)}`);
this.status = status;
}
}
async function api(method, url, body) {
const response = await fetch(url, {
method,
headers: {
Authorization: `Bearer ${key}`,
Accept: 'application/json',
...(body ? { 'Content-Type': 'application/json' } : {}),
},
body: body ? JSON.stringify(body) : undefined,
signal: AbortSignal.timeout(90_000),
});
const raw = await response.text();
if (!response.ok) throw new APIError(response.status, raw);
return JSON.parse(raw);
}
async function createOnce() {
const content = [{ type: 'text', text: process.env.SEEDANCE_PROMPT || '海浪轻轻拍打沙滩,固定镜头,自然光,画面平稳。' }];
if (imageUrl) content.push({ type: 'image_url', image_url: { url: imageUrl }, role: 'reference_image' });
let result;
try {
result = await api('POST', endpoint, {
model, duration, resolution: '720p', ratio: process.env.SEEDANCE_RATIO || '16:9', content,
});
} catch (error) {
throw new Error(`创建失败或响应不明确,禁止自动再次 POST;请保存错误并核查。 ${error.message}`);
}
if (typeof result.id !== 'string' || !result.id) throw new Error('创建响应缺少任务 ID;不要重复提交。');
return result.id;
}
async function poll(taskId) {
const statusUrl = `${endpoint}/${encodeURIComponent(taskId)}`;
const deadline = Date.now() + 45 * 60_000;
while (Date.now() < deadline) {
let result;
try {
result = await api('GET', statusUrl);
} catch (error) {
const retryable = error instanceof APIError
? [408, 429, 500, 502, 503, 504].includes(error.status)
: error instanceof TypeError || ['TimeoutError', 'AbortError'].includes(error.name);
if (!retryable) throw error;
console.log('查询暂不可用,20 秒后重试 GET;不会创建新任务。');
await sleep(20_000);
continue;
}
console.log('任务状态:', result.status || 'unknown');
if (result.status === 'succeeded') {
if (!result.content?.video_url) throw new Error('成功响应缺少 content.video_url;请联系支持。');
return result.content.video_url;
}
if (['failed', 'cancelled', 'canceled', 'expired'].includes(result.status)) {
throw new Error(`任务未成功:${JSON.stringify(result.error || result.status)}`);
}
await sleep(15_000);
}
throw new Error('本地等待到期,任务未必结束;保留 ID,下次设置 SEEDANCE_TASK_ID 继续查询,不要新建。');
}
async function download(url) {
if (new URL(url).protocol !== 'https:') throw new Error('拒绝非 HTTPS 视频地址。');
if (existsSync(output)) throw new Error(`输出文件已存在,请更换 SEEDANCE_OUTPUT:${output}`);
// Signed URLs already authorize access. Do not send the Sub2 API key.
const response = await fetch(url, { signal: AbortSignal.timeout(180_000) });
if (response.status === 403) throw new Error('签名链接可能过期;重新 GET 任务获取新链接,不要 POST。');
if (!response.ok || !response.body) throw new Error(`下载失败 HTTP ${response.status}`);
const mime = (response.headers.get('content-type') || '').split(';')[0].trim();
if (!['video/mp4', 'application/octet-stream'].includes(mime)) throw new Error(`意外下载类型:${mime}`);
await pipeline(Readable.fromWeb(response.body), createWriteStream(output, { flags: 'wx' }));
console.log('视频已保存:', output);
}
async function main() {
if (!key) throw new Error('请先设置 SUB2_API_KEY,为绑定 Seedance 分组的 Key。');
const durations = { 'seedance2.0fast': [5, 10, 15], 'seedance2.5': [5, 10, 30] };
if (!durations[model]?.includes(duration)) throw new Error('模型或时长不支持。');
const taskId = taskToResume || await createOnce();
console.log('任务 ID(请立即保存):', taskId);
await download(await poll(taskId));
}
main().catch(error => { console.error(error.message); process.exitCode = 1; });
错误处理与常见问题
| 情况 | 排查与处理 |
|---|---|
| 401 / 鉴权失败 | 检查 Key 拼写、Bearer 请求头、Key 是否停用 / 过期;不要使用上游 Cookie 或网站登录 token |
| 403 / 权限、配额或余额问题 | 检查 API Key 是否绑定 Seedance 分组、余额和 Key 配额是否充足,以返回错误正文为准;下载 403 则先排查签名过期 |
| 400 / 422 / 参数不支持 | 核对模型 ID、整数时长、720p、比例、content 数组;删掉不支持的音视频参考和高级参数 |
| 404 / 查不到任务 | 核对 ID,必须使用原创建任务的同一个用户、Key 和分组;任务归属记录可能已过期 |
| 405 / 取消请求 | 当前不支持 DELETE 取消。停止本地等待不等于取消上游任务 |
| 429 / 暂时限流 | 降低并发,延长查询间隔;免费额度或账号池限制也会影响请求。POST 不自动重试 |
| 502 / 503 / 暂无可用资源 | 可能是上游、账号池或网络暂不可用,保留正文和时间。仅 GET 可在退避后重试;POST 是否接受不明确时先核查 |
HTTP 200 但 status=failed | 这是任务业务失败,不是生成成功。读取 error 并停止轮询;不扣费,不要用下载字段判定成功 |
| 一直 queued / running | 异步视频等待可能较长,继续用原 ID 间隔查询;不要反复创建相同任务 |
| 视频 URL 打不开 / 403 | 使用完整签名地址,不删查询参数,不加 Basic;仍在查询有效期时重新 GET 任务获得新链接 |
通用聊天客户端若只支持 messages 和流式聊天,不能直接用 Seedance 视频模型“发聊天”生成视频。请使用上述任务 API,或自行实现支持创建任务、轮询和下载的视频界面。本节参数适用于当前 Seedance 分组接入;其他站点和官方 Ark 的参数、取消、计费能力不能据此推定相同。
教程更新时间:2026-10-05(北京时间)。实际可用模型、价格、额度与调用限制以控制台 / 模型广场和实时 API 返回为准。
请求格式
普通 OpenAI Compatible 调用推荐使用 POST /v1/chat/completions;支持新协议的 Codex / Agent 类工具可使用 POST /v1/responses;图片能力使用 Images 端点或 Responses 图像工具。不同客户端字段支持不完全一致,配置前请确认客户端实际支持的协议。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 模型标识,如 gpt-5.6-sol、gpt-image-2、claude-opus-4-8、grok-4.5。请填写完整模型 ID,不要填写网址或分组名。 |
messages | array | 是 | 对话消息数组,每条包含 role 和 content |
temperature | number | 否 | 采样温度,范围 0-2,默认 1。数值越低输出越确定 |
max_tokens | integer | 否 | 最大输出 token 数 |
stream | boolean | 否 | 是否启用流式输出,默认 false |
top_p | number | 否 | 核采样概率,范围 0-1 |
frequency_penalty | number | 否 | 频率惩罚,范围 -2 到 2 |
presence_penalty | number | 否 | 存在惩罚,范围 -2 到 2 |
消息角色
| 角色 | 说明 |
|---|---|
system | 系统指令,设定 AI 的行为方式和背景。放在消息数组的第一条。 |
user | 用户发送的消息内容。 |
assistant | AI 助手的回复,用于提供对话历史上下文。 |
完整请求示例
{
"model": "gpt-5.5",
"messages": [
{
"role": "system",
"content": "你是一位专业的技术文档撰写助手。"
},
{
"role": "user",
"content": "请帮我写一段 Python 快速排序代码。"
}
],
"temperature": 0.7,
"max_tokens": 2048,
"stream": false
}
GPT Image 2 图片生成示例
生成图片时使用图片模型和 Images 端点。图片编辑可使用 /v1/images/edits。图片能力、价格和可用分组可能调整,请查看 API 价格页,实际扣费以控制台用量记录为准。
图片模型按当前计费模式和实际用量扣费。OpenAI/Codex 兼容分组的图片生成和编辑能力以当前模型列表为准;请使用支持对应图片模型的 API Key 分组。最终扣费以控制台用量记录为准。
curl https://api.zhinaoapi.ai/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-YOUR_API_KEY" \
-d '{
"model": "gpt-image-2",
"prompt": "一张未来感城市夜景,霓虹灯,电影感构图",
"size": "1024x1024",
"quality": "high",
"n": 1
}'
响应格式
标准响应(非流式)
{
"id": "chatcmpl-abc123def456",
"object": "chat.completion",
"created": 1781654400,
"model": "gpt-5.5",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "以下是 Python 快速排序的实现..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 42,
"completion_tokens": 256,
"total_tokens": 298
}
}
流式响应(SSE)
当请求中设置 "stream": true 时,响应会以 Server-Sent Events 格式逐块返回。流式接口对网络、客户端和反代超时更敏感,建议客户端正确处理断线重试、[DONE] 结束标记和错误事件:
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"以下"},"finish_reason":null}]}
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"是"},"finish_reason":null}]}
data: [DONE]
Chat Completions 流式响应通常以 data: [DONE] 结束;Responses 流式响应会返回 response.* 事件。若客户端提示 stream disconnected before completion,请优先检查客户端是否支持对应接口、请求体是否过大、网络是否中断以及是否使用了正确的 API 域名。
错误码说明
当请求发生错误时,API 将返回对应的 HTTP 状态码和 JSON 格式的错误信息:
{
"error": {
"message": "具体的错误描述信息",
"type": "error_type",
"code": "error_code"
}
}
| 状态码 | 含义 | 说明与处理建议 |
|---|---|---|
| 400 | 请求参数错误 | 请求体格式不正确或缺少必需参数。请检查 JSON 格式、model 字段是否正确、messages 数组是否为空。 |
| 401 | 身份认证失败 | API Key 无效、已过期或未提供。请检查 Authorization 请求头格式是否为 Bearer sk-xxx。 |
| 403 | 权限不足 | 当前 API Key 无权访问所请求的模型或资源。请确认账户余额充足且未被禁用。 |
| 404 | 模型或接口不存在 | 常见原因是 model 填成了网址、分组名,或客户端请求了平台未开放的路径。请核对模型 ID 和 Base URL。 |
| 413 | 请求体过大 | 请求中包含过多上下文、日志、文件内容或内联图片。请先压缩上下文、减少粘贴内容,或拆分任务后重试。 |
| 429 | 请求过于密集 | 短时间内请求过多。建议实现指数退避重试策略,或适当降低并发数。通常等待数秒后重试即可。 |
| 500 | 服务器内部错误 | 服务端出现未预期的异常。此类错误通常为暂时性故障,建议稍后重试。如持续出现,请联系技术支持。 |
| 502 | 上游通道异常 | 网关已收到请求,但上游账号、代理、模型服务或连接握手失败。通常可稍后重试;若连续出现,请在控制台查看渠道状态或联系技术支持。 |
| 503 | 服务暂时不可用 | 模型服务可能过载、维护,或暂时没有可调度账号。系统会从当前可调度账号中选择上游;若全部不可用,请等待片刻后重试。 |
| 504 | 网关超时 | 长上下文、慢模型或网络抖动可能导致超时。建议减少请求体、开启流式输出,或稍后重试。 |
对于 429、500、502、503、504 错误,建议实现自动重试机制:首次等待 1 秒,之后每次翻倍,最多重试 3 次。对于 400、401、403、404、413,优先检查参数、权限、模型名和请求体大小,盲目重试通常无法解决。
计费说明
充值与余额
账户余额按实际用量扣减,充值开放状态看控制台。调用前请确认账户余额、API Key 所属分组与目标模型;调用后的实际用量和扣费可在控制台日志中查询。
截至 2026-07-18 后台按 ¥1 = $1 计入余额,最低充值金额为 ¥1,已配置支付宝和 0.5% 手续费。此类数值没有匿名公开接口可供文档实时读取,付款前必须以控制台订单确认页显示的实付金额与到账余额为准。
分组倍率说明
同一模型在不同 API Key 分组中可能使用不同倍率和计费规则。创建或切换 API Key 时,请确认它绑定到正确分组。API 价格页 按分组展示当前模型价格、计费单位和倍率;请结合该页面与控制台用量记录核对费用。
Codex / OpenAI 模型计费
Codex / OpenAI 兼容模型按实际用量和 API Key 所属分组的当前计费规则扣减余额。输入、输出和缓存等计费项请查看 API 价格页;不同模型的计费模式可能不同。
Grok 模型计费
Grok 当前通过 Grok 分组按量使用,文本请求按 Token 和分组倍率扣费;图片按生成张数与质量规格计费,视频按时长和分辨率计费。不同模型和媒体规格的实际费用以控制台用量记录为准。
Claude 模型计费
Claude 系列适合 Claude Code、Claude 桌面客户端、VS Code / JetBrains 插件、Cherry Studio、ChatBox、LobeChat 等客户端使用。可用模型取决于 API Key 所属分组,输入、输出及缓存等当前价格请查看 API 价格页。
Claude 通道依赖上游账号池和代理链路。可用模型、排队情况和通道状态会随上游资源变化,请以控制台模型列表和渠道状态为准。
模型实时价格
查看完整 API 价格,按分组、模型和计费方式查询当前费率。价格页直接读取后台公开价格,后台调整后页面会自动刷新;本接入文档不另存一份模型价格表。
图片模型计费
图片模型支持 /v1/images/generations、/v1/images/edits 和部分 Responses 图像工具。是否可用、如何扣费、支持哪些尺寸,请以当前分组和控制台用量记录为准。
先按客户端所需的模型和能力选择 API Key 分组,再查看对应模型的计费单位。首次接入可用少量请求验证效果,并在控制台用量日志核对实际扣费。
代码示例
Python(使用 OpenAI SDK)
首先安装 OpenAI Python SDK:
pip install openai
from openai import OpenAI
client = OpenAI(
api_key="sk-YOUR_API_KEY",
base_url="https://api.zhinaoapi.ai/v1"
)
response = client.chat.completions.create(
model="gpt-5.5",
messages=[
{"role": "system", "content": "你是一个有帮助的AI助手。"},
{"role": "user", "content": "用Python实现一个二分查找算法。"}
],
temperature=0.7,
max_tokens=1024
)
print(response.choices[0].message.content)
Node.js(使用 OpenAI SDK)
首先安装 OpenAI Node.js SDK:
npm install openai
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: 'sk-YOUR_API_KEY',
baseURL: 'https://api.zhinaoapi.ai/v1',
});
async function main() {
const completion = await client.chat.completions.create({
model: 'gpt-5.5',
messages: [
{ role: 'system', content: '你是一个有帮助的AI助手。' },
{ role: 'user', content: '用JavaScript实现一个防抖函数。' }
],
temperature: 0.7,
max_tokens: 1024,
});
console.log(completion.choices[0].message.content);
}
main();
cURL
curl -X POST https://api.zhinaoapi.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-YOUR_API_KEY" \
-d '{
"model": "gpt-5.4-mini",
"messages": [
{"role": "system", "content": "你是一个有帮助的AI助手。"},
{"role": "user", "content": "什么是量子计算?请用通俗的语言解释。"}
],
"temperature": 0.7,
"max_tokens": 512
}'
流式输出示例
Python 流式输出
from openai import OpenAI
client = OpenAI(
api_key="sk-YOUR_API_KEY",
base_url="https://api.zhinaoapi.ai/v1"
)
stream = client.chat.completions.create(
model="gpt-5.5",
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)
print() # 换行
Node.js 流式输出
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: 'sk-YOUR_API_KEY',
baseURL: 'https://api.zhinaoapi.ai/v1',
});
async function main() {
const stream = await client.chat.completions.create({
model: 'gpt-5.5',
messages: [
{ role: 'user', content: '写一首关于春天的七言绝句。' }
],
stream: true,
});
for await (const chunk of stream) {
const content = chunk.choices[0]?.delta?.content;
if (content) {
process.stdout.write(content);
}
}
console.log();
}
main();
cURL 流式输出
curl -X POST https://api.zhinaoapi.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-YOUR_API_KEY" \
-N \
-d '{
"model": "gpt-5.5",
"messages": [
{"role": "user", "content": "你好"}
],
"stream": true
}'
Claude Code 接入指南
Claude Code 是命令行 AI 编程助手。推荐优先在「API 密钥」页面使用一键接入脚本,脚本会按当前系统写入 Base URL 和 API Key;下面的环境变量方式适合手动配置或排查问题。
配置方法
在您的终端环境中设置以下环境变量:
Linux / macOS
# 将以下内容添加到 ~/.bashrc 或 ~/.zshrc
export ANTHROPIC_BASE_URL="https://api.zhinaoapi.ai"
export ANTHROPIC_API_KEY="sk-YOUR_API_KEY"
# 使配置生效
source ~/.bashrc # 或 source ~/.zshrc
Windows (PowerShell)
# 临时设置(当前会话有效)
$env:ANTHROPIC_BASE_URL = "https://api.zhinaoapi.ai"
$env:ANTHROPIC_API_KEY = "sk-YOUR_API_KEY"
# 永久设置(写入用户环境变量)
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.zhinaoapi.ai", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-YOUR_API_KEY", "User")
Windows (CMD)
:: 永久设置
setx ANTHROPIC_BASE_URL "https://api.zhinaoapi.ai"
setx ANTHROPIC_API_KEY "sk-YOUR_API_KEY"
验证配置
配置完成后,直接启动 Claude Code 即可:
# 启动 Claude Code
claude
# 或在项目目录中启动
cd your-project && claude
如果一切配置正确,Claude Code 将通过本平台的网关与 Claude 模型通信。您可以像平常一样使用所有 Claude Code 功能,包括代码编辑、项目分析、命令执行等。
Claude Code 调用的是 Claude 系列模型。请确认 API Key 所属分组支持目标模型,并在控制台查看余额、用量和通道状态;当前费率可查看 API 价格页。
请确保 ANTHROPIC_BASE_URL 设置为 https://api.zhinaoapi.ai(不含 /v1 后缀),Claude Code 会自动拼接路径。ANTHROPIC_API_KEY 使用您在本平台生成的 API Key。
VS Code 插件接入
VS Code、Cursor、Trae 等 IDE 类工具通常支持 OpenAI Compatible 接入。若工具内有 Chat / Responses 两种模式,请先确认工具版本是否真正支持 Responses;不确定时优先选择 Chat Completions。
A) Continue 插件(推荐)
Continue 支持代码补全、对话和重构等功能。接入时使用 OpenAI Compatible 配置即可。
安装 Continue 插件
打开 VS Code,点击左侧扩展图标(或按 Ctrl+Shift+X),在搜索框中输入 Continue,找到由 Continue.dev 发布的插件并点击「安装」。
打开配置文件
安装完成后,点击左侧边栏的 Continue 图标打开侧边栏,然后点击底部的 齿轮图标(设置),即可打开 config.json 配置文件。
填写模型配置
在 config.json 中添加以下配置,将 sk-YOUR_API_KEY 替换为您的实际密钥:
{
"models": [
{
"title": "GPT-5.6 Sol",
"provider": "openai",
"model": "gpt-5.6-sol",
"apiBase": "https://api.zhinaoapi.ai/v1",
"apiKey": "sk-YOUR_API_KEY"
},
{
"title": "Claude Opus 4.8",
"provider": "openai",
"model": "claude-opus-4-8",
"apiBase": "https://api.zhinaoapi.ai/v1",
"apiKey": "sk-YOUR_API_KEY"
}
]
}
您可以在 models 数组中添加多个模型配置,在使用时随时切换。provider 统一填 openai 即可。Claude 模型能否在该插件中稳定使用,取决于插件是否完整兼容对应协议。
开始使用
保存配置后,在 Continue 侧边栏的模型下拉列表中选择您配置的模型,即可在编辑器中直接与 AI 对话、生成代码、解释代码或进行重构。按 Ctrl+L 可快速打开 Continue 对话框。
B) Cline 插件
Cline 类 Agent 插件会读取项目文件、提交较大的上下文并执行多轮工具调用。若请求体过大导致 413,请先压缩上下文、减少日志粘贴或拆分任务。
安装 Cline 插件
在 VS Code 扩展商店搜索 Cline,找到插件并安装。安装后左侧边栏会出现 Cline 图标。
配置 API 提供商
点击 Cline 侧边栏图标,在顶部设置区域将 API Provider 切换为 OpenAI Compatible。
开始使用
配置完成后,在 Cline 对话框中输入您的需求即可。Cline 可以自动分析项目结构、编辑代码文件、运行终端命令,是非常强大的 AI 编程搭档。
Continue 适合日常代码补全和对话辅助,Cline 类工具更擅长自主完成复杂编码任务。若出现 502、握手失败或流式中断,请先查看渠道状态并降低并发。
JetBrains 插件接入
如果您使用 IntelliJ IDEA、PyCharm、WebStorm 等 JetBrains 系列 IDE,可以通过支持 OpenAI Compatible 的插件接入本平台。
CodeGPT 插件配置
安装 CodeGPT 插件
打开 JetBrains IDE,进入 Settings(Ctrl+Alt+S)→ Plugins → Marketplace,搜索 CodeGPT 并安装。安装后需重启 IDE。
配置自定义 API
重启后进入 Settings → Tools → CodeGPT,在服务提供商中选择 Custom OpenAI,然后填写以下信息:
模型名称请填写控制台可选的完整模型 ID,如 gpt-5.6-sol、gpt-5.6-luna、gpt-image-2、claude-opus-4-8 等。若插件不支持 Claude 或 Responses,请改用 Chat Completions 模式。
开始使用
配置完成后,您可以在编辑器中右键选择 CodeGPT 功能,或使用快捷键打开 AI 对话窗口。支持代码生成、代码解释、Bug 修复等常用功能。
Cherry Studio 接入
Cherry Studio 适合日常多模型对话、Prompt 管理和知识库场景。接入时请选择 OpenAI Compatible / 自定义服务商,并使用 API 专用域名。
下载安装
前往 Cherry Studio 官网 下载适合您操作系统的安装包(支持 Windows、macOS、Linux),完成安装并打开应用。
添加自定义服务商
打开 Cherry Studio,进入 设置 → 模型服务商,点击 添加自定义服务商,填写以下信息:
添加模型
在刚添加的服务商下方,点击 添加模型,手动输入模型名称(如 gpt-5.6-sol、gpt-5.6-luna、gpt-image-2、claude-opus-4-8),或点击「获取模型列表」自动拉取可用模型。
开始对话
返回主界面,在顶部的模型选择器中切换到您刚添加的模型,即可开始对话。Cherry Studio 支持多轮对话、Markdown 渲染、代码高亮等功能。
Cherry Studio 支持同时配置多个服务商和模型,您可以在对话中随时切换模型进行对比。还支持设置系统提示词、调整温度等参数。
ChatBox 接入
ChatBox 是跨平台 AI 桌面客户端,适合普通聊天和轻量多模型使用。请注意不同版本的 Base URL 填写方式略有差异。
下载安装
前往 ChatBox 官网 下载对应平台的客户端,安装后打开应用。
配置 AI 提供商
打开 ChatBox,进入 设置 → AI 模型提供商,选择 OpenAI API Compatible,然后填写以下信息:
如果 ChatBox 的字段名称是 API Host,通常填写 https://api.zhinaoapi.ai,由客户端自动拼接 /v1;如果字段名称是 Base URL 或 API URL,并要求完整路径,则填写 https://api.zhinaoapi.ai/v1。不要填写官网域名 https://zhinaoapi.ai。
开始使用
配置完成后,返回主界面即可开始与 AI 对话。ChatBox 支持多轮对话、Markdown 渲染、代码高亮,还可以创建多个对话窗口同时进行不同话题的讨论。
LobeChat 接入
LobeChat 支持 Web 部署和本地运行,适合多助手、多模型和知识库场景。接入时请选择 OpenAI 兼容配置,并确认部署环境可以访问 api.zhinaoapi.ai。
访问 LobeChat
您可以直接访问 LobeChat 在线版,也可以通过 Docker 自行部署。本地部署方式请参考 LobeChat GitHub 仓库。
配置语言模型
进入 LobeChat 后,点击左下角 设置 → 语言模型 → OpenAI,进行以下配置:
选择模型并对话
保存设置后,在对话界面顶部的模型选择器中选择您想使用的模型(如 gpt-5.6-sol、gpt-image-2 等),即可开始对话。若部署在服务器端,请确认服务器出口网络能稳定访问 API 域名。
如果在模型列表中没有看到您需要的模型,可以在设置中开启「自定义模型名称」功能,手动输入完整模型 ID(如 gpt-5.6-terra、claude-opus-4-8)即可使用。
更多客户端
除了以上工具,只要客户端支持自定义 OpenAI Compatible 地址,通常都可以接入本平台。配置时重点看它要求填写的是 Host、Base URL 还是完整 Endpoint。
OpenCat
iOS / macOS 原生 AI 客户端,界面精美,支持自定义 API 地址和多模型切换。
BotGPT
iOS 平台的 AI 聊天客户端,支持 OpenAI 兼容 API,操作简单直观。
NextChat
开源 Web 聊天应用,支持一键部署到 Vercel,自带 Prompt 模板和对话管理。
LibreChat
功能强大的开源自托管聊天平台,支持多 AI 服务商、插件、文件上传等高级功能。
通用配置如下;如果客户端会自动拼接 /v1,Base URL 可填写 https://api.zhinaoapi.ai;如果客户端要求完整 OpenAI Base URL,则填写 https://api.zhinaoapi.ai/v1。
如果您在接入过程中遇到任何问题,请优先核对上方接入配置、模型名称与鉴权方式。
兑换码使用教程
如果您获得了兑换码,可以按照以下步骤兑换余额或并发数到您的账户。
登录平台
打开浏览器访问 https://zhinaoapi.ai,使用您的账号登录平台。
进入兑换页面
登录后,点击左侧菜单中的「兑换码」选项,或直接访问兑换页面。
粘贴兑换码
在兑换码输入框中,粘贴您获得的兑换码。
点击兑换
确认兑换码无误后,点击「兑换」按钮提交。
兑换完成
兑换成功后,余额或并发数会自动增加到您的账户,您可以在仪表盘查看更新后的余额。
- 兑换码区分大小写,建议直接复制粘贴
- 每个兑换码只能使用一次
- 兑换码有有效期,请在有效期内使用
- 如果兑换失败,请检查兑换码是否正确或联系客服
常见问题
gpt-5.6-sol、claude-opus-4-8、grok-4.5、grok-imagine-image、grok-imagine-video 等。使用时请填写完整模型 ID;如果某个密钥看不到对应模型,请检查该 API Key 绑定的分组权限。Grok 的完整模型和端点请查看 Grok 接入指南。/v1/chat/completions、/v1/responses 和 Images 等常用接口。多数 OpenAI SDK 只需修改 base_url 和 api_key 即可接入;但不同客户端对 Chat、Responses、Images、tools 的支持程度不同,遇到异常时请先确认客户端实际调用的是哪一种协议。/v1/chat/completions;Codex、Agent 类工具、新版 OpenAI SDK 如果明确支持 Responses,就用 /v1/responses;Claude Code 或 Claude 兼容客户端通常走 /v1/messages。如果工具里只有 OpenAI Compatible 选项,就先用 Chat Completions;如果工具明确要求 Responses,再切 Responses。Authorization: Bearer sk-xxx,注意 Bearer 后面有一个空格;(3) 在控制台确认该令牌是否仍处于「启用」状态且未被删除;(4) 确认账户余额大于 0。https://zhinaoapi.ai;API、SDK、IDE 插件和桌面客户端请使用 https://api.zhinaoapi.ai 或 https://api.zhinaoapi.ai/v1。平台会尽量优化线路,但客户端本地网络、代理软件、公司防火墙和请求体大小都会影响速度。/v1/chat/completions 或 /v1/responses;Claude 兼容客户端请确认是否支持对应的 Messages 工具调用格式。© 2026 智脑API平台 | 提供高质量 AI 模型 API 服务