API 开发文档

1快速开始

三步跑通第一个请求：

1. 注册并开通：注册平台账号，控制台「资金管理」完成测试额度开通（按量扣减）。
2. 创建 API Key：控制台「API Keys」新建密钥。密钥明文只在创建时展示一次，请立即保存；平台只存哈希，丢失只能重新创建。
3. 发起请求：向对话补全接口发送你的第一条消息。

curl https://westertoken-22231.app.workbuddy.host/api/v1/chat/completions \
  -H "Authorization: Bearer $WESTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek",
    "messages": [{"role": "user", "content": "你好，介绍一下你自己"}]
  }'

2鉴权

所有 API 请求通过 HTTP 头携带 API Key：

Authorization: Bearer wt-xxxxxxxxxxxxxxxx

• Key 全局唯一、区分状态，停用或删除后立即失效；
• 限流与用量按 Key 粒度统计，不同业务建议拆分多个 Key 便于对账；
• 可为每个 Key 设置消费上限（limitYuan），超出即拒绝请求；
• 不要把 Key 写进前端代码、公开仓库或发到群里；泄露请立即到控制台停用。

3对话补全

POST/api/v1/chat/completions

与 OpenAI /v1/chat/completions 协议兼容，请求体为 JSON：

响应示例

{
  "id": "chatcmpl-m3xk2a1",
  "object": "chat.completion",
  "created": 1793832000,
  "model": "deepseek",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "你好！我是……" },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 48,
    "total_tokens": 60
  },
  "wt": {
    "billed_yuan": 0.0007,
    "billing_error": null,
    "latency_ms": 812,
    "instance_id": "inst-a800-01"
  }
}

usage 为标准 OpenAI 字段；wt 是平台扩展的计费透明字段——本次实扣金额（元）、计费异常提示、耗时与承载实例，方便你在业务侧自助对账。

4模型列表

GET/api/v1/chat/completions

OpenAI /v1/models 风格，返回当前在售的全部模型：

curl https://westertoken-22231.app.workbuddy.host/api/v1/chat/completions \
  -H "Authorization: Bearer $WESTERTOKEN_API_KEY"

# 响应
{
  "object": "list",
  "data": [
    { "id": "deepseek", "object": "model", "owned_by": "deepseek-ai", "timeout_ms": 60000, "filing_no": "" },
    { "id": "qwen",     "object": "model", "owned_by": "alibaba",    "timeout_ms": 60000, "filing_no": "" }
  ]
}

其中 filing_no 为该模型的算法备案 / 生成式 AI 服务登记号（未核验到时为空串）。该字段为合规公示用途，OpenAI 兼容客户端会自动忽略，不影响既有调用。 完整清单见 《备案信息公示》。

5图像生成

POST/api/v1/images/generations

文生图 / 图生图，按张计费（分分辨率档），返回可下载的图片 URL：

curl https://westertoken-22231.app.workbuddy.host/api/v1/images/generations \
  -H "Authorization: Bearer $WESTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wanx",
    "prompt": "戈壁滩上的绿色数据中心，黄昏光线",
    "size": "1280x720",
    "n": 1
  }'

# 响应
{
  "created": 1793910000,
  "data": [{ "url": "https://.../img-xxxx.png" }],
  "wt": { "billed_yuan": 0.20, "latency_ms": 4300 }
}

6视频生成

POST/api/v1/videos/generations

视频生成耗时较长，采用异步任务制：创建任务 → 轮询状态 → 取结果。按秒计费（分分辨率档），仅对成功任务扣费：

第一步：创建任务

curl https://westertoken-22231.app.workbuddy.host/api/v1/videos/generations \
  -H "Authorization: Bearer $WESTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan-video",
    "prompt": "无人机航拍中卫算力园区，镜头缓缓推进",
    "duration_seconds": 5,
    "resolution": "720p",
    "image_url": "https://.../first-frame.png"
  }'

# 响应
{ "task_id": "vt-9k2m4x", "status": "queued", "created": 1793910100 }

image_url 可选，提供即按「图生视频」首帧模式生成。

第二步：轮询任务

curl https://westertoken-22231.app.workbuddy.host/api/v1/videos/generations/vt-9k2m4x \
  -H "Authorization: Bearer $WESTERTOKEN_API_KEY"

