第三方接入文档

1. 接入概览

本平台对第三方开放三套原生兼容协议，同一把控制台 API 密钥通用。先在控制台创建密钥并充值，再按下表选择 Base URL。

协议	Base URL	主要端点	认证头
OpenAI Chat / 图像 / 视频 / Responses	`/v1`	/chat/completions /images/generations /videos /responses	Authorization Bearer <令牌>
Anthropic Messages	`站点根路径` （不要带 /v1）	/v1/messages SDK 自动拼接	x-api-key 或 Bearer
Gemini generateContent	`站点根路径`	/v1beta/models/{model}:generateContent	x-goog-api-key 或 Bearer

当前站点地址：。下文示例中的 {ORIGIN} 会自动替换为该地址。

在线体验使用登录 JWT；第三方程序必须使用控制台生成的 API 密钥，JWT 不能调 /v1。

2. 认证

三种写法等价，令牌都是控制台里的 API Key：

Authorization: Bearer sk-xxxxxxxx
x-api-key: sk-xxxxxxxx
x-goog-api-key: sk-xxxxxxxx

缺少或错误的密钥返回 401，body 为 OpenAI 风格错误：

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

余额探测

GET /api/user/self：用同一把 API 密钥查询当前用户余额（第三方余额探测）。

curl {ORIGIN}/api/user/self \
  -H "Authorization: Bearer <令牌>"

{
  "id": 1,
  "email": "user@example.com",
  "nickname": "昵称",
  "role": "user",
  "balance": 4.25,
  "api_key_id": 12
}

3. 模型列表

GET /v1/models 可公开访问。以返回的 id（即 model_name）作为后续请求的 model。

curl {ORIGIN}/v1/models

完整价格与分组见模型价格。

4. OpenAI 兼容 · Chat Completions

POST /v1/chat/completions。Base URL 填 {ORIGIN}/v1。Claude / Gemini 也可走这条，平台会做协议转换。

流式：请求体设 "stream": true。成功时响应头为 Content-Type: text/event-stream，正文为 OpenAI SSE（data: {...} / data: [DONE]）。

参数	类型	必填	说明
model	string	是	模型 id，与 /v1/models 一致
messages	array	是	OpenAI messages
temperature	number	否	0–2
max_tokens	integer	否	最大输出 token
stream	boolean	否	当前建议 false；流式能力以控制台实测为准

curl

curl {ORIGIN}/v1/chat/completions \
  -H "Authorization: Bearer <您的令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "你是简洁助手"},
      {"role": "user", "content": "用一句话解释 TCP 三次握手"}
    ],
    "max_tokens": 512
  }'

Python (openai SDK)

from openai import OpenAI

client = OpenAI(
    api_key="<您的令牌>",
    base_url="{ORIGIN}/v1",
)
resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "ping"}],
)
print(resp.choices[0].message.content)

Node.js

import OpenAI from 'openai'
const client = new OpenAI({
  apiKey: '<您的令牌>',
  baseURL: '{ORIGIN}/v1',
})
const resp = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'ping' }],
})
console.log(resp.choices[0].message.content)

5. OpenAI Responses API

POST /v1/responses。GPT-5 / Codex 类客户端默认走这条。不是所有模型都支持，请以价格页为准。

curl {ORIGIN}/v1/responses \
  -H "Authorization: Bearer <您的令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "input": "用一句话解释什么是幂等",
    "reasoning": {"effort": "medium"}
  }'

6. Anthropic 原生 Messages

跑 Claude 时优先用这条，prompt cache / thinking 语义更完整。

Base URL 不要带 /v1：SDK 会自己拼 /v1/messages。

curl {ORIGIN}/v1/messages \
  -H "x-api-key: <您的令牌>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "ping"}]
  }'

import anthropic
client = anthropic.Anthropic(
    api_key="<您的令牌>",
    base_url="{ORIGIN}",
)
msg = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "ping"}],
)
print(msg.content[0].text)

anthropic-version、anthropic-beta（如 1M 上下文）会透传到上游。需要缓存时在内容块上加 cache_control。

7. Gemini 原生协议

POST /v1beta/models/{model}:generateContent。Base URL 为站点根路径。

curl "{ORIGIN}/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: <您的令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "用一句话解释量子纠缠"}]}],
    "generationConfig": {"maxOutputTokens": 512}
  }'

