集成文档

Silk Road AI 完全 OpenAI 兼容(同时提供 Anthropic 兼容协议), 所有支持自定义 base URL 的客户端 / SDK 一行替换即可接入。

没有 key?先 注册一个账户 — 30 秒拿到能用的 sk-…

通用配置

OpenAI 兼容 Base URL
https://ai.silkroadai.io/v1
Anthropic 兼容 Base URL
https://ai.silkroadai.io
API Key
portal /keys 创建,形如 sk-…
模型清单
完整清单 → /models

Cursor 设置里有 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」关键字定位最新指引。

Cline 在 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.dev

Continue 通过 config.yaml / config.json 管理模型。OpenAI provider 加一条即可:

yaml
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 等亦可。

Claude Code 通过两个环境变量切到 Anthropic 兼容的第三方网关,启动前导出即可。ANTHROPIC_AUTH_TOKEN 会以 Bearer 形式注入 Authorization 头。

bash
# 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-…"
claude

Claude Code 检测到 ANTHROPIC_BASE_URL 指向非官方主机时,默认会停用 MCP tool search;若需要可同时设置 ENABLE_TOOL_SEARCH=true

05OpenAI Codex(CLI / IDE 插件 / 桌面 app)

官方文档 → developers.openai.com/codex/config-advanced

Codex 有三个客户端形态 — 终端 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(三客户端通用)

yaml
# 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

bash
# 安装(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-…"
codex

2.2 IDE 插件(VS Code / Cursor / Windsurf / JetBrains 全系)

  1. VS Code / Cursor / Windsurf: marketplace 搜 Codex – OpenAI's coding agent (发布者 openai.chatgpt)。JetBrains 系(IntelliJ / PyCharm / WebStorm / Rider):marketplace 搜 Codex
  2. 打开 Codex 侧边栏 → 不要点 "Sign in with ChatGPT",改点 "Use API Key"
  3. 粘贴 portal /keys sk-… → 确定。
  4. 重启 IDE / reload extension,Codex 侧边栏自动读 ~/.codex/config.toml 里的 silkroadai provider 路由请求。

VS Code 内也可走 Settings → Extensions → Codex → API Key 字段粘贴 sk-…,效果等同 2 + 3 步。

2.3 桌面 app

bash
# CLI 安装好后,内置桌面 app 子命令
codex app

# 首次打开会弹 sign-in 对话框,同 2.2 一样:
#   选 "Use API Key" → 粘贴 sk-… → 确定

切换模型:把步骤 1 配置文件里的 model = "gpt-5.4" 改成任意 OpenAI 兼容模型(如 gpt-5.5gpt-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 后重新登录。

官方 openai Python 包构造函数接受 base_url + api_key(snake_case),改一行即可。

python
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),改一行即可。

typescript
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 更精准)。下表列出最常见的三种:

HTTPbody error.code含义 / 处理
401invalid_authenticationAPI key 无效或缺 sk- 前缀。 portal /keys 重新复制完整 51 字符串。
403insufficient_user_quota账户余额不足(注:HTTP 语义上更接近 402 Payment Required;新版会改 status 码,当前以 body 的 error.code 为准)。 前往 /balance 查看余额,/pay 充值。
503no 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 等)开箱即用。所有报错请求一律不计费。

HTTPerror.type / error.code含义 / 处理
400user_error / moderation_blocked内容安全审核拒绝(提示词或参考图触发安全策略)。原样重发无效,请改写提示词或更换素材。
400invalid_request_error / invalid_image · invalid_value · invalid_request请求本身的问题:参考图损坏或格式不支持(invalid_image,多图时 message 会标注第几张)、尺寸/参数非法(invalid_value,param 指向出错字段)。修正请求后重发。
401invalid_request_error / invalid_api_keyAPI key 无效或已禁用。到 /keys 重新复制完整 key。
429insufficient_quota / insufficient_quota账户余额不足。前往 /pay 充值后重试。
429rate_limit_error / rate_limit_exceeded限流/并发排队。按响应头 Retry-After 的秒数退避后重发(密集立即重发会加剧排队)。
500server_error / —平台或上游临时错误(超时、网络抖动、空返回)。直接重试即可。
503server_error / —线路繁忙(overloaded)。稍等 30 秒以上再重试。

错误体示例(审核拒绝):

