Skip to Content
5. API 参考

API 参考

  • Base URL: http://localhost:8000/v1（生产请替换为实际地址）
  • 鉴权: Authorization: Bearer stk-live-…

POST /v1/chat/completions

与 OpenAI Chat Completions 接口完全兼容：

curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer stk-live-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek/deepseek-chat",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'

支持的常用参数：messages、stream、temperature、max_tokens、tools / tool_choice。其它参数（如 enable_thinking 等上游特定字段）也会原样透传，不在我们枚举范围内的字段不做白名单限制。

可选 query 参数 ?channel=<name>：跳过路由直接指定渠道（用于排查 / 比对，不建议长期使用）。

POST /v1/responses

OpenAI Responses API 入口，给 Codex / Cursor / Agents SDK 这类原生说 Responses 协议的客户端用。请求体的 input 是消息列表，每条 content 是 [{type:"input_text",text}]；可选 instructions 当系统提示；用 max_output_tokens 代替 max_tokens。

curl http://localhost:8000/v1/responses \
  -H "Authorization: Bearer stk-live-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": [
      {"role":"user","content":[{"type":"input_text","text":"你好"}]}
    ],
    "stream": false
  }'

该端点只路由到 wire_api=responses 的渠道（运营在管理后台为渠道勾选）。常用场景是接入 ChatGPT Plus / Pro 订阅账户：管理员配好 OAuth 中继账户 + responses 渠道后，客户端无感切换。

POST /v1/images/generations

curl http://localhost:8000/v1/images/generations \
  -H "Authorization: Bearer stk-live-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/dall-e-3",
    "prompt": "雪山中的狐狸，油画",
    "n": 1,
    "size": "1024x1024"
  }'

返回的 URL 是 Smartoken 自己 OSS 上的稳定地址（不依赖上游的临时链接），可以直接热链接。

size 限制：每个模型在管理后台声明了一组可用尺寸（如 1664x928、1328x1328 等）；非声明列表里的 size 会被 400 拒绝。模型市场的详情页可以看到该模型支持的全部尺寸。

POST /v1/videos/generations

文生视频。resolution 和 duration 必填，且必须命中该模型在管理后台声明的允许列表；ratio 选填。计费 = 该分辨率每秒单价 × duration。

curl http://localhost:8000/v1/videos/generations \
  -H "Authorization: Bearer stk-live-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-t2v",
    "prompt": "A miniature city built from cardboard and bottle caps comes alive at night.",
    "resolution": "720P",
    "ratio": "16:9",
    "duration": 5
  }'

返回与 /v1/images/generations 同形态：{ created, data:[{url}] }，URL 指向 Smartoken OSS 上的 mp4（content-type=video/mp4）。视频生成是异步任务，单次调用通常 60-180s 才返回，请把客户端超时设到 5-10 分钟。

GET /v1/models

列出所有可用模型，无需鉴权。返回 OpenAI 兼容的 { object: "list", data: [...] } 结构，每个对象额外带：

  • model_type：llm | text2image | text2video。
  • pricing：含 input_per_mtok / output_per_mtok / cache_read_per_mtok / per_image。
  • video_price_per_second_by_resolution：text2video 模型的分辨率-每秒价字典（µUSD/sec）。
  • available_sizes / available_ratios / available_durations：声明的允许列表。
  • context_length：LLM 模型的上下文窗口（token 数）。

错误码

响应体格式 { "error": { "message": "...", "type": "..." } }，常见状态码：

  • 400 请求参数错误。
  • 401 缺密钥 / 密钥失效。
  • 402 余额不足。
  • 403 该密钥无权调用此模型（或代金券白名单不匹配）。
  • 404 模型 slug 不存在。
  • 429 触发了模型限流（RPM / TPM）。
  • 500 网关内部错误。
  • 503 所有上游渠道均失败。
4. 集成与最佳实践