API 参考

完整端点说明：请求参数、响应格式、流式协议、错误码、协议互通性。所有示例可直接复制粘贴运行，把 stk-live-... 换成你自己的 API Key 即可。

5.1 通用约定

协议互通性

Smartoken 同时支持三种主流协议：

• /v1/chat/completions —— OpenAI 经典 Chat Completions，请求体用 messages
• /v1/responses —— OpenAI Responses API，请求体用 input + instructions
• /v1/messages —— Anthropic Messages API，请求体用 messages + 顶层 system + 必填 max_tokens

三个端点都能用于任意 LLM 模型——平台内部自动双向翻译，包括工具调用（tool_calls ↔ function_call ↔ tool_use）、tool_result 反向消息等。文生图 / 文生视频只支持 OpenAI 协议（Anthropic Messages 协议本身不涵盖媒体生成）。

实际效果：

• 客户端只会说 OpenAI Chat（例如 Cursor）—— 可以调任意模型，哪怕上游是只接受 Anthropic 协议的渠道
• 客户端只会说 Anthropic（例如 Claude Code）—— 可以调任意模型，哪怕上游是只支持 Chat 的第三方代理
• 任意组合都行

5.2 GET /v1/models

列出所有可见模型，无需鉴权。

curl https://smartoken.top/v1/models

返回 { object: "list", data: [...] } 结构，每个 model 对象包含：

{
  "object": "list",
  "data": [
    {
      "id": "gpt-5.4-mini",
      "display_name": "GPT 5.4 Mini",
      "description": "快速、平衡的通用模型",
      "model_type": "llm",
      "context_length": 128000,
      "pricing": {
        "input_per_mtok": 150000,
        "output_per_mtok": 600000,
        "cache_read_per_mtok": 30000,
        "per_image": 0
      },
      "available_sizes": [],
      "available_ratios": [],
      "available_durations": [],
      "video_price_per_second_by_resolution": {}
    }
  ]
}

字段说明：

• id：模型 slug，调用时填入请求体的 model 字段
• model_type：llm / text2image / text2video
• pricing.*：单位 µUSD（百万分之一美元）。per_image 仅 text2image 模型有意义
• context_length：LLM 上下文窗口（token）；非 LLM 模型为 null
• available_sizes：text2image 模型允许的尺寸枚举（如 ["1664x928", "1328x1328"]）
• available_ratios / available_durations：text2video 模型允许的比例 / 时长枚举
• video_price_per_second_by_resolution：text2video 模型，分辨率 → 每秒单价（µUSD）字典

5.3 POST /v1/chat/completions

经典 OpenAI Chat Completions 接口，完全兼容。

非流式

curl https://smartoken.top/v1/chat/completions \
  -H "Authorization: Bearer stk-live-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {"role": "system", "content": "你是一个友好的助手。"},
      {"role": "user", "content": "你好"}
    ]
  }'

流式

加 "stream": true，返回 text/event-stream。SSE 格式与 OpenAI 完全一致，每条 data: 是一个 JSON chunk，最后是 data: [DONE]。

curl -N https://smartoken.top/v1/chat/completions \
  -H "Authorization: Bearer stk-live-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [{"role": "user", "content": "讲个笑话"}],
    "stream": true
  }'

常用参数

平台原样透传 OpenAI 标准字段：

模型特定字段（如 enable_thinking、reasoning_effort 等）原样透传给上游，不在白名单里——你的模型支持什么就能用什么。

多模态

图片输入直接按 OpenAI 标准用 image_url 即可：

{
  "model": "<vision 模型 slug>",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "这张图里有什么？"},
      {"type": "image_url", "image_url": {"url": "https://example.com/a.jpg"}}
    ]
  }]
}

如果该模型实际接的是 Responses 渠道，平台会自动把 image_url 翻译成 input_image。

工具调用

