网关 API 文档

鉴权

以 Bearer Token 方式发送 API Key，费用从 Key 所属账户的积分中扣除。 获取 API Key

Authorization: Bearer sk_xxxxxxxxxxxxxxxx

接口列表

创建生成任务

传入模型 ID、统一输入参数，可选指定供应商 slug。接口立即返回任务 ID；同步类供应商的图片模型可能直接返回成功结果。

curl https://01router.com/api/v1/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "provider": "fal",            // optional: omit to auto-route
    "input": {
      "prompt": "A red fox running through fresh snow, cinematic",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "generate_audio": true
    }
  }'

{
  "id": "gen_6f1c…",
  "object": "generation",
  "model": "seedance-2.5",
  "type": "video",
  "provider": "kie",
  "status": "processing",        // queued | processing | succeeded | failed
  "input": { "prompt": "…", "duration": 5, "resolution": "720p", "aspect_ratio": "16:9", "generate_audio": true },
  "outputs": [],
  "error": null,
  "credits": 512,
  "price_usd": 2.0475,
  "created_at": "2026-10-23T08:00:00.000Z",
  "completed_at": null
}

获取结果

每隔几秒轮询，直到 status 为 succeeded 或 failed。输出链接由供应商托管，可能过期，请及时下载保存；也可以传 callback_url 接收推送。

curl https://01router.com/api/v1/generations/gen_6f1c… -H "Authorization: Bearer $API_KEY"

{ "id": "gen_6f1c…", "status": "succeeded", "outputs": ["https://…/video.mp4"], … }

任务回调

传入 callback_url（公网 https 地址），任务成功或失败后我们会把最终的 generation 对象 POST 过去，失败按退避重试最多 5 次，无需轮询。

curl https://01router.com/api/v1/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "input": { "prompt": "A red fox running through fresh snow" },
    "callback_url": "https://your-app.com/webhooks/generation"
  }'

每次回调都带 X-Gateway-Timestamp 和 X-Gateway-Signature：sha256=HMAC-SHA256(你的 API Key, timestamp + "." + 原始请求体)。可以校验签名，也可以直接再调一次 GET /generations/:id 确认。

// Node.js: verify X-Gateway-Signature
import { createHmac, timingSafeEqual } from 'crypto';

const ts = req.headers['x-gateway-timestamp'];
const expected = 'sha256=' + createHmac('sha256', process.env.API_KEY)
  .update(`${ts}.${rawBody}`).digest('hex');
const ok = timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-gateway-signature']));

取消任务

POST /generations/:id/cancel 会请求供应商停止进行中的任务。供应商确认后，任务以 failed 结束（error 为 "Canceled by user"），积分全额退还。目前支持 fal（仅排队中的任务）和 Replicate；其他供应商或已结束的任务返回 409 not_cancelable。

curl -X POST https://01router.com/api/v1/generations/gen_6f1c…/cancel -H "Authorization: Bearer $API_KEY"

{ "id": "gen_6f1c…", "status": "failed", "error": "Canceled by user", "credits": 0, … }

OpenAI 兼容生图

POST /images/generations 兼容 OpenAI 图片接口，OpenAI SDK、LobeChat、Cherry Studio、Dify、n8n 都能直接调用这里的图片模型。size 会映射为最接近的 aspect_ratio，n 映射为 num_images，模型的其他参数可作为额外字段传入。最多等待约 110 秒，超时返回 504 和任务 id，可继续轮询。

from openai import OpenAI

client = OpenAI(base_url="https://01router.com/api/v1", api_key="sk_…")
res = client.images.generate(
    model="nano-banana-pro",
    prompt="A minimalist poster of a paper crane",
    size="1024x1536",   # mapped to the closest aspect_ratio
)
print(res.data[0].url)

音频模型

音乐（Suno）和语音合成（Gemini TTS）模型与图片、视频一样走 /generations：先创建任务再轮询，输出为音频文件 URL。

curl https://01router.com/api/v1/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": { "prompt": "Welcome back, let us get started.", "voice": "Kore", "style_instructions": "warm and upbeat" }
  }'

{ "id": "gen_9a2d…", "type": "audio", "status": "succeeded", "outputs": ["https://…/speech.wav"], … }

对话补全

对话模型（GPT、Claude、Gemini、Grok、DeepSeek 等）使用 OpenAI Chat Completions 格式，官方 OpenAI SDK 将 base URL 设为 https://01router.com/api/v1 即可调用。传 "stream": true 获得 SSE 流式输出。调用前按输入 + max_tokens（未传时为 4096）预扣积分，回复结束后按实际 token 用量结算；请求 ID 会出现在 X-Gateway-Request-Id 响应头和任务日志中。

curl https://01router.com/api/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5.5",
    "messages": [{ "role": "user", "content": "Write a haiku about routers" }],
    "max_tokens": 512,
    "stream": true
  }'

from openai import OpenAI

client = OpenAI(base_url="https://01router.com/api/v1", api_key="sk_…")
res = client.chat.completions.create(
    model="gpt-6-sol",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(res.choices[0].message.content, res.usage)

供应商路由

未指定 provider 时，我们会用每个供应商支持的取值校验参数并报价，提交给最便宜的供应商；提交失败会退款并尝试下一个（最多 3 家）。指定 provider 时只会发往该供应商。

自动熔断：某个供应商在同一模型上连续 5 次提交失败，会在 5 分钟内被排到最后，请求优先走健康的供应商；它仍作为最后的兜底，成功一次即恢复。

报价

请求体与创建任务相同。返回按价格排序的可用供应商，以及无法处理该请求的供应商及原因。

curl https://01router.com/api/v1/quote -H "Content-Type: application/json" \
  -d '{ "model": "nano-banana-pro", "input": { "prompt": "poster", "resolution": "2K" } }'

{
  "model": "nano-banana-pro",
  "providers": [
    { "provider": "kie", "provider_name": "KIE AI", "unit": "image", "quantity": 1, "price_usd": 0.117, "credits": 30 },
    { "provider": "openrouter", … }
  ],
  "unavailable": [{ "provider": "atlascloud", "reason": "resolution must be one of 1K, 2K" }]
}

计费

任务提交时按所选供应商对应参数的价格扣除积分（视频按秒、图片按张或按次）。失败或超时的任务会自动退还积分。

错误码

{ "error": { "message": "Insufficient credits: this request costs 512 credits", "code": "insufficient_credits" } }

全部模型 ID 与参数： 模型