from google import genai
from google.genai import types
client = genai.Client(
    api_key="<您的令牌>",
    http_options=types.HttpOptions(base_url="{ORIGIN}"),
)
resp = client.models.generate_content(model="gemini-2.5-flash", contents="ping")
print(resp.text)

流式路径：:streamGenerateContent。图像 Gemini 模型返回 candidates[].content.parts[].inlineData.data（base64）。

8. 图像生成

OpenAI 格式：POST /v1/images/generations。一次只出 1 张，不要传 n。

curl {ORIGIN}/v1/images/generations \
  -H "Authorization: Bearer <您的令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只戴墨镜的柴犬，赛博朋克风格",
    "size": "1024x1024"
  }'

模型族	size / quality	说明
gpt-image-*	1024x1024 / 1536x1024 / 1024x1536；quality 仅 low/medium/high/auto	不要传 DALL·E 的 quality=standard。出图较慢，可能返回 b64_json
dall-e / 通用	1024x1024、1792x1024、1024x1792	走 /v1/images/generations
Gemini 图像	可走 generateContent 或图像接口回退	原生路径见上一节
doubao-seedream-*	1024x1024 或 2K / 4K	火山侧需带日期的官方模型 ID（如 doubao-seedream-4-0-250828）。短名会 404

9. 视频生成

规范端点是 POST /v1/videos，不要用 /v1/videos/generations（旧别名仍可用）。成功后多为异步任务：先拿 id / task_id，再查询、下载。

用途	方法 / 路径
创建任务	POST /v1/videos
查询状态	GET /v1/videos/{taskId}
下载成片	GET /v1/videos/{taskId}/content

MiniMax-H3

时长只能 4 / 8 / 12 秒。图生视频用公网 URL：input_reference.image_url。

curl {ORIGIN}/v1/videos -H "Authorization: Bearer <令牌>" -H "Content-Type: application/json" \
  -d '{"model":"MiniMax-H3","prompt":"橘猫走在雨夜街道","seconds":"8","resolution":"768P","aspect_ratio":"16:9"}'

Kling 3.0

{"model":"kling-3.0","prompt":"...","seconds":"8","metadata":{"duration":"8","aspect_ratio":"16:9","mode":"std"}}

图生：image.imageUri 为公网 URL，可选尾帧 lastFrame。

KlingO3

模型名 KlingO3。只传 seconds + resolution=1080p，不要传 aspect_ratio / mode。

Veo

{"model":"veo-3.1-fast-generate-preview","prompt":"...","seconds":"8","aspect_ratio":"16:9","generate_audio":false}

Seedance

文生/图生用无 -ref 后缀模型。参考视频用 -ref 模型，根级传 video 公网 URL。

查询与下载

curl {ORIGIN}/v1/videos/task_xxx -H "Authorization: Bearer <令牌>"
curl -L {ORIGIN}/v1/videos/task_xxx/content -H "Authorization: Bearer <令牌>" -o result.mp4

视频是异步的：创建接口返回后任务仍在跑。请轮询 status 为 completed / succeeded 后再拉 /content。缺参会 400，code 多为 missing_required_parameter。

10. 错误码与排障

{
  "error": {
    "message": "错误说明",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

HTTP	常见原因
401	未带令牌、用了 JWT、密钥无效
400	缺 model/prompt/messages；GPT Image 传了 quality=standard；视频缺 seconds 等
402	余额不足
404	路径写错（如 /v1/v1/...）；Seedream 短名在火山不存在
405	Gemini 打错方法/路径，或图像模型误走了不支持的 generateContent 再未回退
429	触发平台限流

11. 对接注意（来自在线体验踩坑）

OpenAI SDK 的 base_url 必须含 /v1；Anthropic / Gemini SDK 的 base 是站点根，不要再加 /v1。
图像接口不要传 n。GPT Image 不要用 1792x1024 和 quality=standard。
视频请用 POST /v1/videos，按模型族组报文；图片参考必须是公网 HTTP(S) URL。
调用会计入控制台「使用记录」，按模型单价和 token / 次计扣费。
可用模型以价格页和控制台为准，文档示例模型名需替换成你账号下实际 id。

打开控制台创建密钥　查看模型价格