集成文档
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 更精准)。下表列出最常见的三种:
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 |
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)· 可选 2K | ¥0.50 / 张 | 旗舰,最高画质 |
| gemini-3-pro-image-preview-2k | 2048×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。
# 文生图 — 用哪个模型就拿哪档分辨率(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 的问题已解决)。 只有需要自定义出图比例(aspectRatio)时,才用下面的原生 /v1beta/models/<model>:generateContent endpoint(默认比例 1:1)。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)
# 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 模型即可。
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
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"
}'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)
curl https://ai.silkroadai.io/v1/images/edits \
-H "Authorization: Bearer sk-你的KEY" \
-F model=gpt-image-2 \
-F prompt="把背景换成雪景" \
-F image=@cat.pngdata[0].b64_json(Base64 的 PNG,自行解码保存;始终返回 b64,传 response_format=url 也回 b64)。实际按 ¥0.05 / 张扣费,响应里的 usage 仅平台估算、勿用于对账。 上游报错原样透传(状态码 + OpenAI 错误体)。OpenAI(..., timeout=180.0, max_retries=2)14计费 · 账户 · 网络
网络:接入点 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-fast | 480P | ¥0.04 / 秒 | ¥0.20 / ¥0.60 |
| seedance-2.0-1080p | 1080P | ¥0.12 / 秒 | ¥0.60 / ¥1.80 |
按视频实际时长(秒)计费;duration 控制秒数(默认 4 秒)。
1) 提交任务
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) 轮询直到完成
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(提交 + 轮询)
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 张。
图生视频(一张图当首帧,让它动)
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" }'首尾帧(给开头和结尾,补中间过程)
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。
参考生(锁人物 / 风格一致)
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_ratio、resolution、generate_audio、camera_fixed。纯文生较慢(约 3–6 分钟),偶发 504 重试即可;视频直链约 24 小时失效,请及时转存。
3 个模型同一接口,只改 model。
遇到问题?
微信 Global_Ads · 邮箱 support@silkroadai.io