# 任务完成
{
  "task_id": "vt-9k2m4x",
  "status": "succeeded",
  "video_url": "https://.../vt-9k2m4x.mp4",
  "wt": { "billed_yuan": 1.50, "duration_seconds": 5 }
}

• 状态流转：queued → running → succeeded / failed；
• 建议 5~10 秒轮询一次，任务一般数十秒至几分钟内完成；
• 也可在后台配置 Webhook，任务完成时主动回调通知。

7语音生成

语音合成（TTS）

POST/api/v1/audio/speech

文本转语音，按字符计费，直接返回音频文件流：

curl https://westertoken-22231.app.workbuddy.host/api/v1/audio/speech \
  -H "Authorization: Bearer $WESTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cosyvoice",
    "input": "欢迎使用西部词元算力聚合平台",
    "voice": "female-default",
    "format": "mp3"
  }' -o speech.mp3

语音识别（ASR）

POST/api/v1/audio/transcriptions

音频转文本，按时长计费，multipart/form-data 上传：

curl https://westertoken-22231.app.workbuddy.host/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $WESTERTOKEN_API_KEY" \
  -F model=paraformer \
  -F file=@meeting.mp3

# 响应
{ "text": "会议纪要……", "duration_seconds": 1800 }

8流式输出

请求体传 "stream": true 即以 SSE（Server-Sent Events）返回，帧格式与 OpenAI 一致，OpenAI SDK 可直接消费：

data: {"id":"chatcmpl-m3xk2a1","object":"chat.completion.chunk","choices":[{"delta":{"content":"你"}}],"finish_reason":null}

data: {"id":"chatcmpl-m3xk2a1","object":"chat.completion.chunk","choices":[{"delta":{"content":"好"}}],"finish_reason":null}

data: [DONE]

• 每个 data: 帧为一个增量片段，按序拼接即完整回答；
• 以 data: [DONE] 结束；
• 计费仍在服务端一次性结算，与是否流式无关。

9计费与用量

• 按量计费：调用时按各模型阶梯单价（元 / 百万 token，输入输出分档）从余额实时扣减；
• 每次响应的 wt.billed_yuan 即本次实扣金额，可逐笔核对；
• 调用明细（模型、token 用量、耗时、扣费）在控制台「调用与计费」可查，账单与余额双向勾稽；
• 失败不计费：上游调用失败（502/503）不产生 token 费用；
• 单价以价格页公开口径为准：文本按 token（输入/输出分档）、图像按张、视频按秒、语音按字符/时长。

10限流

按 API Key 粒度做令牌桶限流，默认 20 QPS / 突发 60（平台可在配置中心按客户调整）：

• 触发限流返回 429，响应头带 Retry-After（秒数），按其退避重试即可；
• 并发较高的批量任务建议客户端做队列与指数退避，避免瞬间打满。

11错误码

错误统一返回 { "error": { "message", "type" } } 结构：

12SDK 示例

Python（openai SDK）

from openai import OpenAI

client = OpenAI(
    api_key="wt-xxxxxxxxxxxxxxxx",
    base_url="https://westertoken-22231.app.workbuddy.host/api/v1",
)

resp = client.chat.completions.create(
    model="deepseek",
    messages=[{"role": "user", "content": "用一句话介绍西部词元"}],
)
print(resp.choices[0].message.content)
print("本次费用(元):", resp.model_extra["wt"]["billed_yuan"])

Node.js（openai SDK）

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.WESTERTOKEN_API_KEY,
  baseURL: "https://westertoken-22231.app.workbuddy.host/api/v1",
});

const resp = await client.chat.completions.create({
  model: "deepseek",
  messages: [{ role: "user", content: "用一句话介绍西部词元" }],
});
console.log(resp.choices[0].message.content);

流式（Python）

stream = client.chat.completions.create(
    model="deepseek",
    messages=[{"role": "user", "content": "写一首关于戈壁算力城的短诗"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

13备案与合规信息

平台接入的第三方大模型，其算法备案与生成式人工智能服务登记由模型厂商依法履行。 为便于集成方核验，模型列表接口在每条模型记录上返回 filing_no 字段 （算法备案 / 生成式 AI 服务登记号，未核验到时为空串）。

完整模型清单与公示口径见 《备案信息公示》； 渠道合作方的权责边界见 《渠道合作规则》； 数据处理规则见 《隐私权政策》。