返回首页

集成文档

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。

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

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)· 可选 2K¥0.50 / 张旗舰,最高画质
gemini-3-pro-image-preview-2k2048×2048(2K)¥0.30 / 张旗舰画质 · 省钱 2K(比 4K 省 40%)

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 的问题已解决)。 只有需要自定义出图比例(aspectRatio)时,才用下面的原生 /v1beta/models/<model>:generateContent endpoint(默认比例 1:1)。
💰 要旗舰画质又想省钱?用 2K 折扣型号 gemini-3-pro-image-preview-2k—— 锁定 2K 分辨率、¥0.30 / 张(比 4K 原型号省 40%),画质与 pro 旗舰同源。用法不变,把请求里的 model 换成它即可(/v1/chat/completions /v1/images/generations 都支持,出图比例照常用 aspect_ratio)。另:原型号 gemini-3-pro-image-preview 也接受 size 参数("2K"/"4K",也认 2048x2048/4096x4096)切分辨率,但价格不随尺寸变(仍 ¥0.50)—— 想省钱请认准上面带 -2k 的型号。

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

13GPT image-2 生图

OpenAI Images API 兼容 —— POST /v1/images/generations 文生图、POST /v1/images/edits 图生图。现有 OpenAI SDK 改一行 base_url 即可。返回 b64_json(Base64 PNG)。 请用 image2 分组创建的 API Key 调用全部档位。

模型分辨率价格用途
gpt-image-2自适应¥0.05 / 张默认推荐,最快
gpt-image-2-1k锁定 1K¥0.05 / 张稳定 1024
gpt-image-2-2k锁定 2K¥0.05 / 张更清晰
gpt-image-2-4k锁定 4K¥0.05 / 张最高清(较慢,见下)

专用档(-1k / -2k / -4k)会强制按各自档位输出,即使 size 传了别的尺寸。4 档同价 ¥0.05 / 张。

文生图 · /v1/images/generations

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"
  }'
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))

图生图 · /v1/images/edits(multipart)

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
🖼️ 返回与计费:图片在 data[0].b64_json(Base64 的 PNG,自行解码保存;始终返回 b64,传 response_format=url 也回 b64)。实际按 ¥0.05 / 张扣费,响应里的 usage 仅平台估算、勿用于对账。 上游报错原样透传(状态码 + OpenAI 错误体)。
⏱️ 4K(gpt-image-2-4k)又慢又大:单张约 7–8MB、生成最长约 120s。接入务必把超时设到 ≥ 180s 并对偶发断连重试一次;不强求 4K 时优先用 gpt-image-2(自适应)或 -1k / -2k,更快更稳。Python:OpenAI(..., timeout=180.0, max_retries=2)
🛡️ 内容准则:禁止暴力 / 血腥 / 未成年 / NSFW、侵权 / 违法 / 恐怖活动相关(即便无关键词、被识别出意图也不出图)。ComfyUI 用户不要带 SD 式负面提示词(易被风控误伤);图生图时参考图含上述内容同样不出图。

14计费 · 账户 · 网络

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

网络:接入点 ai.silkroadai.io 多区域 CDN,国内通常可直连。流式调用对网络稳定性敏感,丢包可能导致 502 —— 频繁出错时可尝试关闭 stream,或换用更稳定的线路。排查时把响应里的 request_id 发给客服可快速定位。

15Seedance 2.0 · 视频生成

ByteDance Seedance 2.0 视频生成,3 个分辨率档,支持文生 / 图生 / 首尾帧 / 参考生。异步接口:提交后拿到 task_id,轮询直到 SUCCESS 取视频 URL。走 /v1/video/generations,不是 /v1/chat/completions(后者会 404)。

模型分辨率价格(按秒)5 秒 / 15 秒
seedance-2.0≤ 720P¥0.04 / 秒¥0.20 / ¥0.60
seedance-2.0-fast480P¥0.04 / 秒¥0.20 / ¥0.60
seedance-2.0-1080p1080P¥0.12 / 秒¥0.60 / ¥1.80

按视频实际时长(秒)计费;duration 控制秒数(默认 4 秒)。

1) 提交任务

bash
curl https://ai.silkroadai.io/v1/video/generations \
  -H "Authorization: Bearer sk-你的KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "seedance-2.0", "prompt": "一只猫在沙滩上散步", "duration": 5 }'
# → { "task_id": "task_xxx", "object": "video", "status": "queued", "progress": 10 }

2) 轮询直到完成

bash
curl https://ai.silkroadai.io/v1/video/generations/task_xxx -H "Authorization: Bearer sk-你的KEY"
# status: IN_PROGRESS … 约 1–2 分钟后 "status": "SUCCESS"
# 视频地址在 data.data.video_url(公网 .mp4)

Python(提交 + 轮询)

python
import time, requests

H = {"Authorization": "Bearer sk-你的KEY", "Content-Type": "application/json"}
B = "https://ai.silkroadai.io/v1/video/generations"

task = requests.post(B, headers=H, json={
    "model": "seedance-2.0", "prompt": "一只猫在沙滩上散步", "duration": 5,
}).json()
tid = task["task_id"]

while True:
    r = requests.get(f"{B}/{tid}", headers=H).json()
    status = r.get("data", {}).get("status") or r.get("status")
    if status in ("SUCCESS", "FAILURE"):
        break
    time.sleep(10)

print(r["data"]["data"]["video_url"])

进阶:图生 / 首尾帧 / 参考生

同一接口,加图片字段即可。image last_frame_image 只接受字符串(https 链接或 base64 dataURL,传数组会 400);reference_images 是数组,最多 4 张。

图生视频(一张图当首帧,让它动)

bash
curl https://ai.silkroadai.io/v1/video/generations \
  -H "Authorization: Bearer sk-你的KEY" -H "Content-Type: application/json" \
  -d '{ "model": "seedance-2.0", "prompt": "镜头缓缓推进,头发被风吹动", "duration": 5, "image": "https://你的图床/first.png" }'

首尾帧(给开头和结尾,补中间过程)

bash
curl https://ai.silkroadai.io/v1/video/generations \
  -H "Authorization: Bearer sk-你的KEY" -H "Content-Type: application/json" \
  -d '{ "model": "seedance-2.0", "prompt": "镜头从全景平滑过渡到特写", "duration": 5, "image": "https://你的图床/first.png", "last_frame_image": "https://你的图床/last.png" }'

尾帧字段名是 last_frame_image,不是 image_tail

参考生(锁人物 / 风格一致)

bash
curl https://ai.silkroadai.io/v1/video/generations \
  -H "Authorization: Bearer sk-你的KEY" -H "Content-Type: application/json" \
  -d '{ "model": "seedance-2.0", "prompt": "这个女孩在花园里奔跑,阳光明媚", "duration": 5, "reference_images": ["https://你的图床/role-a.png", "https://你的图床/role-b.png"] }'

图生:图片是视频第一帧; 参考生:图片不出现在画面里,只锁长相 / 画风。两者可同时用。

进阶可选字段(随模型透传,不填走默认): aspect_ratioresolutiongenerate_audiocamera_fixed。纯文生较慢(约 3–6 分钟),偶发 504 重试即可;视频直链约 24 小时失效,请及时转存。

3 个模型同一接口,只改 model

遇到问题?

微信 Global_Ads · 邮箱 support@silkroadai.io