json
{
  "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 兼容路径收到:
json
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_turnMAX_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/completionsOpenAI 兼容所有文本 / 多模态模型(推荐主用)
/v1/messagesAnthropic 原生Claude 系列
/v1/images/generationsOpenAI 图像兼容gpt-image-2 / DALL·E 系
/v1beta/models/<model>:generateContentGemini 原生Gemini 高清图像 2K / 4K
GET /v1/modelsOpenAI 兼容 + 扩展你的 key 可用的模型 + 价格/模态元数据(见第 18 章)
GET /v1/keySilk Road 扩展key 自查:档次 / 账户余额 / 用量(见第 19 章)

11文本调用示例

⚠️ Claude 系列 + Cline / Cursor / Roo Code 请把 max_tokens 设为 ≤ 4096 —— 上游有此限制,超过会返 502(已知问题,持续跟进)。在 Cline 里请选 OpenAI Compatible provider, 不要选 Anthropic provider(否则会被 SDK 锁住 max_tokens)。

Python(openai SDK)

python
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)

typescript
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

bash
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 原生格式(可选)

bash
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-preview2048×2048(2K)¥0.20 / 张高速 + 高清
gemini-3-pro-image-preview4096×4096(4K)¥0.50 / 张旗舰,最高画质
gemini-3-pro-image-preview-2k2048×2048(2K)¥0.30 / 张旗舰画质 · 省钱 2K(比 4K 省 40%)
📐 「档」是像素预算,不是固定方边长。 上表尺寸为 1:1 比例下的值;同一档总像素量不变,实际宽高随比例重新分布 —— 指定 16:9 等宽幅时长边更大(2K 长边 ≈ 2816、4K ≈ 5504)。不指定比例时: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

bash
# 文生图 — 用哪个模型就拿哪档分辨率(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 = "![image](https://images.silkroadai.io/gen/….png)"

传图改图:content 用 OpenAI 多模态数组,加一个 image_url(data URL 最稳;外部 http(s) URL 平台代拉,单图 ≤ 20MB,内网地址拒绝)。

json
{ "role": "user", "content": [
  { "type": "text", "text": "给这只猫戴一顶圣诞帽" },
  { "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,<BASE64>" } }
] }

图片默认存平台图床(不保证长期保留,重要图请及时转存)。想让图片直接进自己的 bucket、用自己的域名 存储设置 配置自定义 OSS(R2 / 阿里 OSS / 腾讯 COS / AWS S3 / 自建;故障自动回退平台图床,不影响出图)。

OpenAI 兼容接口现在直接返回该模型的最大分辨率(2K / 4K)。 平台代理会把 /v1/chat/completions 自动翻译到 Gemini 原生接口并注入 imageConfig.imageSize—— 用哪个模型就拿哪档分辨率,无需任何额外参数(2026-06-05 起,旧式只出 1K 的问题已解决)。
💰 要旗舰画质又想省钱?用 2K 折扣型号 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)

bash
# 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

python
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 模型即可。

💡 计费按 model 名算: 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" }] }

bash
# 文生图 — /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_formaturl(默认,进图床)/ b64_jsonb64_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 R2https://<account_id>.r2.cloudflarestorage.com留空
阿里云 OSShttps://oss-cn-hangzhou.aliyuncs.com留空
腾讯云 COShttps://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 调用。

💰 计价:按 token 计费,¥1.3 = 官方 $1 —— 按官方 gpt-image 的真实 token 用量结算(官方价:输入 $5 / 图像输入 $8 / 输出 $30,每百万 token;图生图的参考图算图像输入)。成本主要由 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)

参数必填说明
modelgpt-image-2
prompt图像文字描述
qualitylow / medium / high / auto(默认)—— 直接决定成本,见上表
size1024x1024 / 1536x1024 / 1024x1536 / auto;最高 3840x2160
output_formatpng(默认)/ jpeg(webp 暂不支持)
n张数,默认 1(建议 1,多张分多次更稳)
response_format默认 b64_json;传 url 则存图床(默认 images.silkroadai.io 或你配置的 OSS)返回 URL
bash
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"
  }'
python
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))
typescript
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)

上传一张(或多张)参考图 + 修改要求,返回改后的图。

