API 文档

1快速开始

所有接口统一以 base_url 为前缀：

http://<你的服务器地址>/v1

把 <你的服务器地址> 换成客服提供的服务器地址（IP 或域名）。每次请求都要带鉴权头：

Authorization: Bearer sk-...

• API Key（形如 sk- 开头）由客服 / 管理员发放并预充余额，第一期不支持自助注册。
• 协议与 OpenAI 完全兼容，可直接使用官方 openai Python / Node SDK，只需把 base_url 指向上面的地址、api_key 填你的 sk- Key。
• 计费按用量实时扣减 Key 余额：对话按 token（输入 / 输出分别计价），生图按张。余额与流水可用 查询接口 查看。

2模型与计价

当前已开放的模型如下。可用 GET /v1/models 查询实时列表。

3对话接口

POST /v1/chat/completions —— OpenAI Chat Completions 兼容。请求体常用字段：model（模型名）、messages（消息数组）、stream（是否流式，默认 false）。响应原样透传上游的 OpenAI 格式结果（含 id / choices / usage）。

例 1 · 非流式对话

curl http://<你的服务器地址>/v1/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-vl-plus",
    "messages": [
      {"role": "user", "content": "你好，用一句话介绍你自己"}
    ]
  }'

{
  "id": "chatcmpl-xxxxxxxx",
  "object": "chat.completion",
  "model": "qwen3-vl-plus",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "我是有鱼智能体……"},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 100, "completion_tokens": 50, "total_tokens": 150}
}

扣费按 usage.prompt_tokens 与 usage.completion_tokens 分别乘对应单价结算。

例 2 · 流式对话（SSE）

请求体加 "stream": true 即可。无需自己传 stream_options——网关会自动注入 stream_options.include_usage，让末段返回带 usage 供计费。

curl http://<你的服务器地址>/v1/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-vl-plus",
    "messages": [{"role": "user", "content": "讲个笑话"}],
    "stream": true
  }'

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","model":"qwen3-vl-plus","choices":[{"index":0,"delta":{"content":"为什"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","model":"qwen3-vl-plus","choices":[{"index":0,"delta":{"content":"么…"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","model":"qwen3-vl-plus","choices":[],"usage":{"prompt_tokens":100,"completion_tokens":50,"total_tokens":150}}

data: [DONE]

• 每帧格式为 data: {JSON}，帧之间以空行（\n\n）分隔。
• 正文增量在 choices[0].delta.content；finish_reason 为 null 表示还没结束。
• 终段 usage chunk：choices 为空数组 []、带 usage 字段——这是最后一帧数据，用于计费统计。
• 流以 data: [DONE] 结束。

多模态 · 读图（image_url）

qwen3-vl-plus 支持读图。把 content 写成数组，混合 text 与 image_url 元素即可；图片可用公网 URL 或 data: URI。

{
  "model": "qwen3-vl-plus",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "这张图里是什么衣服？"},
        {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
      ]
    }
  ]
}

image_url.url 也可直接内联 base64，例如 "data:image/jpeg;base64,/9j/4AAQ..."。

4生图接口

POST /v1/images/generations。请求体字段：

• model：生图模型名（见价目表）。
• prompt：文本提示词。
• size：比例，如 "1:1"、"3:4"、"2:3"、"16:9"。
• n：生成张数，最多 4（超过 4 自动夹到 4；非法值 0 / 非整数会返回 400）。
• image（选填）：参考图数组，每个元素为公网 URL 或 data: URI，用于图生图 / 参考图。

异步模型（gpt-image-2）· 提交 + 轮询

异步模型提交后返回一个任务 id，需要按 id 轮询任务结果。

例 3 · 提交任务 + 轮询

curl http://<你的服务器地址>/v1/images/generations \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只戴墨镜的柯基，扁平插画风",
    "size": "1:1",
    "n": 1
  }'

{"id": "任务ID", ...}

curl http://<你的服务器地址>/v1/tasks/任务ID \
  -H "Authorization: Bearer sk-..."

