SU API/v1

1.基本信息

本站提供 OpenAI 兼容的对话接口，可直接用 openai SDK、LangChain、Dify、Cherry Studio、ChatBox 等客户端接入。

项目值
Base URLhttp://你的服务器地址/v1
完整地址http://你的服务器地址/v1/chat/completions
请求方法POST
鉴权请求头 Authorization: Bearer <你的 API Key>
数据格式application/json
流式响应text/event-stream（SSE，OpenAI 标准 data: 分帧）
协议兼容OpenAI Chat Completions，含 tools / tool_calls

2.获取 API Key

登录后在 控制台 → 密钥 页面创建，密钥形如 sk-xxxxxxxx。可设置额度上限与过期时间。

3.可用模型

模型 ID说明思考模式输入 / 千 tokens输出 / 千 tokens
ernie-5.1ERNIE 5.1支持¥0.0021¥0.0009
ernie-5.0-thinking-previewERNIE 5.0 Thinking支持¥0.0021¥0.0009
ernie-4.5-turbo-vlERNIE 4.5 Turbo VL—¥0.0021¥0.0009
deepseek-v4-proDeepSeek V4 Pro支持¥0.0063¥0.0027
ernie-5.0ERNIE 5.0—¥0.0021¥0.0009
ernie-4.5-turbo-32kERNIE 4.5 Turbo 32K—¥0.0018¥0.0008
ernie-4.5-turbo-128kERNIE 4.5 Turbo 128K—¥0.0021¥0.0009

把上面的模型 ID 填到 model 字段即可切换。带「思考模式」的模型会自动返回 reasoning_content，适合推理类任务。

查看当前可用模型（命令行）

bash复制
curl http://你的服务器地址/v1/models \
  -H "Authorization: Bearer $API_KEY"

返回形如 {"object":"list","data":[{"id":"ernie-5.1","object":"model","owned_by":"raccoon"},...]}。

单价 = 基础单价 × 模型倍率（当前基础输入 ¥0.0700 / 千 tokens，输出 ¥0.0300 / 千 tokens）。

4.发起对话

curl

bash复制
curl http://你的服务器地址/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

Python（openai SDK）

python复制
from openai import OpenAI

client = OpenAI(
    base_url="http://你的服务器地址/v1",
    api_key="sk-your-key",
)

resp = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

5.请求参数

参数类型必填说明
modelstring是模型 ID，见上方可用模型
messagesarray是消息数组，role 支持 system / user / assistant / tool
streambool否true 时以 SSE 流式返回，默认 false
temperaturenumber否采样温度，0 ~ 2
max_tokensint否最大生成 token 数
toolsarray否函数调用定义，见下方「函数调用」
tool_choicestring否auto / none / 指定函数
reasoning_effortstring否思考强度，非空即启用深度思考

6.非流式响应

json复制
{
  "id": "chatcmpl-7f3a9c21",
  "object": "chat.completion",
  "created": 1792496000,
  "model": "deepseek-v4-pro",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "你好！有什么可以帮你的吗？"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 12,
    "total_tokens": 20
  }
}

7.函数调用

接口完整支持 OpenAI tools 协议。模型决定调用工具时，响应中会返回 tool_calls，且 finish_reason 为 tool_calls。

第一步：携带工具定义发起请求

python复制
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "查询指定城市的实时天气",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string", "description": "城市名"}},
            "required": ["city"],
        },
    },
}]

resp = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "北京现在天气如何？"}],
    tools=tools,
)

第二步：解析 tool_calls

json复制
{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_daeb2f19",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"city\": \"北京\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

第三步：回传工具结果继续对话

把 assistant 的 tool_calls 原样放回消息历史，再追加一条 role: "tool" 消息即可。

python复制
messages.append(resp.choices[0].message.model_dump())
messages.append({
    "role": "tool",
    "tool_call_id": "call_daeb2f19",
    "content": "{\"temp\": 26, \"text\": \"晴\"}",
})

8.流式响应

text复制
data: {"id":"chatcmpl-7f3a","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-7f3a","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"你好"},"finish_reason":null}]}

data: {"id":"chatcmpl-7f3a","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":8,"completion_tokens":12,"total_tokens":20}}

data: [DONE]

命中工具调用时，会单独下发一帧 delta.tool_calls，finish_reason 为 tool_calls。

9.图像生成

用 doubao-image 模型出图。兼容 OpenAI Images 接口，也支持走 Chat 接口返回图片链接。

方式一：Images 接口（推荐）

curl复制
curl https://your-domain/ai/v1/images/generations \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-image",
    "prompt": "一只戴礼帽的猫，油画风格",
    "size": "1024x768",
    "n": 1
  }'

方式二：Chat 接口

curl复制
curl https://your-domain/ai/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-image",
    "messages": [{"role": "user", "content": "一只戴礼帽的猫"}]
  }'

返回的 content 中是 Markdown 图片语法，可直接渲染。

响应示例

json复制
{
  "created": 1792547701,
  "data": [
    {"url": "https://p26-flow-imagex-sign.byteimg.com/...png",
     "revised_prompt": "一只戴礼帽的猫"},
    {"url": "https://p26-flow-imagex-sign.byteimg.com/...png"},
    {"url": "https://p26-flow-imagex-sign.byteimg.com/...png"},
    {"url": "https://p26-flow-imagex-sign.byteimg.com/...png"}
  ]
}

尺寸与比例

上游只认以下几种比例，其余会回落到 1:1：

参数 size实际比例典型像素
1024x10241:11328×1328
1024x7684:31536×1152
768x10243:41152×1536
1792x102416:9—
1024x17929:16—

也接受直接写比例串（"4:3"）。默认每次出 4 张图，n 参数目前只作占位。

注意事项

  • 单次生图约 15–40 秒，记得把客户端超时设到 60 秒以上。
  • 返回的是带签名的临时直链，链接会过期，建议拿到就存下来。
  • 同时发起多个生图请求容易被风控，建议串行。
  • 比例由服务端后台「豆包」页的默认比例决定，请求里不传 size 时用它。

10.错误码

HTTP含义处理建议
400请求体格式错误检查 JSON 结构与必填字段
401API Key 无效或未提供检查 Authorization 头
402余额不足前往控制台充值
404模型不存在核对 model 字段
429上游额度耗尽或触发限流降低频率或稍后重试
502上游服务异常稍后重试

11.计费说明

按 token 计费，公式：费用 = (输入 tokens ÷ 1000 × 输入单价 + 输出 tokens ÷ 1000 × 输出单价) × 模型倍率。

实时用量与账单见 控制台 → 账单，完整价格表见 定价页。