字段必填说明
modelgpt-image-2(或专用档)
prompt修改要求
image原图文件;可重复传多张参考图
quality / size同文生图;默认回 b64_json,传 response_format: url 存图床返 URL
bash
curl https://ai.silkroadai.io/v1/images/edits \
  -H "Authorization: Bearer sk-你的KEY" \
  -F model=gpt-image-2 \
  -F prompt="把背景换成雪景" \
  -F image=@cat.png
python
from 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))

响应格式

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 → 走文生图。原来的两个独立接口照常可用、行为不变。
⏱️ 4K(size=3840x2160)又慢又大:单张约 7–8MB、生成最长约 120s。接入务必把超时设到 ≥ 180s 并对偶发断连重试一次;不强求 4K 时用默认 size 更快更省;4K 配 quality=high 的 token 成本最高。Python:OpenAI(..., timeout=180.0, max_retries=2)
🛡️ 内容准则:禁止暴力 / 血腥 / 未成年 / NSFW、侵权 / 违法 / 恐怖活动相关(即便无关键词、被识别出意图也不出图)。ComfyUI 用户不要带 SD 式负面提示词(易被风控误伤);图生图时参考图含上述内容同样不出图。

错误处理

上游报错原样透传,HTTP 状态码即上游状态码,响应体为 OpenAI 错误格式;按非 2xx 状态码 + error.message 处理。

状态码含义处理
401Key 无效检查 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)
📐 合规尺寸规则:宽、高都是 16 的倍数 · 长边 1024~3840 · 短边 ≤ 2160 · 长宽比 ≤ 3:1
合规例:1024x1024 / 1536x1024 / 3072x1024 / 3840x2160;非法例:3200x1024(比例 > 3:1)、3840x2176(短边 > 2160)、1024x641(非 16 倍数)。
bash
# 严格模式:非法参数直接 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 生图等),文生图 / 图生图都支持。

🔀 用法:在原来的图片接口后加一个 query 参数 ?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)

bash
# ① 提交(文生图;图生图用 /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"

查询响应结构

json
{
  "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].url

Python(提交 + 轮询封装)

python
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 一份结果,你就不用轮询了:

bash
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 的内容:

json
{
  "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计费 · 账户 · 网络

  • 实时余额/balance —— 余额 + 累计消费
  • 充值/pay —— 支付宝 / 微信 / Stripe
  • 用量明细/usage —— 按模型 / token / 日期

用 API 查询余额

💡 想用脚本 / 监控查余额,请用下面的 /v1/balance ——不是上面的 /balance 网页。鉴权用你的 API Key(sk-…),和调用模型同一个。

① 查余额(推荐,直接返回人民币)

bash
curl https://ai.silkroadai.io/v1/balance \
  -H "Authorization: Bearer sk-…"
json
{
  "object": "balance",
  "currency": "CNY",
  "balance_cny": 268.46,
  "used_cny": 951.54,
  "balance_usd": 38.35
}

balance_cny = 可用余额(¥)· used_cny = 累计消费(¥,已扣视频等失败任务的退款,与控制台「概览」一致)· balance_usd = 余额折算美元。

Python

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(单位美元)。

bash
# 总额度(美元)
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.93

Key 无效 / 停用返 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)。

⚠️ 需先在「API 密钥」页创建一把 「seedance逆向低价」档 的 key(创建密钥时在档次里选它)。该 key 专用于下列 seedance-2.0-720 / seedance-2.0-1080 模型;调别的模型请用默认档 key。

模型与价格(按视频秒数)

模型分辨率价格10 秒 / 15 秒
seedance-2.0-720720P¥0.60 / 秒¥6.00 / ¥9.00
seedance-2.0-10801080P¥0.72 / 秒¥7.20 / ¥10.80

按视频秒数计费;seconds 控制时长,当前支持 10 / 15(字符串)。分辨率由模型名决定。

1) 提交任务(文生视频)

bash
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) 轮询直到完成

bash
curl https://ai.silkroadai.io/v1/video/generations/task_xxx -H "Authorization: Bearer 你的key"
# status: in_progress … 几分钟后 "status": "completed"
# 视频直链在响应的 video_url 字段(公网 .mp4)
⚠️ 务必轮询到 status 变 completed / SUCCESS 再取视频。 生成中(in_progress)时 video_url 为空(或临时链),取了也打不开 —— 这是「扣钱没出片」最常见的原因。完成后 video_url 是我们的公网永久直链,可直接播放 / 下载。

参数总表