{
  "id": "任务ID",
  "state": "succeeded",
  "data": {
    "images": [
      {"url": "https://.../result.png"}
    ]
  }
}

• GET /v1/tasks/{id} 的 state 取值：pending（排队）/ running（生成中）/ succeeded（成功）/ error（失败）。
• 成功后到 data.images[].url 取图片地址。图片 URL 有时效，请尽快下载保存。
• 只能查询你自己 Key 提交的任务；查别人的或不存在的任务返回 404 task_not_found。

同步模型（doubao-seedream-4-0-250828）· 直接返回

同步模型无需轮询，请求成功后直接返回 data 数组（OpenAI 标准生图格式），按实际返回张数后付费扣费。

{
  "created": 1750000000,
  "data": [
    {"url": "https://.../image.png"}
  ]
}

5Python 示例

流式对话（openai SDK）

from openai import OpenAI

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

stream = client.chat.completions.create(
    model="qwen3-vl-plus",
    messages=[{"role": "user", "content": "用三句话介绍杭州"}],
    stream=True,
)
for chunk in stream:
    # 终段 usage chunk 的 choices 为空数组，这里的判断会自动跳过它
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

生图：提交 + requests 轮询

生图不是 OpenAI SDK 的标准异步流程，直接用 requests 提交并轮询更直观。

import time
import requests

BASE = "http://<你的服务器地址>/v1"
KEY = "sk-..."
headers = {"Authorization": f"Bearer {KEY}"}

# 1. 提交生图任务
resp = requests.post(
    f"{BASE}/images/generations",
    headers=headers,
    json={"model": "gpt-image-2", "prompt": "雪山下的湖泊，写实风格",
          "size": "1:1", "n": 1},
    timeout=60,
)
resp.raise_for_status()
task_id = resp.json()["id"]

# 2. 每 3 秒轮询一次，直到终态
while True:
    time.sleep(3)
    r = requests.get(f"{BASE}/tasks/{task_id}", headers=headers, timeout=30)
    r.raise_for_status()
    state = r.json().get("state")
    if state == "succeeded":
        for img in r.json()["data"]["images"]:
            print(img["url"])          # URL 有时效，尽快下载
        break
    if state == "error":
        print("生成失败，费用已自动退回")
        break

6查询接口

GET /v1/me · 余额 / 今日用量 / 近 20 条流水

curl http://<你的服务器地址>/v1/me \
  -H "Authorization: Bearer sk-..."

{
  "name": "你的 Key 名称",
  "balance_micro": 4876544,
  "balance_yuan": "4.8765",
  "today": {"requests": 12, "cost_yuan": "1.2340"},
  "recent": [
    {
      "ts": 1750000000,
      "type": "charge",
      "model": "qwen3-vl-plus",
      "kind": "chat",
      "delta_yuan": "-0.0005",
      "status": "ok"
    }
  ]
}

• balance_micro：余额（整数微元，1 元 = 1,000,000 微元）；balance_yuan：余额（元，固定 4 位小数字符串）。
• today.requests：今日请求数；today.cost_yuan：今日消费（元）。
• recent：最近至多 20 条流水，每条含 ts（Unix 秒级时间戳）、type（charge 扣费 / refund 退款 / topup 充值等）、model、kind（chat / image）、delta_yuan（金额变动，负为扣费）、status。

GET /v1/models · 模型列表

curl http://<你的服务器地址>/v1/models \
  -H "Authorization: Bearer sk-..."

{
  "object": "list",
  "data": [
    {"id": "qwen3-vl-plus", "object": "model", "owned_by": "ecworkflow", "ecw_kind": "chat"},
    {"id": "gpt-image-2", "object": "model", "owned_by": "ecworkflow", "ecw_kind": "image"}
  ]
}

ecw_kind 是本平台的扩展字段（非 OpenAI 标准），取值 chat 或 image，方便你区分对话模型与生图模型（OpenAI SDK 会自动忽略这个多余字段，不影响兼容）。

7错误码表

所有错误统一为 OpenAI 风格 JSON 结构：

{"error": {"message": "...", "type": "...", "code": "..."}}