快速开始

pip install openai

from openai import OpenAI

client = OpenAI(
    api_key="sk-relay-你的密钥",
    base_url="https://你的域名/v1",
)

resp = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[
        {"role": "system", "content": "你是一个助手"},
        {"role": "user", "content": "用一句话介绍你自己"},
    ],
    max_tokens=500,
)
print(resp.choices[0].message.content)
print("本次消费:", resp.model_extra.get("relay_usage"))

const OpenAI = require('openai');

const client = new OpenAI({
  apiKey: 'sk-relay-你的密钥',
  baseURL: 'https://你的域名/v1',
});

const resp = await client.chat.completions.create({
  model: 'gpt-5.6-terra',
  messages: [{ role: 'user', content: '你好' }],
});
console.log(resp.choices[0].message.content);

curl -X POST https://你的域名/v1/chat/completions \
  -H "Authorization: Bearer sk-relay-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [{"role": "user", "content": "你好"}]
  }'

鉴权

有两种传法，任选其一：

• Authorization: Bearer sk-relay-xxx（OpenAI 标准，推荐）
• Authorization: sk-relay-xxx 或 X-API-Key: sk-relay-xxx

对话补全

请求参数

响应中的计费信息

响应体额外带一个 relay_usage 字段，让你能实时看到本次调用花了多少钱：

{
  "id": "chatcmpl-xxx",
  "model": "gpt-5.6-terra",
  "choices": [{ "message": { "role": "assistant", "content": "你好" }, "finish_reason": "stop" }],
  "usage": { "prompt_tokens": 8, "completion_tokens": 2, "total_tokens": 10 },

  // 平台追加字段
  "relay_usage": {
    "request_id": "req_a1b2c3",
    "sale": "0.00000100",   // 从你余额扣除的金额（= 你实际付的钱）
    "unit": "per_1m_token"
  }
}

模型列表

返回当前所有可调用模型及其售价，格式与 OpenAI 一致，额外携带计费信息：

{
  "object": "list",
  "data": [{
    "id": "gpt-5.6-terra",
    "object": "model",
    "owned_by": "tugou-ai",
    "relay": {
      "billing_unit": "per_1m_token",
      "sale_price": "0.00000840"
    }
  }]
}

异步任务（视频 / 图片生成）

视频、音乐、数字人等生成任务耗时较长，走异步协议：提交拿任务号 → 轮询查状态 → 取结果。

POST /v1/async/submit
{
  "model": "可灵文生视频",
  "params": {
    "prompt": "一只猫在草地上奔跑",
    "duration": 5
  }
}

// 响应
{
  "request_id": "req_xxx",
  "status": "submitted",
  "upstream_task_id": "task_abc123"
}

{
  "request_id": "req_xxx",
  "status": "success",          // submitted / running / success / failed / timeout
  "progress": 100,
  "result_url": "https://.../output.mp4",
  "reserved_amount": "3.00",    // 预占
  "settled_amount": "0.60",     // 实际结算
  "refunded": "2.40"            // 已退回
}

轮询建议

• 视频类任务建议每 5~10 秒轮询一次，不要秒级轮询
• 轮询到 success / failed / timeout 即停止
• 建议加指数退避：5s → 10s → 20s → 30s（上限 30s）

错误码

错误响应统一为 OpenAI 格式，客户端 SDK 能直接解析：

{
  "error": {
    "message": "余额不足，当前可用 ¥0.50，本次需要 ¥1.20",
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "request_id": "req_xxx"
  }
}

计费与余额

• 先充值后调用：余额不足时会拒绝请求，不会产生调用与费用
• 最低充值 ¥1，人民币现金计价，没有平台虚拟币
• 扣费时机：调用前按预估量预扣，返回后按实际用量结算并退差额
• 单次调用可低至万分之一分钱，控制台可查看每一笔明细

计费单位有三种：per_1m_token（每百万 token）、 per_call（每次）、per_second（每秒）。 具体每个模型的计费单位见 /v1/models 返回的 relay.billing_unit。

幂等与重试

网络超时后重试，最怕的是重复扣费。加一个 Idempotency-Key 头即可：

headers = {
  "Authorization": "Bearer sk-relay-xxx",
  "Idempotency-Key": "order-20240101-001",   # 你的业务唯一标识
}

# 带相同 Idempotency-Key 重试时：
#   - 不会重复调用（不会二次消耗算力额度）
#   - 不会重复扣费
#   - 直接返回首次的结果

常见问题

为什么余额明明够，却提示 402？

可动用金额 = 账户余额 − 在途占用（已提交但尚未返回的请求）。 如果有并发的长耗时请求（尤其视频生成），它们会占用一部分额度。 控制台「钱包」页会单独显示"在途占用"，等任务完成就会释放。

调用失败了会扣钱吗？

不会。余额不足（402）不会产生调用；服务异常（502/503）会退回全部预扣。 唯一会扣钱的是成功返回了结果的调用。控制台的用量明细里， 失败记录的"消费"列都是 0。

支持哪些模型？

见首页模型广场或调用 GET /v1/models。 模型名沿用原始名称，没有做别名映射 —— 你在控制台看到的名字就是调用时该用的名字。

可以开发票吗？

充值后联系客服即可。请注意余额按实际消耗扣除，未消费部分可申请退回。

模型名怎么查？

curl https://你的域名/v1/models \
  -H "Authorization: Bearer sk-relay-你的密钥"