集成文档
Silk Road AI 完全 OpenAI 兼容(同时提供 Anthropic 兼容协议), 所有支持自定义 base URL 的客户端 / SDK 一行替换即可接入。
没有 key?先 注册一个账户 — 30 秒拿到能用的 sk-…。
通用配置
01Cursor
官方文档 → cursor.com/docsCursor 设置里有 OpenAI 自定义模型入口,填入 base URL + API Key + 模型名即可。 各版本 Cursor 设置面板路径偶有调整,以官方最新文档为准。
- Override OpenAI Base URLhttps://ai.silkroadai.io/v1
- OpenAI API Keysk-… (portal /keys)
- Model namegpt-5.4 / claude-sonnet-4-6 / 等
注:Cursor 的「自定义 OpenAI 模型」开关位置随版本变动,建议直接搜索 Cursor docs 中的「OpenAI」关键字定位最新指引。
02Cline (VS Code)
官方文档 → docs.cline.botCline 在 VS Code 设置里支持 OpenAI Compatible provider,base URL + API Key + 手填模型 ID 即可。具体下拉选项名称以官方最新文档为准。
- API ProviderOpenAI Compatible(下拉选项)
- Base URLhttps://ai.silkroadai.io/v1
- API Keysk-… (portal /keys)
- Model IDgpt-5.4
03Continue (VS Code / JetBrains)
官方文档 → docs.continue.devContinue 通过 config.yaml / config.json 管理模型。OpenAI provider 加一条即可:
models:
- name: Silk Road AI · gpt-5.4
provider: openai
apiBase: https://ai.silkroadai.io/v1
apiKey: sk-… # portal /keys
model: gpt-5.4
roles:
- chat
- edit字段名(provider / apiBase / apiKey / model)以 Continue 官方 schema 为准, 不同版本可能略有差异。模型名替换为 claude-sonnet-4-6 等亦可。
04Claude Code Desktop / CLI
官方文档 → code.claude.com/docs/en/env-varsClaude Code 通过两个环境变量切到 Anthropic 兼容的第三方网关,启动前导出即可。ANTHROPIC_AUTH_TOKEN 会以 Bearer 形式注入 Authorization 头。
# macOS / Linux
export ANTHROPIC_BASE_URL="https://ai.silkroadai.io"
export ANTHROPIC_AUTH_TOKEN="sk-…" # portal /keys
claude
# Windows PowerShell
$env:ANTHROPIC_BASE_URL = "https://ai.silkroadai.io"
$env:ANTHROPIC_AUTH_TOKEN = "sk-…"
claudeClaude Code 检测到 ANTHROPIC_BASE_URL 指向非官方主机时,默认会停用 MCP tool search;若需要可同时设置 ENABLE_TOOL_SEARCH=true。
05OpenAI Codex(CLI / IDE 插件 / 桌面 app)
官方文档 → developers.openai.com/codex/config-advancedCodex 有三个客户端形态 — 终端 CLI、IDE 插件(VS Code / Cursor / Windsurf / JetBrains)、桌面 app —— 共享同一个 ~/.codex/config.toml 配置文件和同一个底层 agent。下面的步骤 1 配置文件只需写一次,3 个客户端共用。
Codex 内置的 openai provider 默认走 OpenAI Responses API(/v1/responses),多数兼容网关不支持。要让 Codex 调 Silk Road AI 的 gpt-5.4 等模型,自定义一个 wire_api = "chat" 的 provider,使 Codex 走标准 OpenAI 兼容的 /v1/chat/completions 路径即可。
步骤 1:编辑共享配置 ~/.codex/config.toml(三客户端通用)
# Silk Road AI provider — wire_api = "chat" 走 /v1/chat/completions
model = "gpt-5.4"
model_provider = "silkroadai"
[model_providers.silkroadai]
name = "Silk Road AI"
base_url = "https://ai.silkroadai.io/v1"
env_key = "OPENAI_API_KEY"
wire_api = "chat"如果 ~/.codex/ 目录不存在,先 mkdir -p ~/.codex 再创建文件。Windows 用户路径为 %USERPROFILE%\.codex\config.toml。
步骤 2:挑你用的客户端安装 + 登录
2.1 终端 CLI
# 安装(macOS / Linux / Windows,需 Node 20+)
npm install -g @openai/codex
# 或 Homebrew(macOS): brew install --cask codex
# 启动(macOS / Linux)
export OPENAI_API_KEY="sk-…" # portal /keys
codex
# 启动(Windows PowerShell)
$env:OPENAI_API_KEY = "sk-…"
codex2.2 IDE 插件(VS Code / Cursor / Windsurf / JetBrains 全系)
- VS Code / Cursor / Windsurf: marketplace 搜
Codex – OpenAI's coding agent(发布者openai.chatgpt)。JetBrains 系(IntelliJ / PyCharm / WebStorm / Rider):marketplace 搜Codex。 - 打开 Codex 侧边栏 → 不要点 "Sign in with ChatGPT",改点 "Use API Key"。
- 粘贴 portal /keys 的
sk-…→ 确定。 - 重启 IDE / reload extension,Codex 侧边栏自动读
~/.codex/config.toml里的silkroadaiprovider 路由请求。
VS Code 内也可走 Settings → Extensions → Codex → API Key 字段粘贴 sk-…,效果等同 2 + 3 步。
2.3 桌面 app
# CLI 安装好后,内置桌面 app 子命令
codex app
# 首次打开会弹 sign-in 对话框,同 2.2 一样:
# 选 "Use API Key" → 粘贴 sk-… → 确定切换模型:把步骤 1 配置文件里的 model = "gpt-5.4" 改成任意 OpenAI 兼容模型(如 gpt-5.5、gpt-5.4-mini),保存后无需重装客户端,下次启动生效。完整清单见 /models。
⚠️ 三个客户端都不要使用 Codex 内置的 openai provider(默认 wire_api = "responses"),会收到 403 forbidden_error · OpenAI codex passthrough requires a non-empty instructions field。 必须按步骤 1 新建自定义 provider。
IDE 插件 + 桌面 app 的认证凭据缓存在 ~/.codex/auth.json(明文),换 key 时记得 rm ~/.codex/auth.json 后重新登录。
06Python(openai SDK)
官方文档 → github.com/openai/openai-python官方 openai Python 包构造函数接受 base_url + api_key(snake_case),改一行即可。
from openai import OpenAI
client = OpenAI(
base_url="https://ai.silkroadai.io/v1",
api_key="sk-…", # portal /keys
)
resp = client.chat.completions.create(
model="gpt-5.4",
messages=[
{"role": "user", "content": "你好,简短自我介绍一下。"},
],
)
print(resp.choices[0].message.content)07Node / TypeScript(openai SDK)
官方文档 → github.com/openai/openai-node官方 openai Node 包构造函数接受 baseURL + apiKey(camelCase),改一行即可。
import OpenAI from 'openai';
const client = new OpenAI({
baseURL: 'https://ai.silkroadai.io/v1',
apiKey: 'sk-…', // portal /keys
});
const resp = await client.chat.completions.create({
model: 'gpt-5.4',
messages: [
{ role: 'user', content: '你好,简短自我介绍一下。' },
],
});
console.log(resp.choices[0].message.content);08Google Gemini · 通过同一个 base URL 调用
Gemini 全家(包括最新 Nano Banana 图像生成)与 OpenAI 兼容协议接入,base URL + SDK 都不变,只需把 model 换成 Gemini 模型名即可。
- Base URLhttps://ai.silkroadai.io/v1
- Text · Pro 旗舰gemini-3.1-pro-preview
- Text · 高速 / 低成本gemini-3.1-flash-lite
- Image · Nano Banana 3 Progemini-3-pro-image-preview / nano-banana-pro-preview
- Image · Nano Banana 3.1 Flashgemini-3.1-flash-image-preview
- Image · Imagen 4 Ultraimagen-4.0-ultra-generate-001
- Videoveo-3.1-generate-preview / -fast / -lite
- Embeddinggemini-embedding-2
完整可调用清单 → /models · 图像 / 视频按官方价透传(无加价),文本同样透传,公式见 portal /pricing(暂未上线 — 表见 landing 页)。
09常见错误码
如果您调用返回非 2xx,请先看响应 body 中的 error.code 字段(比 HTTP status 更精准)。下表列出最常见的三种:
| HTTP | body error.code | 含义 / 处理 |
|---|---|---|
| 401 | invalid_authentication | API key 无效或缺 sk- 前缀。 portal /keys 重新复制完整 51 字符串。 |
| 403 | insufficient_user_quota | 账户余额不足(注:HTTP 语义上更接近 402 Payment Required;新版会改 status 码,当前以 body 的 error.code 为准)。 前往 /balance 查看余额,/pay 充值。 |
| 503 | no available channel | 模型名拼写错误,或该模型暂时下线。请用 /models 页搜索一下确认模型 id。 |
图片 API(gpt-image-2)错误码 · 对齐 OpenAI 官方(2026-08-18 起)
图片接口(/v1/images/generations / /v1/images/edits)的错误已统一为 OpenAI 官方契约:错误体恒为 {"error":{"message","type","param","code"}}四字段形,程序请按 HTTP status + error.code 分支(message 只用于人读,措辞可能调整)。官方 openai SDK 的异常分类(RateLimitError / BadRequestError 等)开箱即用。所有报错请求一律不计费。
| HTTP | error.type / error.code | 含义 / 处理 |
|---|---|---|
| 400 | user_error / moderation_blocked | 内容安全审核拒绝(提示词或参考图触发安全策略)。原样重发无效,请改写提示词或更换素材。 |
| 400 | invalid_request_error / invalid_image · invalid_value · invalid_request | 请求本身的问题:参考图损坏或格式不支持(invalid_image,多图时 message 会标注第几张)、尺寸/参数非法(invalid_value,param 指向出错字段)。修正请求后重发。 |
| 401 | invalid_request_error / invalid_api_key | API key 无效或已禁用。到 /keys 重新复制完整 key。 |
| 429 | insufficient_quota / insufficient_quota | 账户余额不足。前往 /pay 充值后重试。 |
| 429 | rate_limit_error / rate_limit_exceeded | 限流/并发排队。按响应头 Retry-After 的秒数退避后重发(密集立即重发会加剧排队)。 |
| 500 | server_error / — | 平台或上游临时错误(超时、网络抖动、空返回)。直接重试即可。 |
| 503 | server_error / — | 线路繁忙(overloaded)。稍等 30 秒以上再重试。 |
错误体示例(审核拒绝):
{
"error": {
"message": "Your request was rejected as a result of our safety system. Your request may contain content that is not allowed by our safety system.",
"type": "user_error",
"param": null,
"code": "moderation_blocked"
}
}2026-08-18 前接入的存量代码请注意:旧行为中限流曾以 408 返回、临时错误散落在 400/404/502/504、审核拒绝的 code 为 content_policy_violation,均已按上表统一;若你的代码曾按这些旧值分支,请对照迁移。
流式(SSE)调用契约:keep-alive 注释与流中断错误帧
流式调用(stream: true)时,我们的网关提供两项可靠性保障,自研 SSE 解析器需要了解:
- keep-alive 注释行:上游静默超过约 15 秒(如 reasoning 模型思考中),流里会出现
: keep-alive注释行,防止中间网络设备掐断长连接。这是 SSE 规范的标准注释(以冒号开头),OpenAI / Anthropic 官方 SDK 会自动忽略;自研解析器请跳过所有以 : 开头的行。 - 流中断错误帧:上游连接在输出中途断开时,你不会再遇到 莫名其妙的 TCP 断连 —— 流会以一个格式内合法的错误事件干净收尾。OpenAI 兼容路径收到:
data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"error"}],"error":{"message":"Upstream connection lost mid-stream; partial output may be incomplete. Please retry.","type":"silkroadai_proxy_error","code":"upstream_stream_interrupted"}}
data: [DONE]Anthropic 原生路径(/v1/messages)则收到标准的 event: error 事件。收到任一错误帧,表示已输出内容可能不完整,建议整轮重试(已产生的 token 正常计费,中断本身不额外收费)。
另外,finish_reason 在 OpenAI 兼容路径(/v1/chat/completions)上已做跨厂商归一,你只会见到标准集;Anthropic 原生 /v1/messages 与 Gemini 原生 /v1beta 不做任何改写,收到的是上游原始值(个别上游的非标值如 end_turn、MAX_TOKENS 已自动映射):
| finish_reason | 含义 |
|---|---|
| stop | 正常结束 |
| length | 到达 max_tokens 上限(reasoning 模型注意:思考也消耗预算,建议 ≥2000) |
| tool_calls / function_call | 模型发起工具调用 |
| content_filter | 上游内容过滤截断,换措辞或换模型重试 |
| error | 流中断错误帧(见上),内容可能不完整,建议整轮重试 |
10API 接入速查
想直接写代码接入?一个 API Key 同时支持四种协议路径 —— 用哪条取决于你的客户端 / SDK 习惯。 文本对话推荐 /v1/chat/completions,Gemini 2K / 4K 高清图必须走 /v1beta 原生路径(见第 12 章)。
- Base URLhttps://ai.silkroadai.io
- 认证 HeaderAuthorization: Bearer sk-…
- API Key 获取portal /keys(注册登录后创建)
| 路径 | 格式 | 用途 |
|---|---|---|
| /v1/chat/completions | OpenAI 兼容 | 所有文本 / 多模态模型(推荐主用) |
| /v1/messages | Anthropic 原生 | Claude 系列 |
| /v1/images/generations | OpenAI 图像兼容 | gpt-image-2 / DALL·E 系 |
| /v1beta/models/<model>:generateContent | Gemini 原生 | Gemini 高清图像 2K / 4K |
| GET /v1/models | OpenAI 兼容 + 扩展 | 你的 key 可用的模型 + 价格/模态元数据(见第 18 章) |
| GET /v1/key | Silk Road 扩展 | key 自查:档次 / 账户余额 / 用量(见第 19 章) |
11文本调用示例
max_tokens 设为 ≤ 4096 —— 上游有此限制,超过会返 502(已知问题,持续跟进)。在 Cline 里请选 OpenAI Compatible provider, 不要选 Anthropic provider(否则会被 SDK 锁住 max_tokens)。Python(openai SDK)
from openai import OpenAI
client = OpenAI(
api_key="sk-…", # portal /keys
base_url="https://ai.silkroadai.io/v1",
)
resp = client.chat.completions.create(
model="gpt-5.4",
max_tokens=4096, # Claude 系建议 ≤4096 避免上游 502
messages=[{"role": "user", "content": "你好,介绍一下丝绸之路"}],
)
print(resp.choices[0].message.content)Node / TypeScript(openai SDK)
import OpenAI from "openai";
const client = new OpenAI({
apiKey: "sk-…", // portal /keys
baseURL: "https://ai.silkroadai.io/v1",
});
const completion = await client.chat.completions.create({
model: "claude-sonnet-4-6",
max_tokens: 4096,
messages: [{ role: "user", content: "Hello" }],
});
console.log(completion.choices[0].message.content);curl
curl -X POST https://ai.silkroadai.io/v1/chat/completions \
-H "Authorization: Bearer sk-…" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.4",
"max_tokens": 4096,
"messages": [{"role":"user","content":"Hello"}]
}'Claude · Anthropic 原生格式(可选)
curl -X POST https://ai.silkroadai.io/v1/messages \
-H "x-api-key: sk-…" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-opus-4-7",
"max_tokens": 4096,
"messages": [{"role":"user","content":"Hello"}]
}'12Gemini 生图 · 2K / 4K 高清
| 模型 | 分辨率 | 价格 | 用途 |
|---|---|---|---|
| gemini-2.5-flash-image | ~1024×1024(1K) | ¥0.10 / 张 | 入门,经济 |
| gemini-3.1-flash-image-preview | 2048×2048(2K) | ¥0.20 / 张 | 高速 + 高清 |
| gemini-3-pro-image-preview | 4096×4096(4K) | ¥0.50 / 张 | 旗舰,最高画质 |
| gemini-3-pro-image-preview-2k | 2048×2048(2K) | ¥0.30 / 张 | 旗舰画质 · 省钱 2K(比 4K 省 40%) |
gemini-2.5-flash-image 默认出方图,gemini-3.1-flash-image-preview 与 pro 系默认出 16:9 宽幅。要正方形或其他比例 → 见下方「出图比例」。Gemini 生图 · OpenAI 兼容(推荐 — 自动 2K / 4K,返回公网 URL)
任何 OpenAI SDK / 工具改一行 base_url 即可。返回标准 chat.completion,图片是公网 URL(不是 base64),形如 https://images.silkroadai.io/gen/<uuid>.png。
# 文生图 — 用哪个模型就拿哪档分辨率(2.5=1K / 3.1=2K / 3-pro=4K)
curl https://ai.silkroadai.io/v1/chat/completions \
-H "Authorization: Bearer sk-你的KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.1-flash-image-preview",
"messages": [{ "role": "user", "content": "一只戴帽子的橘猫,水彩风格" }]
}'
# 响应 choices[0].message.content = ""传图改图:content 用 OpenAI 多模态数组,加一个 image_url(data URL 最稳;外部 http(s) URL 平台代拉,单图 ≤ 20MB,内网地址拒绝)。
{ "role": "user", "content": [
{ "type": "text", "text": "给这只猫戴一顶圣诞帽" },
{ "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,<BASE64>" } }
] }图片默认存平台图床(不保证长期保留,重要图请及时转存)。想让图片直接进自己的 bucket、用自己的域名 → 存储设置 配置自定义 OSS(R2 / 阿里 OSS / 腾讯 COS / AWS S3 / 自建;故障自动回退平台图床,不影响出图)。
/v1/chat/completions 自动翻译到 Gemini 原生接口并注入 imageConfig.imageSize—— 用哪个模型就拿哪档分辨率,无需任何额外参数(2026-06-05 起,旧式只出 1K 的问题已解决)。gemini-3-pro-image-preview-2k—— 锁定 2K 分辨率、¥0.30 / 张(比 4K 原型号省 40%),画质与 pro 旗舰同源。用法不变,把请求里的 model 换成它即可(/v1/chat/completions 与 /v1/images/generations 都支持,出图比例照常用 aspect_ratio)。出图比例
OpenAI chat/completions 接口本身没有比例参数,这条路上:文生图 走 Gemini 默认取景(2.5-flash 出方图;3.1-flash 与 pro 出 16:9 宽幅),传图改图 自动跟随输入图比例。要 精确指定比例 → 用下方 DALL·E 接口的 aspect_ratio 参数,或原生接口的 aspectRatio(完整取值见下方「出图比例白名单」)。
Gemini 原生 API · curl(2K / 4K)
# 2K — gemini-3.1-flash-image-preview
curl -X POST "https://ai.silkroadai.io/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
-H "Authorization: Bearer sk-…" \
-H "Content-Type: application/json" \
-d '{
"contents": [{ "parts": [{ "text": "A calico cat on a window sill" }] }],
"generationConfig": { "imageConfig": { "imageSize": "2K", "aspectRatio": "1:1" } }
}'
# 4K — gemini-3-pro-image-preview(把 imageSize 改成 "4K")
curl -X POST "https://ai.silkroadai.io/v1beta/models/gemini-3-pro-image-preview:generateContent" \
-H "Authorization: Bearer sk-…" \
-H "Content-Type: application/json" \
-d '{
"contents": [{ "parts": [{ "text": "A calico cat on a window sill" }] }],
"generationConfig": { "imageConfig": { "imageSize": "4K", "aspectRatio": "1:1" } }
}'响应为 Gemini 原生形:图片在 candidates[0].content.parts[].inlineData.data (base64)。
Python · Google Gen AI SDK
from google import genai
from google.genai import types
client = genai.Client(
api_key="sk-…",
http_options=types.HttpOptions(base_url="https://ai.silkroadai.io"),
)
resp = client.models.generate_content(
model="gemini-3.1-flash-image-preview",
contents="A calico cat sitting on a window sill",
config=types.GenerateContentConfig(
image_config=types.ImageConfig(image_size="2K", aspect_ratio="1:1"),
),
)
for part in resp.candidates[0].content.parts:
if part.inline_data:
open("output.jpg", "wb").write(part.inline_data.data)关于 4K 库存:gemini-3-pro-image-preview 4K 使用 Google 限额,每日有上限,超额会返 429 quota exceeded —— 不扣费、不自动降级到 2K,稍后再试或改用 2K 模型即可。
gemini-3-pro-image-preview-2k = 2K ¥0.30,gemini-3-pro-image-preview = 4K ¥0.50。给 4K 的原型号传 imageSize:"2K" 出的是 2K 图,但仍按 4K 价 ¥0.50 计费 —— 要省钱拿 2K,直接用带 -2k 的 model。Gemini 生图 · DALL·E 兼容接口(/v1/images/*)
要用 OpenAI 图像专用接口(images.generate / images.edit)或需要显式比例时用这条。返回标准 DALL·E 形 { "created":…, "data":[{ "url" | "b64_json" }] }。
# 文生图 — /v1/images/generations(显式比例)
curl https://ai.silkroadai.io/v1/images/generations \
-H "Authorization: Bearer sk-你的KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-pro-image-preview",
"prompt": "赛博朋克城市夜景,雨后霓虹",
"aspect_ratio": "16:9",
"response_format": "url"
}'
# 改图 — /v1/images/edits(multipart;image 可重复传多张参考图,也支持 JSON + data URL)
curl https://ai.silkroadai.io/v1/images/edits \
-H "Authorization: Bearer sk-你的KEY" \
-F model="gemini-3-pro-image-preview" \
-F prompt="把这两张人物合到同一个海边场景" \
-F aspect_ratio="3:2" \
-F image=@person1.png \
-F image=@person2.png| 参数 | 取值 | 说明 |
|---|---|---|
| model | 见上表 Gemini 生图模型 | 非 Gemini 模型(gpt-image-2 等)原样透传上游 |
| prompt | 文本 | 必填 |
| aspect_ratio | 见白名单;auto / 空 = 不指定 | 不在白名单 → 400;auto / 空时文生图走默认、图生图跟随输入图 |
| image | 文件(可多张)/ data URL / 外部 URL | 仅 /v1/images/edits;参考图 |
| response_format | url(默认,进图床)/ b64_json | b64_json 直返 base64 内联 |
取舍:n(多图)忽略,单次出 1 张;分辨率由 model 档决定,形状由 aspect_ratio 决定。
出图比例白名单
aspect_ratio / aspectRatio 取值按模型分档(传白名单外的值 → 400):
- flash 系(2.5-flash / 3.1-flash),10 个:
21:9 · 16:9 · 4:3 · 3:2 · 5:4 · 1:1 · 4:5 · 3:4 · 2:3 · 9:16 - pro 系(pro / pro-2k),13 个:上面 10 个 + 三个极端比例
1:4 · 1:8 · 8:1(超长条 / 全景)
自定义图床(OSS)
默认生成图存平台图床(URL 形如 images.silkroadai.io/gen/<uuid>.png,不保证长期保留)。想让图片直接进自己的 bucket、用自己的域名、数据归属自己 → 在 存储设置 配置自定义 OSS:选服务商 → 填 Bucket / AK / SK / 公网前缀 → 点「测试连接」(平台写入并删除一个临时文件验证读写)→ 保存即时生效,之后所有生图自动进你的 bucket。
| 服务商 | Endpoint 示例 | Region |
|---|---|---|
| Cloudflare R2 | https://<account_id>.r2.cloudflarestorage.com | 留空 |
| 阿里云 OSS | https://oss-cn-hangzhou.aliyuncs.com | 留空 |
| 腾讯云 COS | https://cos.ap-guangzhou.myqcloud.com | 留空 |
| AWS S3 | 留空 | 必填(如 us-east-1) |
| 自建 / 其他 S3 兼容 | https://minio.example.com | 留空(自动 path-style) |
安全:用子账号最小权限(只授该 bucket 的 PutObject + DeleteObject),凭证在平台侧 AES-256-GCM 加密存储、保存后永不回显。OSS 出任何故障(凭证过期 / bucket 删 / 网络)不会导致生图失败 —— 自动回退平台图床并在响应头加 X-Silkroadai-Oss-Fallback: yes。
常见问题
Q:没指定比例,出来的为什么不是正方形?
3.1-flash 和 pro 系默认出 16:9 宽幅,只有 2.5-flash 默认方图。要正方形请显式传 aspect_ratio: "1:1"。
Q:pro 的 2K 和 4K 怎么选?
要快、要省 → gemini-3-pro-image-preview-2k(¥0.30);要最高清(印刷)→ gemini-3-pro-image-preview(¥0.50,生成慢一倍)。
Q:image_url 返回 400 image_url fetch failed?
源站拒绝平台拉取(反盗链 / 限流)或图超 20MB。改用 data URL(把图转 base64 直接发)。
Q:图片 URL 会一直有效吗?
平台图床不保证永久保留,重要图请及时转存,或配置自定义 OSS 让图直接进自己的 bucket。
13GPT image-2 生图
OpenAI Images API 兼容 —— POST /v1/images/generations 文生图、POST /v1/images/edits 图生图。现有 OpenAI SDK 改一行 base_url 即可。返回 b64_json(Base64 PNG)。后端为 Azure 官方 gpt-image,稳定 + 抗高并发(实测 100 并发 100% 成功)。 请用「image2官方稳定高并发」档的 API Key 调用。
quality 决定(下表),尺寸(size)影响很小。| 情形 | 大致输出 token | 约 ¥ / 张 |
|---|---|---|
| 简单 prompt · quality 默认(auto) | ~200–400 | ¥0.008–0.026 |
| 复杂 prompt · auto(自动提质) | ~2000–4000 | ¥0.065–0.16 |
| quality=high(1024²) | ~7000 | ~¥0.27 |
单一模型 gpt-image-2,分辨率由 size 控制(最高 3840×2160);上表为估算,实际以响应 usage / 账单为准。
文生图 · /v1/images/generations(JSON)
| 参数 | 必填 | 说明 |
|---|---|---|
| model | ✓ | gpt-image-2 |
| prompt | ✓ | 图像文字描述 |
| quality | — | low / medium / high / auto(默认)—— 直接决定成本,见上表 |
| size | — | 1024x1024 / 1536x1024 / 1024x1536 / auto;最高 3840x2160 |
| output_format | — | png(默认)/ jpeg(webp 暂不支持) |
| n | — | 张数,默认 1(建议 1,多张分多次更稳) |
| response_format | — | 默认 b64_json;传 url 则存图床(默认 images.silkroadai.io 或你配置的 OSS)返回 URL |
curl https://ai.silkroadai.io/v1/images/generations \
-H "Authorization: Bearer sk-你的KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "一只戴圣诞帽的橘猫,工作室灯光,高细节",
"size": "1536x1024",
"quality": "high"
}'from openai import OpenAI
import base64
client = OpenAI(api_key="sk-你的KEY", base_url="https://ai.silkroadai.io/v1")
resp = client.images.generate(
model="gpt-image-2",
prompt="一只戴圣诞帽的橘猫,工作室灯光,高细节",
size="1536x1024",
)
with open("out.png", "wb") as f:
f.write(base64.b64decode(resp.data[0].b64_json))import OpenAI from "openai";
import fs from "node:fs";
const client = new OpenAI({ apiKey: "sk-你的KEY", baseURL: "https://ai.silkroadai.io/v1" });
const resp = await client.images.generate({
model: "gpt-image-2",
prompt: "一只戴圣诞帽的橘猫,工作室灯光,高细节",
size: "1536x1024",
});
fs.writeFileSync("out.png", Buffer.from(resp.data[0].b64_json, "base64"));图生图 · /v1/images/edits(multipart)
上传一张(或多张)参考图 + 修改要求,返回改后的图。
| 字段 | 必填 | 说明 |
|---|---|---|
| model | ✓ | gpt-image-2(或专用档) |
| prompt | ✓ | 修改要求 |
| image | ✓ | 原图文件;可重复传多张参考图 |
| quality / size | — | 同文生图;默认回 b64_json,传 response_format: url 存图床返 URL |
curl https://ai.silkroadai.io/v1/images/edits \
-H "Authorization: Bearer sk-你的KEY" \
-F model=gpt-image-2 \
-F prompt="把背景换成雪景" \
-F image=@cat.pngfrom openai import OpenAI
import base64
client = OpenAI(api_key="sk-你的KEY", base_url="https://ai.silkroadai.io/v1")
resp = client.images.edit(
model="gpt-image-2",
prompt="把背景换成雪景",
image=open("cat.png", "rb"),
)
with open("edited.png", "wb") as f:
f.write(base64.b64decode(resp.data[0].b64_json))响应格式
{
"created": 1781523778,
"data": [{ "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." }]
}data[0].b64_json(Base64 的 PNG,自行解码保存)。默认回 b64_json;若想拿公网 URL(存平台图床 images.silkroadai.io,或你在存储设置配了自定义 OSS 则进你的 bucket),请求加 "response_format": "url"。按 token 计费(¥1.3 = 官方 $1),成本由 quality 主导(见上表), 响应 usage 即真实 token 用量。上游报错原样透传(状态码 + OpenAI 错误体)。/v1/images/generations 或 /v1/images/edits 任意一个都行,平台按有没有带参考图自动分流:带图(multipart 的 image 字段,或 JSON 里 image / image_url 传 data URL)→ 走图生图;只有 prompt → 走文生图。原来的两个独立接口照常可用、行为不变。OpenAI(..., timeout=180.0, max_retries=2)错误处理
上游报错原样透传,HTTP 状态码即上游状态码,响应体为 OpenAI 错误格式;按非 2xx 状态码 + error.message 处理。
| 状态码 | 含义 | 处理 |
|---|---|---|
| 401 | Key 无效 | 检查 Authorization 头 |
| 402 | 余额不足 | 前往 /pay 充值 |
| 400 | 内容违规 / 参数错误 | 看 error.message,调整 prompt / 参数 |
| 429 | 频率过高 | 退避后重试 |
| 5xx | 上游临时故障 | 稍后重试 |
POST /v1/images/generations · 图生图 POST /v1/images/edits · 模型 gpt-image-2(自适应,推荐)/ -1k / -2k / -4k · 返回 data[0].b64_json(PNG)· 按 token(¥1.3=$1)· 4K 超时 ≥180s + 重试 · Key 用 image2 分组。严格模式 · Azure 标准校验(可选)
默认对不支持的参数「尽量出图」(静默忽略 / 自动调整尺寸)。若你需要严格对标 Azure gpt-image 行为(不支持的参数明确报 400、而非静默改),给请求加一个开关即可:请求头 X-Silkroadai-Strict: true 或 URL 加 ?strict=true。不加这个开关 = 保持现在的宽容行为,现有代码完全不受影响。
开启后
| 参数 | 严格模式行为 |
|---|---|
| output_format(webp 等) | 非 png / jpeg → 400(默认:静默返回 PNG) |
| background=transparent | → 400(默认:静默返回不透明 PNG) |
| size | 非法尺寸 → 400(默认:静默四舍五入),规则见下 |
| output_format=jpeg | 真正返回 JPEG(默认:恒返 PNG) |
合规例:1024x1024 / 1536x1024 / 3072x1024 / 3840x2160;非法例:3200x1024(比例 > 3:1)、3840x2176(短边 > 2160)、1024x641(非 16 倍数)。
# 严格模式:非法参数直接 400,不再静默出图
curl https://ai.silkroadai.io/v1/images/generations \
-H "Authorization: Bearer sk-你的KEY" \
-H "X-Silkroadai-Strict: true" \
-H "Content-Type: application/json" \
-d '{ "model": "gpt-image-2", "prompt": "...", "size": "3200x1024" }'
# → 400 invalid size '3200x1024': aspect ratio must be within 3:1
# output_format=jpeg 在严格模式下真正返回 JPEG(也可用 ?strict=true 开关)
curl "https://ai.silkroadai.io/v1/images/generations?strict=true" \
-H "Authorization: Bearer sk-你的KEY" -H "Content-Type: application/json" \
-d '{ "model": "gpt-image-2", "prompt": "...", "output_format": "jpeg" }'14异步生图 · 大图/批量免超时
4K / 高质量图生成可能耗时 1–4 分钟,同步长连接容易在你或中间层(反向代理 / 云网关)撞超时。异步模式:提交秒回一个 task_id(不占长连接),之后用 task_id轮询结果,或配一个 webhook 让我们在完成时主动回调你。对所有走 /v1/images/* 的模型都生效(gpt-image-2、Gemini 生图等),文生图 / 图生图都支持。
?async=true 即可 —— 请求 body 和同步调用完全一样,只是返回从「图片」变成「task_id」。三个接口
| 接口 | 作用 |
|---|---|
| POST /v1/images/generations?async=true | 文生图,提交 → 秒回 task_id |
| POST /v1/images/edits?async=true | 图生图(multipart:image + prompt + model),提交 → 秒回 task_id |
| GET /v1/images/tasks/{task_id} | 查询结果:IN_PROGRESS / SUCCESS / FAILURE |
Query 参数
| 参数 | 必填 | 说明 |
|---|---|---|
| async | ✓ | 填 true 启用异步(不填 = 原同步行为不变) |
| webhook | — | 公网 http(s) 回调地址;任务完成时我们 POST 结果过去(见下方 webhook 段) |
body 参数(model / prompt / size / quality / image …)与同步接口完全一致,见上一章。
调用示例(curl)
# ① 提交(文生图;图生图用 /v1/images/edits + multipart,加同一个 ?async=true)
curl "https://ai.silkroadai.io/v1/images/generations?async=true" \
-H "Authorization: Bearer sk-你的KEY" \
-H "Content-Type: application/json" \
-d '{ "model": "gpt-image-2", "prompt": "一只在炒菜的小猫", "size": "1024x1024" }'
# → { "code":"success", "data":{ "task_id":"3dad96708a77…", "status":"IN_PROGRESS" } }
# ② 轮询(每几秒一次,直到 status = SUCCESS / FAILURE)
curl "https://ai.silkroadai.io/v1/images/tasks/3dad96708a77…" \
-H "Authorization: Bearer sk-你的KEY"查询响应结构
{
"code": "success",
"data": {
"task_id": "3dad96708a77485e97ac7ef652796d7b",
"status": "SUCCESS", // IN_PROGRESS / SUCCESS / FAILURE
"fail_reason": "", // FAILURE 时填失败原因
"submit_time": 1758993864,
"finish_time": 1758993885,
"progress": "100%",
"data": { // ← 内层 = 标准图片结果
"data": [ { "url": "https://images.silkroadai.io/gen/xxxx.png" } ],
"model": "gpt-image-2",
"created": 1758993885
}
}
}
// 成功后图片 URL 在 data.data.data[0].urlPython(提交 + 轮询封装)
import time, requests
BASE = "https://ai.silkroadai.io/v1"
H = {"Authorization": "Bearer sk-你的KEY"}
# 提交
task_id = requests.post(
f"{BASE}/images/generations?async=true", headers=H,
json={"model": "gpt-image-2", "prompt": "一只在炒菜的小猫", "size": "1024x1024"},
).json()["data"]["task_id"]
# 轮询
while True:
d = requests.get(f"{BASE}/images/tasks/{task_id}", headers=H).json()["data"]
if d["status"] == "SUCCESS":
print("图片:", d["data"]["data"][0]["url"]); break
if d["status"] == "FAILURE":
print("失败:", d["fail_reason"]); break
time.sleep(3)webhook 回调(可选,免轮询)
提交时带上 &webhook=你的公网地址,任务完成时(成功或失败)我们会向该地址 POST 一份结果,你就不用轮询了:
curl "https://ai.silkroadai.io/v1/images/generations?async=true&webhook=https://你的域名/callback" \
-H "Authorization: Bearer sk-你的KEY" -H "Content-Type: application/json" \
-d '{ "model": "gpt-image-2", "prompt": "一只在炒菜的小猫" }'我们 POST 到你 webhook 的内容:
{
"topic": "image_task_completed",
"data": { /* 与查询响应的 data 完全一致:含 status、fail_reason、data.data[0].url 等 */ }
}webhook 必须是公网 http(s) 地址(不接受 localhost / 内网 IP,提交时会 400 拒绝)。投递失败自动重试 3 次;webhook 只是通知,任务结果始终可用上面的查询接口拿到。
?async=true → 秒回 task_id → GET /v1/images/tasks/{task_id} 轮询(或加 &webhook= 收回调)· 图在 data.data.data[0].url · Key 用你在 /keys 拿的即可 · Gemini 生图填对应 model 名,不要用原生 /v1beta。15计费 · 账户 · 网络
用 API 查询余额
/v1/balance ——不是上面的 /balance 网页。鉴权用你的 API Key(sk-…),和调用模型同一个。① 查余额(推荐,直接返回人民币)
curl https://ai.silkroadai.io/v1/balance \
-H "Authorization: Bearer sk-…"{
"object": "balance",
"currency": "CNY",
"balance_cny": 268.46,
"used_cny": 951.54,
"balance_usd": 38.35
}balance_cny = 可用余额(¥)· used_cny = 累计消费(¥,已扣视频等失败任务的退款,与控制台「概览」一致)· balance_usd = 余额折算美元。
Python
import requests
r = requests.get(
"https://ai.silkroadai.io/v1/balance",
headers={"Authorization": "Bearer sk-…"},
)
data = r.json()
print(f"余额 ¥{data['balance_cny']} · 已用 ¥{data['used_cny']}")② OpenAI 兼容接口(给现成余额工具用,零改动)
很多客户端 / 余额监控工具按 OpenAI 老接口查额度,我们也兼容。余额 = hard_limit_usd − total_usage / 100(单位美元)。
# 总额度(美元)
curl https://ai.silkroadai.io/v1/dashboard/billing/subscription \
-H "Authorization: Bearer sk-…"
# → {"hard_limit_usd": 174.29, ...}
# 已用(美分)
curl https://ai.silkroadai.io/v1/dashboard/billing/usage \
-H "Authorization: Bearer sk-…"
# → {"total_usage": 13593} # = $135.93Key 无效 / 停用返 401。余额实时(约 60 秒缓存)。⚠️ 这些是查询接口,不要用 GET /balance(无 v1 前缀)——那是网页,会返回 HTML。
网络:接入点 ai.silkroadai.io 多区域 CDN,国内通常可直连。流式调用对网络稳定性敏感,丢包可能导致 502 —— 频繁出错时可尝试关闭 stream,或换用更稳定的线路。排查时把响应里的 request_id 发给客服可快速定位。
16Seedance 2.0 · 视频生成
Seedance 2.0 全能视频生成(即梦 / Sora 体系)—— 文生 / 图生 / 多图组合 / 首帧·首尾帧 / 参考视频 / 参考音频,一个接口全包。异步:提交拿 task_id,轮询到 SUCCESS 取视频。走 /v1/video/generations(不是 /v1/chat/completions,后者 404)。
seedance-2.0-720 / seedance-2.0-1080 模型;调别的模型请用默认档 key。模型与价格(按视频秒数)
| 模型 | 分辨率 | 价格 | 10 秒 / 15 秒 |
|---|---|---|---|
| seedance-2.0-720 | 720P | ¥0.60 / 秒 | ¥6.00 / ¥9.00 |
| seedance-2.0-1080 | 1080P | ¥0.72 / 秒 | ¥7.20 / ¥10.80 |
按视频秒数计费;seconds 控制时长,当前支持 10 / 15(字符串)。分辨率由模型名决定。
1) 提交任务(文生视频)
curl https://ai.silkroadai.io/v1/video/generations \
-H "Authorization: Bearer 你的key" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.0-720",
"prompt": "霓虹雨夜街头的电影感跟拍镜头,缓慢推进,35mm 颗粒",
"aspect_ratio": "16:9",
"seconds": "10"
}'
# → { "task_id": "task_xxx", "object": "video", "status": "queued" }2) 轮询直到完成
curl https://ai.silkroadai.io/v1/video/generations/task_xxx -H "Authorization: Bearer 你的key"
# status: in_progress … 几分钟后 "status": "completed"
# 视频直链在响应的 video_url 字段(公网 .mp4)in_progress)时 video_url 为空(或临时链),取了也打不开 —— 这是「扣钱没出片」最常见的原因。完成后 video_url 是我们的公网永久直链,可直接播放 / 下载。参数总表
| 参数 | 必填 | 说明 |
|---|---|---|
| model | 必填 | seedance-2.0-720(720P)/ seedance-2.0-1080(1080P) |
| prompt | 必填 | 画面提示词;多素材时用 @Image1 / @Video1 / @Audio1 显式指代(见下) |
| aspect_ratio | 否 | 16:9(默认)/ 9:16 / 1:1 / 4:3 / 3:4 / 21:9 |
| seconds | 否 | 时长(字符串),"10" / "15",默认 10 |
| image_url | 否 | 单张参考图(URL 或 base64 dataURL) |
| reference_image_urls | 否 | 多张参考图数组(≤9),@ImageN 对应第 N 张 |
| reference_videos | 否 | 参考视频数组(≤3,总时长 ≤15s) |
| audio_url / reference_audios | 否 | 参考音频(≤3,mp3/wav/m4a 等),需同时带 ≥1 张参考图 |
| video_config.reference_mode | 否 | auto(默认,多图参考)/ start_frame(正好 1 图=首帧)/ start_end(正好 2 图=首尾帧) |
@ 引用语法(多素材必读)
多素材组合时,模型靠 prompt 里的 @ 标记识别每个素材的角色: @Image1 = reference_image_urls 第 1 张、@Video1 = reference_videos 第 1 个、@Audio1 = reference_audios 第 1 个,依此类推。不显式 @ 指代,模型会瞎猜哪张图是什么。
玩法示例
1) 图生视频(单图)
curl https://ai.silkroadai.io/v1/video/generations \
-H "Authorization: Bearer 你的key" -H "Content-Type: application/json" \
-d '{ "model": "seedance-2.0-720", "prompt": "@Image1 的人物开始走路,镜头跟随推进", "seconds": "10",
"image_url": "https://你的图床/start.jpg" }'2) 多图组合(角色 + 场景,@ 引用)
curl https://ai.silkroadai.io/v1/video/generations \
-H "Authorization: Bearer 你的key" -H "Content-Type: application/json" \
-d '{ "model": "seedance-2.0-1080",
"prompt": "@Image1 的角色,在 @Image2 的场景里跳舞,宽银幕镜头",
"aspect_ratio": "21:9", "seconds": "15",
"reference_image_urls": ["https://你的图床/role.jpg", "https://你的图床/scene.jpg"] }'3) 首帧(start_frame,正好 1 张图)
curl https://ai.silkroadai.io/v1/video/generations \
-H "Authorization: Bearer 你的key" -H "Content-Type: application/json" \
-d '{ "model": "seedance-2.0-720", "prompt": "从这个画面开始,镜头缓慢推进,人物转身", "seconds": "10",
"image_url": "https://你的图床/start.jpg", "video_config": { "reference_mode": "start_frame" } }'4) 首尾帧(start_end,正好 2 张图)
curl https://ai.silkroadai.io/v1/video/generations \
-H "Authorization: Bearer 你的key" -H "Content-Type: application/json" \
-d '{ "model": "seedance-2.0-720", "prompt": "从第一张画面平滑过渡到第二张,自然运镜", "seconds": "10",
"reference_image_urls": ["https://你的图床/first.jpg", "https://你的图床/last.jpg"],
"video_config": { "reference_mode": "start_end" } }'5) 全能参考(图 + 视频 + 音频,卡点 / 配乐)
curl https://ai.silkroadai.io/v1/video/generations \
-H "Authorization: Bearer 你的key" -H "Content-Type: application/json" \
-d '{ "model": "seedance-2.0-720",
"prompt": "@Image1 角色随 @Audio1 的节奏起舞,运镜参考 @Video1", "seconds": "15",
"reference_image_urls": ["https://你的图床/role.jpg"],
"reference_videos": ["https://你的视频/camera.mp4"],
"audio_url": "https://你的音频/track.mp3" }'用音频(audio_url / reference_audios)时必须同时带 ≥1 张参考图,否则上游报错。
Python 完整示例(提交 + 轮询)
import time, requests
BASE = "https://ai.silkroadai.io/v1/video/generations"
H = {"Authorization": "Bearer 你的key", "Content-Type": "application/json"}
task = requests.post(BASE, headers=H, json={
"model": "seedance-2.0-720",
"prompt": "一只橘猫在窗台上伸懒腰,慢镜头,暖色调",
"aspect_ratio": "16:9", "seconds": "10",
}).json()
tid = task.get("task_id") or task.get("id")
def pick(d): # 递归找视频直链
out = None
def w(n):
nonlocal out
if isinstance(n, dict):
v = n.get("video_url")
if isinstance(v, str) and v.startswith("http") and not out: out = v
for x in n.values(): w(x)
elif isinstance(n, list):
for x in n: w(x)
w(d); return out
for _ in range(120): # 最多约 16 分钟
r = requests.get(f"{BASE}/{tid}", headers=H).json()
st = str(r.get("data", {}).get("status") or r.get("status") or "").lower()
if st in ("completed", "success", "failed", "failure"):
print(st, "→", pick(r)); break
time.sleep(8)常见问题
| 现象 | 原因 / 解决 |
|---|---|
| 无可用渠道 / 模型不存在 | key 不是「seedance逆向低价」档,或模型名拼错(只有 seedance-2.0-720 / -1080) |
| seconds 报错 / 不生效 | 必须是字符串,且只能 "10" / "15" |
| 多图但角色错乱 | prompt 里用 @Image1 / @Image2 显式指代每张图 |
| 音频报错 | 用音频时必须同时带至少一张参考图 |
| 视频链接过段时间失效 | 临时直链,拿到尽快转存到自己存储 |
| 任务很久仍生成中 | 高峰排队正常,1080P 更慢;耐心轮询,别频繁重建 |
| 偶发 5xx | 上游波动,稍后重试 |
17Seedance 海外满血 · 高质量视频
即梦 Seedance 2.0 官方满血源(质量优先,与上方普通 Seedance 是两套独立的源与价格)。支持文生 / 图生 / 首尾帧 / 参考音频,异步接口(提交 → 轮询),按视频秒数计费。
dreamina-seedance-2-0-* 模型;调别的模型请用默认档 key。"generate_audio": false;想让画面跟随你指定的音频(唱歌 / 卡点)见下方「参考音频」玩法。注意:上方普通 Seedance是另一套独立的源,是否有声以那套源为准 —— 要稳定有声请用本节的 dreamina-seedance-2-0-*。模型与价格(按视频秒数)
| 模型(文生 / 图生·首尾帧·音频用 -ref) | 分辨率 | 文生 ¥/秒 | 带图(-ref)¥/秒 |
|---|---|---|---|
| dreamina-seedance-2-0-480p[-ref] | 480P | ¥0.43 | ¥0.27 |
| dreamina-seedance-2-0-720p[-ref] | 720P | ¥0.93 | ¥0.57 |
| dreamina-seedance-2-0-1080p[-ref] | 1080P | ¥2.31 | ¥1.41 |
| dreamina-seedance-2-0-4k[-ref] | 4K | ¥4.45 | ¥2.67 |
| dreamina-seedance-2-0-fast-480p[-ref] | 480P 快 | ¥0.35 | ¥0.20 |
| dreamina-seedance-2-0-fast-720p[-ref] | 720P 快 | ¥0.75 | ¥0.44 |
纯文字用不带 -ref 的;带图 / 首尾帧 / 音频用带 -ref 的(更便宜)。duration 控制秒数(默认 4)。
1) 文生视频
curl https://ai.silkroadai.io/v1/video/generations \
-H "Authorization: Bearer sk-你的海外满血KEY" -H "Content-Type: application/json" \
-d '{ "model": "dreamina-seedance-2-0-720p", "prompt": "一只橘猫在窗台伸懒腰,暖色调", "duration": 5 }'2) 图生 / 参考生(-ref + image)
curl https://ai.silkroadai.io/v1/video/generations -H "Authorization: Bearer sk-你的海外满血KEY" \
-H "Content-Type: application/json" -d '{ "model": "dreamina-seedance-2-0-720p-ref",
"prompt": "镜头缓缓推进,画面动起来", "duration": 5, "image": "https://你的图床/photo.jpg" }'
# image 支持 http 链接或 base64 data URL;多图用 images:[...](≤9);也兼容 image_url / reference_image_urls3) 首尾帧过渡(-ref + first_frame/last_frame)
curl https://ai.silkroadai.io/v1/video/generations -H "Authorization: Bearer sk-你的海外满血KEY" \
-H "Content-Type: application/json" -d '{ "model": "dreamina-seedance-2-0-720p-ref",
"prompt": "从第一张平滑过渡到第二张", "duration": 5,
"first_frame": "https://你的图床/first.jpg", "last_frame": "https://你的图床/last.jpg" }'4) 参考音频(-ref + image + audio_url)
curl https://ai.silkroadai.io/v1/video/generations -H "Authorization: Bearer sk-你的海外满血KEY" \
-H "Content-Type: application/json" -d '{ "model": "dreamina-seedance-2-0-720p-ref",
"prompt": "这个人随节奏唱歌", "duration": 5, "image": "https://你的图床/singer.jpg",
"audio_url": "https://你的音频/song.mp3" }'
# 用音频时必须同时带至少一张图5) 参考视频(-ref + reference_videos)
curl https://ai.silkroadai.io/v1/video/generations -H "Authorization: Bearer sk-你的海外满血KEY" \
-H "Content-Type: application/json" -d '{ "model": "dreamina-seedance-2-0-720p-ref",
"prompt": "运镜参考 @Video1,把场景换成雪天", "duration": 5,
"reference_videos": ["https://你的视频/camera.mp4"] }'
# reference_videos 数组(≤3);可与参考图同用,prompt 里 @Video1 / @Image1 指代轮询取片
curl https://ai.silkroadai.io/v1/video/generations/task_xxx -H "Authorization: Bearer sk-你的海外满血KEY"
# data.status=SUCCESS 后,视频在 data.data.video_url(或 result_url,等价)参考图别太小(约 256px 以下会被上游拒,用 ≥512px 稳);视频直链是临时的,拿到尽快转存。首尾帧也可用 video_config.reference_mode = start_frame/start_end 指定。参考视频用 reference_videos(数组 ≤3,单段建议 ≤15s),与图片同走转存,可与参考图 / 音频同用;参考视频分辨率需 ≥480p(像素 ≥409600,360p 等过小会被上游拒)。
参数总表
| 参数 | 适用 | 说明 |
|---|---|---|
| model | 必填 | 上表模型名(决定分辨率 / 计费档) |
| prompt | 必填 | 画面描述 |
| duration | 否 | 秒数,默认 4(价格 = 每秒价 × 秒数);同义字段 seconds |
| aspect_ratio | 否 | 16:9(默认)/ 9:16 / 1:1 / 4:3 / 3:4 / 21:9 |
| image / images | -ref | 参考图(单 / 多 ≤9);http 链接或 base64;同义字段 image_url / reference_image_urls |
| first_frame / last_frame | -ref | 首帧 / 尾帧图(首尾帧过渡) |
| reference_videos | -ref | 参考视频数组(≤3,单段建议 ≤15s);http 链接或 base64 |
| audio_url | -ref | 参考音频(直链或 base64),需配 ≥1 张图 |
| generate_audio | 全部 | 是否生成 AI 声音,默认 true(出声);传 false 得静音视频。不额外收费 |
Python 完整示例(提交 + 轮询)
import time, requests
BASE = "https://ai.silkroadai.io/v1"
KEY = "你的 seedance海外满血 key"
H = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}
# 图生(参考图);文生去掉 image、换不带 -ref 的模型即可
task = requests.post(f"{BASE}/video/generations", headers=H, json={
"model": "dreamina-seedance-2-0-720p-ref",
"prompt": "镜头缓缓推进,画面动起来",
"duration": 5,
"image": "https://你的图床/photo.jpg",
}).json()
tid = task.get("task_id") or task.get("id")
def pick(d): # 递归找视频直链
out = None
def w(n):
nonlocal out
if isinstance(n, dict):
v = n.get("video_url")
if isinstance(v, str) and v.startswith("http") and not out: out = v
for x in n.values(): w(x)
elif isinstance(n, list):
for x in n: w(x)
w(d); return out
for _ in range(120): # 最多约 10 分钟
r = requests.get(f"{BASE}/video/generations/{tid}", headers=H).json()
st = str(r.get("data", {}).get("status") or r.get("status") or "").upper()
if st in ("SUCCESS", "FAILURE", "FAILED"):
print(st, "→", pick(r) or r.get("data", {}).get("result_url")); break
time.sleep(8)常见问题
| 现象 | 原因 / 解决 |
|---|---|
| 无可用渠道 / 模型不存在 | key 不是「seedance海外满血」档,或模型名拼错 |
| 视频没有声音 | 本节模型默认带声音;若用的是普通 seedance-2.0(另一套源)或传了 generate_audio:false 会静音 —— 改用 dreamina-seedance-2-0-* 且别关音频 |
| 401 鉴权失败 | 检查 Authorization: Bearer 头与 key |
| 参考图报 Asset provider error | 图太小(<~256px),换 ≥512px |
| -ref 模型报 requires an image | -ref 必须带 image / first_frame / last_frame |
| 音频报 requires reference_image | 用音频时必须同时带至少一张图 |
| 视频链接过段时间失效 | 临时直链,拿到尽快转存到自己存储 |
| 任务很久仍生成中 | 高峰排队正常,1080P 更慢;耐心轮询,别频繁重建 |
| 偶发 5xx | 上游波动,稍后重试 |
18Seedance 国内企业级 · 火山方舟
火山方舟(Volcengine Ark)doubao-seedance 国内企业级端口 —— 文生 / 图生 / 首帧·首尾帧 / 多图参考 / 参考视频 / 参考音频,720P · 1080P · 4K 全档。异步:提交拿 task_id,轮询到 completed 取视频。走 /v1/video/generations(不是 /v1/chat/completions,后者 404),与「Seedance 2.0」章节同一套调用方式。
seedance2.0-pro-* 模型;调别的模型请用对应档 key。模型与价格(按 token 计费)
| 分辨率 | 无视频输入(文生 / 图生 / 首尾帧 / 多图)· 元/1M token | 含视频输入(参考视频)· 元/1M token |
|---|---|---|
| 720P | ¥39.1 | ¥23.8 |
| 1080P | ¥43.35 | ¥26.35 |
| 4K | ¥22.1 | ¥13.6 |
按实际 token 计费(以响应 usage.completion_tokens 为准,仅对成功出片扣费)。视频 token ≈ 分辨率 × 时长 —— 分辨率越高 / 视频越长,token 越多。示例:720P 5 秒 ≈ 10.9 万 token ≈ ¥4.26。模型 6 档: seedance2.0-pro-{720p|1080p|4k}(文生)+ 加 -ref(图生 / 首尾帧 / 多图 / 参考视频)。含视频输入(参考视频)每 1M token 更便宜,但输入视频时长也计入 token,故整体成本更高。duration 支持 5 / 10 秒。
1) 提交任务(文生视频)
curl https://ai.silkroadai.io/v1/video/generations \
-H "Authorization: Bearer 你的key" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance2.0-pro-1080p",
"prompt": "一只穿红大衣的小猫在漫天大雪中好奇地伸爪抓雪花,写实电影质感",
"aspect_ratio": "16:9",
"duration": 5
}'
# → { "task_id": "cgt_xxx", "object": "video", "status": "queued" }2) 轮询直到完成
curl https://ai.silkroadai.io/v1/video/generations/cgt_xxx -H "Authorization: Bearer 你的key"
# status: in_progress … 几分钟后 "status": "completed"
# 视频直链在响应的 video_url 字段in_progress)时 video_url 为空,务必轮询到 completed 再取。参数总表
| 参数 | 必填 | 说明 |
|---|---|---|
| model | 必填 | seedance2.0-pro-{720p|1080p|4k}(文生)或加 -ref 后缀(图生 / 首尾帧 / 多图 / 参考视频) |
| prompt | 必填 | 画面提示词 |
| duration | 否 | 时长秒数,5 / 10,默认 5(也接受 seconds) |
| aspect_ratio | 否 | 16:9(默认)/ 9:16 / 1:1 / 4:3 / 3:4 / 21:9 |
| image / image_url | 否 | 单张参考图(URL 或 base64 dataURL);需用 -ref 模型 |
| images / reference_image_urls | 否 | 多张参考图数组(≤9) |
| first_frame / last_frame | 否 | 首帧 / 尾帧图(首尾帧玩法) |
| reference_videos | 否 | 参考视频数组(≤3) |
| audio_url / audios | 否 | 参考音频,需同时带 ≥1 张参考图 |
| generate_audio | 否 | 是否生成背景音效,默认 true(传 false 关) |
玩法示例
1) 图生视频(单图 → 用 -ref 模型)
curl https://ai.silkroadai.io/v1/video/generations \
-H "Authorization: Bearer 你的key" -H "Content-Type: application/json" \
-d '{ "model": "seedance2.0-pro-720p-ref", "prompt": "图中人物开始走路,镜头跟随推进",
"duration": 5, "image_url": "https://你的图床/start.jpg" }'2) 首尾帧
curl https://ai.silkroadai.io/v1/video/generations \
-H "Authorization: Bearer 你的key" -H "Content-Type: application/json" \
-d '{ "model": "seedance2.0-pro-1080p-ref", "prompt": "从第一张画面平滑过渡到第二张",
"duration": 5, "first_frame": "https://.../a.jpg", "last_frame": "https://.../b.jpg" }'3) 多图参考 + 参考音频
curl https://ai.silkroadai.io/v1/video/generations \
-H "Authorization: Bearer 你的key" -H "Content-Type: application/json" \
-d '{ "model": "seedance2.0-pro-720p-ref", "prompt": "参考人物外观,跟随音乐节奏起舞",
"duration": 5,
"images": ["https://.../face.jpg", "https://.../outfit.jpg"],
"audio_url": "https://.../beat.mp3" }'参考图 / 视频 / 音频可传公网 URL 或 base64 dataURL;dataURL 会由我们自动转存后再交给上游。 无参考模型(不带 -ref)带图会 400,请选对应 -ref 模型。也可在 Seedance 视频测试工具 里在线试。
19模型目录 · 程序化价格发现
GET /v1/models 返回你的 key 可调用的模型列表(标准 OpenAI 形),每个条目额外带一个 silkroadai 字段:显示名、厂商、类型、上下文窗口、按你 key 档次解析的 ¥ 价格。 比价、选型、给 litellm / 网关生成配置,都不用再人肉翻网页。OpenAI 官方 SDK 对多出来的字段自动忽略 —— 存量代码零改动。
- 端点GET https://ai.silkroadai.io/v1/models
- 认证Authorization: Bearer sk-…
- 响应标记头X-Silkroadai-Enriched: models
- 目录数据刷新约 60 秒
响应示例(单个条目)
{
"id": "claude-opus-4-8",
"object": "model",
"created": 1700000000,
"owned_by": "anthropic",
"silkroadai": {
"display_name": "Claude Opus 4.8",
"vendor": "Anthropic",
"type": "vision",
"vision": true,
"context_window": 200000,
"tier": "official",
"pricing": {
"input_cny_per_1m": 34,
"output_cny_per_1m": 170,
"per_image_cny": null
}
}
}silkroadai 字段说明
| 字段 | 说明 |
|---|---|
| display_name | 人类可读名(目录未收录的模型无此字段) |
| vendor | 厂商(OpenAI / Anthropic / Google / …) |
| type | 展示分类:chat / vision / image-gen / video / audio / embedding。注意:具备视觉能力的对话旗舰归 vision 而非 chat —— 判断「能否对话」用 type ∈ {chat, vision},判断「收不收图」用下面的 vision 布尔。 |
| vision | 能力位:是否接受图片输入 |
| context_window | 上下文窗口(token;已知才给) |
| tier | 本响应价格对应的档次 = 你请求所用 key 的档次 |
| pricing | ¥ / 100 万 token(对话类 input / output)或 ¥ / 张(生图类 per_image_cny)。该档未定价 = null(不会拿别档价格充数);实际扣费以账单为准。 |
curl + jq:列出你可用的视觉模型和价格
curl -s https://ai.silkroadai.io/v1/models -H "Authorization: Bearer sk-…" \
| jq -r '.data[] | select(.silkroadai.vision == true)
| "\(.id)\t¥\(.silkroadai.pricing.input_cny_per_1m // "未定价")/1M in\t¥\(.silkroadai.pricing.output_cny_per_1m // "-")/1M out"'Python:选出最便宜的可对话模型
import requests
resp = requests.get(
"https://ai.silkroadai.io/v1/models",
headers={"Authorization": "Bearer sk-…"},
).json()
chatable = [
m for m in resp["data"]
if m.get("silkroadai", {}).get("type") in ("chat", "vision")
and m["silkroadai"].get("pricing") # 该档有定价的才参与比价
]
cheapest = min(chatable, key=lambda m: m["silkroadai"]["pricing"]["input_cny_per_1m"])
p = cheapest["silkroadai"]["pricing"]
print(f'最便宜可对话模型: {cheapest["id"]} ¥{p["input_cny_per_1m"]}/1M in, ¥{p["output_cny_per_1m"]}/1M out')常见问题
| 为什么有的模型 pricing 是 null? | 该模型在你 key 的档次下没有登记目录价(不代表不能调用)。实际按量计费照常, 费用以 portal /usage 与账单为准。 |
| 价格和账单对不上? | 目录价是标价快照(约 60 秒刷新);实际扣费由计费引擎按调用时点结算。两者不一致时以账单为准。 |
| 不同 key 看到的列表 / 价格不一样? | 是。列表按 key 可调模型过滤,价格按 key 档次解析 —— 用哪个 key 查,就是哪个 key 的视角。 |
| 增强会影响我现有代码吗? | 不会。条目集合、顺序、原有字段完全不变,只是每条多了 silkroadai 字段;元数据服务异常时 自动回退为原始列表(无 X-Silkroadai-Enriched 头)。 |
20Key 自查 · 余额监控
GET /v1/key 用 sk- 本身即可自查这把 key 的档次、状态和账户余额 —— 写个 cron 定时轮询就是现成的余额告警,不用登后台、不用截图问客服。
- 端点GET https://ai.silkroadai.io/v1/key
- 认证Authorization: Bearer sk-…
- 错误401 = key 无效/已撤销 · 503 = 余额服务暂不可用(稍后重试)
响应示例
{
"data": {
"key_alias": "prod-openai",
"status": "active",
"tier": "official",
"tier_display_name": "官方稳定",
"created_at": "2026-05-04T00:00:00.000Z",
"model_limits_enabled": false,
"model_limits": [],
"account_balance": {
"balance_cny": 123.45,
"spent_cny": 67.89,
"currency": "CNY",
"stale": false
},
"key_usage": {
"recent_used_cny": 12.34,
"last_used_at": "2026-07-01T12:00:00.000Z",
"source": "live"
}
}
}字段说明
| 字段 | 说明 |
|---|---|
| key_alias / status / tier | key 别名、状态(能查到的必为 active)、档次;tier_display_name 是档次的中文名 |
| model_limits | 建 key 时配置的模型白名单(未启用则为空数组) |
| account_balance | 账户级余额与累计消费(¥)—— 预算在账户不在 key,同账户所有 key 查到的数值相同。stale: true 表示计费源短暂不可达、数值可能滞后(监控脚本此时不要当实时值触发动作)。 |
| key_usage | 本 key 的近期消费概览(best-effort,暂不可得时为 null):recent_used_cny 是近期消费记录(最多约 1000 条)的合计,是概览不是对账口径(对账以 portal /usage 与账单为准);last_used_at 仅实时数据(source=live)时出现 —— 字段缺失=本次未知,null=从未使用过。 |
curl
curl -s https://ai.silkroadai.io/v1/key -H "Authorization: Bearer sk-…" | jq .data.account_balancePython:余额低于阈值告警(可放 cron)
import requests
THRESHOLD_CNY = 50
resp = requests.get("https://ai.silkroadai.io/v1/key", headers={"Authorization": "Bearer sk-…"})
if resp.status_code == 503:
print("余额服务暂不可用,下轮再查") # 稍后重试,勿告警
raise SystemExit(0)
resp.raise_for_status()
bal = resp.json()["data"]["account_balance"]
if bal["stale"]:
print("余额为滞后快照(stale),跳过本轮判断")
elif bal["balance_cny"] < THRESHOLD_CNY:
print(f'⚠️ 余额仅 ¥{bal["balance_cny"]},请及时充值!') # 接你的告警渠道
else:
print(f'余额充足: ¥{bal["balance_cny"]}')常见问题
| 几把 key 查到的余额都一样? | 正常。预算在账户级,key 只是访问凭证 —— 所有 key 共享同一个账户余额。 |
| recent_used_cny 和后台对不上? | 它是近期消费概览(约 60 秒缓存 + 记录条数有上限),长期高频使用的 key 只反映最近一段;完整对账请看 portal /usage。 |
| 已撤销的 key 能查吗? | 不能,返回 401(撤销的 key 在任何端点都不可用)。 |
| 会被限流吗? | 不限流,但余额数据有约 60 秒缓存 —— 高于每分钟一次的轮询不会拿到更新的数字。 |
21用量与扣费查询 · 逐请求对账
每次调用花了多少 token、实际扣了多少钱,都可以程序化拿到:token 用量在响应体里(OpenAI 标准 usage 字段);实际扣费用 GET /v1/usage 查询(按 request_id 单条对账,或按时间段批量拉账单)。
① Token 用量:响应里就有
非流式调用的响应体自带 usage;流式(stream: true)默认不带,加一个参数即可让最后一个 chunk 返回用量:
{
"model": "gpt-5.4",
"stream": true,
"stream_options": { "include_usage": true },
"messages": [{ "role": "user", "content": "你好" }]
}
// 最后一个 SSE chunk:
// { "choices": [], "usage": { "prompt_tokens": 12, "completion_tokens": 340, "total_tokens": 352 } }Anthropic 兼容协议(/v1/messages)同理:响应 / SSE 事件里自带 usage.input_tokens / output_tokens,无需额外参数。
② 实际扣费:先拿 request_id,再查 /v1/usage
扣费是请求结束后记账的,所以不在响应体里 —— 拿每次调用的 request_id 查 /v1/usage 就是这一单实际扣的钱。记账通常在响应结束后 1-2 秒内完成。request_id 从哪拿(两种协议不同):
OpenAI 兼容/v1/chat/completions | 用响应体的 id 字段(形如 chatcmpl-2026…,带不带 chatcmpl- 前缀都能查;流式的每个 chunk 也带同一个 id)。⚠️ 响应头 x-oneapi-request-id 是网关侧的另一个 ID,调用成功时查不到账 —— 别用它 |
Anthropic 兼容/v1/messages | 用响应头 x-oneapi-request-id(响应体的 msg_… 是 Anthropic 自己的 ID,查不到) |
- 端点GET https://ai.silkroadai.io/v1/usage
- 认证Authorization: Bearer sk-…(与调模型同一个 key)
- 错误401 = key 无效/已撤销 · 404 = request_id 还没入账(稍后重试) · 503 = 暂不可用
查询参数(全部可选)
| 参数 | 说明 |
|---|---|
| request_id | 单条对账:OpenAI 兼容协议用响应体 id(chatcmpl- 前缀可带可不带);Anthropic 兼容协议用响应头 x-oneapi-request-id。命中返回该条;还没入账返 404(带明确提示,稍等 1-2 秒重试即可) |
| start_time / end_time | 时间窗(unix 秒,UTC),批量拉账单用 |
| model | 只看某个模型(精确匹配) |
| page / page_size | 分页;page_size 默认 50、上限 100。响应 has_more: true 表示还有下一页 |
| type | consume(默认,成功扣费)· error(失败调用)· refund(退款,如视频任务失败退回)· all |
| key_only | true = 只看当前这把 key 的调用(默认返回整个账户所有 key) |
单条对账(curl)
# 1. 调用,拿响应体的 id(OpenAI 兼容协议)
curl -s https://ai.silkroadai.io/v1/chat/completions \
-H "Authorization: Bearer sk-…" -H "Content-Type: application/json" \
-d '{"model":"gpt-5.4","messages":[{"role":"user","content":"你好"}]}' \
| jq -r .id
# chatcmpl-20260729103000123456789
# 2. 查这一单实际扣费(id 直接整段贴上,chatcmpl- 前缀可带可不带)
curl -s "https://ai.silkroadai.io/v1/usage?request_id=chatcmpl-20260729103000123456789" \
-H "Authorization: Bearer sk-…"响应示例
{
"object": "list",
"data": [
{
"request_id": "20260729103000123456789",
"created_at": 1753797003,
"type": "consume",
"model": "gpt-5.4",
"token_name": "prod-openai",
"is_stream": true,
"duration_ms": 3000,
"usage": { "prompt_tokens": 12, "completion_tokens": 340, "total_tokens": 352 },
"billing": "per_token",
"cost_cny": 0.023800,
"cost_usd": 0.003400,
"quota": 11900,
"content": "模型倍率 0.36,分组倍率 1.20,补全倍率 5.00"
}
],
"page": 1,
"page_size": 50,
"has_more": false
}字段说明
| cost_cny | 这一单实际扣的人民币(权威值,来自计费系统;cost_usd 为按真实汇率折算的美元参考值)。type=refund 的行为负数 = 退回 |
| usage | 计费用的 token 数(prompt / completion / total),与响应体 usage 同源 |
| billing | per_token = 按 token 计费(LLM / gpt-image 系),usage 就是计费依据;per_call = 按次/按张计费(Gemini 生图等固定单价),此时 token 数是上游噪声、仅供参考,以 cost_cny 为准 |
| created_at / duration_ms | 入账时间(unix 秒,UTC)/ 调用耗时(毫秒) |
| content | 计费说明(倍率明细)或失败原因(type=error 时) |
Python:拉当天账单,按模型汇总
import requests, time
BASE = "https://ai.silkroadai.io/v1"
KEY = {"Authorization": "Bearer sk-…"}
start = int(time.time()) - 86400 # 近 24 小时
rows, page = [], 1
while True:
r = requests.get(f"{BASE}/usage", headers=KEY, params={
"start_time": start, "page": page, "page_size": 100,
})
r.raise_for_status()
body = r.json()
rows += body["data"]
if not body["has_more"]:
break
page += 1
by_model = {}
for row in rows:
m = by_model.setdefault(row["model"], {"calls": 0, "cny": 0.0, "tokens": 0})
m["calls"] += 1
m["cny"] += row["cost_cny"]
m["tokens"] += row["usage"]["total_tokens"]
for model, s in sorted(by_model.items(), key=lambda kv: -kv[1]["cny"]):
print(f'{model}: {s["calls"]} 次 · {s["tokens"]} tokens · ¥{s["cny"]:.4f}')
print(f'合计 ¥{sum(s["cny"] for s in by_model.values()):.4f}')常见问题
| 为什么扣费不直接放在模型响应里? | 计费在请求结束后才结算(流式尤其如此,响应发完账才落)。响应里的 usage 是实时的;金额请以 /v1/usage 查询为准 —— 两者用同一个 request_id 关联。 |
| request_id 查询返 404? | 最常见原因:OpenAI 兼容协议误用了响应头 x-oneapi-request-id(要用响应体 id,见上表)。其次是账还没落(通常 1-2 秒),稍等重试即可。若几分钟后仍 404,确认 request_id 是否完整、调用是否真的成功(失败调用在 type=error 里)。 |
| cost_cny 加总和余额变化对得上吗? | 对得上:consume 行合计 − refund 行合计 = 账户净消费,与控制台「概览」和 /v1/key 的 spent_cny 同口径。 |
| 会被限流吗? | 不限流。批量对账建议按时间窗分页拉取(每页最多 100 条),而不是逐条查 request_id。 |
遇到问题?
微信 Global_Ads · 邮箱 support@silkroadai.io