参数必填说明
model必填seedance-2.0-720(720P)/ seedance-2.0-1080(1080P)
prompt必填画面提示词;多素材时用 @Image1 / @Video1 / @Audio1 显式指代(见下)
aspect_ratio16: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_modeauto(默认,多图参考)/ start_frame(正好 1 图=首帧)/ start_end(正好 2 图=首尾帧)

@ 引用语法(多素材必读)

多素材组合时,模型靠 prompt 里的 @ 标记识别每个素材的角色: @Image1 = reference_image_urls 第 1 张、@Video1 = reference_videos 第 1 个、@Audio1 = reference_audios 第 1 个,依此类推。不显式 @ 指代,模型会瞎猜哪张图是什么。

玩法示例

1) 图生视频(单图)

bash
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) 多图组合(角色 + 场景,@ 引用)

bash
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 张图)

bash
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 张图)

bash
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) 全能参考(图 + 视频 + 音频,卡点 / 配乐)

bash
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 完整示例(提交 + 轮询)

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 是两套独立的源与价格)。支持文生 / 图生 / 首尾帧 / 参考音频,异步接口(提交 → 轮询),按视频秒数计费。

⚠️ 需先在「API 密钥」页创建一把 「seedance海外满血」档 的 key(创建密钥时在档次里选它)。该 key 专用于下列 dreamina-seedance-2-0-* 模型;调别的模型请用默认档 key。
🔊 视频默认带声音:Seedance 2.0 会为画面自动生成 AI 环境音 / 音效,默认开启且不额外收费。 不想要声音时传 "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) 文生视频

bash
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)

bash
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_urls

3) 首尾帧过渡(-ref + first_frame/last_frame)

bash
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)

bash
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)

bash
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 指代

轮询取片

bash
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_ratio16: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 完整示例(提交 + 轮询)

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」章节同一套调用方式。

⚠️ 需先在「API 密钥」页创建一把 「seedance 国内企业级端口」档 的 key(创建密钥时在档次里选它)。 该 key 专用于下列 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) 提交任务(文生视频)

bash
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) 轮询直到完成

bash
curl https://ai.silkroadai.io/v1/video/generations/cgt_xxx -H "Authorization: Bearer 你的key"
# status: in_progress … 几分钟后 "status": "completed"
# 视频直链在响应的 video_url 字段
⚠️ 视频直链是火山官方 VOD 的签名链接,约 24 小时后过期。 完成后请尽快下载或转存到你自己的存储;过期后需重新生成。 (与其它 Seedance 档不同:本档返回火山官方直链以保证资源真实性,不做永久托管。)另注: 生成中(in_progress)时 video_url 为空,务必轮询到 completed 再取。

参数总表

参数必填说明
model必填seedance2.0-pro-{720p|1080p|4k}(文生)或加 -ref 后缀(图生 / 首尾帧 / 多图 / 参考视频)
prompt必填画面提示词
duration时长秒数,5 / 10,默认 5(也接受 seconds)
aspect_ratio16: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 模型)

bash
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) 首尾帧

bash
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) 多图参考 + 参考音频

bash
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 秒

响应示例(单个条目)

json
{
  "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:列出你可用的视觉模型和价格

bash
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:选出最便宜的可对话模型

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 = 余额服务暂不可用(稍后重试)

响应示例

json
{
  "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 / tierkey 别名、状态(能查到的必为 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

bash
curl -s https://ai.silkroadai.io/v1/key -H "Authorization: Bearer sk-…" | jq .data.account_balance

Python:余额低于阈值告警(可放 cron)

python
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 返回用量:

json
{
  "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 表示还有下一页
typeconsume(默认,成功扣费)· error(失败调用)· refund(退款,如视频任务失败退回)· all
key_onlytrue = 只看当前这把 key 的调用(默认返回整个账户所有 key)

单条对账(curl)

bash
# 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-…"

响应示例

json
{
  "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 同源
billingper_token = 按 token 计费(LLM / gpt-image 系),usage 就是计费依据;per_call = 按次/按张计费(Gemini 生图等固定单价),此时 token 数是上游噪声、仅供参考,以 cost_cny 为准
created_at / duration_ms入账时间(unix 秒,UTC)/ 调用耗时(毫秒)
content计费说明(倍率明细)或失败原因(type=error 时)

Python:拉当天账单,按模型汇总

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