{
  "model": "<你的模型 slug>",
  "messages": [{"role": "user", "content": "今天东京天气怎么样？"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "查询某城市的实时天气",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}

返回的 choices[0].message.tool_calls 与 OpenAI 完全一致。把工具执行结果用 {"role":"tool","tool_call_id":"...","content":"..."} 加回 messages 再次请求即可继续。

Query 参数

• ?channel=<name> —— 跳过路由直接指定渠道，用于排查 / 比对，不建议长期挂在生产代码里

5.4 POST /v1/responses

OpenAI Responses API 入口，给 Codex CLI、Cursor 部分模式、OpenAI Agents SDK 这类原生说 Responses 协议的客户端用。

curl https://smartoken.top/v1/responses \
  -H "Authorization: Bearer stk-live-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "instructions": "你是一个友好的助手。",
    "input": [
      {"role": "user", "content": [{"type": "input_text", "text": "你好"}]}
    ]
  }'

与 Chat Completions 的对应关系

平台双向翻译，两个端点对同一模型都能用。

流式

{ "stream": true, ... }

SSE 事件类型与 OpenAI Responses API 一致：response.created、response.in_progress、response.output_text.delta、response.completed 等。每个事件携带 sequence_number，最终事件 response.completed 的 response.usage 里有 input_tokens / output_tokens / total_tokens。

5.5 POST /v1/messages

Anthropic Messages API 入口，给 anthropic Python SDK、Claude Code、Claude Agent SDK 等原生说 Anthropic 协议的客户端用。

curl https://smartoken.top/v1/messages \
  -H "x-api-key: stk-live-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<你的模型 slug>",
    "max_tokens": 1024,
    "system": "你是一个友好的助手。",
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

必填字段

可选字段

与 OpenAI Chat 的字段对应

流式

加 "stream": true，返回的 SSE 事件序列与 Anthropic 原生格式一致：

event: message_start         ← 携带 message id / role / model
event: ping
event: content_block_start   ← {type:"text"} 或 {type:"tool_use"}
event: content_block_delta   ← text_delta 或 input_json_delta
event: content_block_stop
event: message_delta         ← stop_reason + 累计 output_tokens
event: message_stop

工具调用的参数 JSON 通过 input_json_delta 增量推送，客户端需要拼接完整 JSON 字符串再 parse。

多模态

当前版本暂不支持多模态图片输入——如果请求的 content 数组里包含 {type:"image", source:...} block，平台会替换为占位文本传给上游，避免 400 阻塞流程。下个版本会原生支持。需要立即用 vision，请走 /v1/chat/completions 端点。

不支持 / 静默丢弃的特性

• thinking blocks（Claude 推理模式）—— 从上游返回时丢弃，不映射进响应
• metadata / cache_control —— 透传给上游，但翻译层不解析

5.6 POST /v1/images/generations

文生图。

curl https://smartoken.top/v1/images/generations \
  -H "Authorization: Bearer stk-live-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<图像模型 slug>",
    "prompt": "雪山中的狐狸，油画风格",
    "n": 1,
    "size": "1024x1024"
  }'

返回与 OpenAI 一致：

{
  "created": 1717209600,
  "data": [{"url": "https://oss.smartoken.top/.../xxx.png"}]
}

注意点：

• 返回的 URL 是 Smartoken 自己 OSS 上的稳定地址（不依赖上游临时链接），可以直接在你应用里热链接、长期保存
• size 限制：每个模型在管理后台声明了允许的尺寸列表（如 1664x928、1328x1328），非列表内的尺寸会被 400 拒绝。具体支持哪些 size 在 模型市场  的模型详情页能看到
• 计费：按张数 × 模型 per_image 单价

5.7 POST /v1/videos/generations

文生视频。

curl https://smartoken.top/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
  }'

字段：

• resolution 必填，必须命中模型的允许列表
• duration 必填（秒），必须命中模型的允许列表
• ratio 可选

返回与 image 同结构 { created, data:[{url}] }，URL 指向 Smartoken OSS 上的 mp4（Content-Type: video/mp4）。

计费：该分辨率每秒单价 × duration。

5.8 流式输出说明

所有支持流式的端点用法相同：请求体加 "stream": true，响应是 text/event-stream，每行 data: <json> 一个事件，结束是 data: [DONE]。

行为细节：

1. usage 始终在尾部——chat 端点平台强制注入 stream_options.include_usage=true，最后一条 chunk 携带 usage；Responses 端点在 response.completed 事件的 response.usage 里；Anthropic 端点在 message_delta 事件的 usage.output_tokens 里
2. 中途断开按已返回部分计费——客户端 abort、网络中断都不会丢账，平台用实际收到的 usage 结算
3. 失败时回退——如果首选渠道在流式输出到一半时挂了，平台不会自动切换到下一个渠道（流式无法重放给客户端），会以错误事件结束。非流式情况下 5xx / 超时会自动 failover 到下一个渠道

5.9 错误处理与重试建议

错误响应统一格式：

{
  "error": {
    "message": "human-readable description",
    "type": "...",
    "code": "..."
  }
}

常见 HTTP 状态码：