原生 API 调用

自己写程序接入时看这一页。快米兔 API 同时暴露四套协议，同一把令牌通用。

调用格式怎么选

同一把令牌可以走多套协议。自己写程序时，优先用 OpenAI 兼容格式：少一层转换，文本、工具、图片、视频都更稳。

类型	建议调用	怎么用
文本 / 对话	`POST /v1/chat/completions`	Body 里带 `model` 和 `messages`。要用工具，按 OpenAI 的 `tools` 来写。
文本 / Responses	`POST /v1/responses`	不建议默认走这条，请改成上面的 Chat。Codex 等客户端用 CC Switch 把协议改成 Chat Completions。
图片	`POST /v1/images/generations` `POST /v1/images/edits`	文生图走 generations，改图走 edits。模型名到模型广场复制。
视频	`POST /v1/videos`	提交后是异步任务，用返回的任务地址查询结果，不要当成同步对话。

现在如果打的是 POST /v1/messages 或 POST /v1/responses，建议都改成 POST /v1/chat/completions。这两条都会再转一层，工具参数和消息角色更容易对不上。用 CC Switch 把协议改成 OpenAI Chat 即可，令牌不用换，请求头用 Authorization: Bearer <令牌>。

Claude Code 和 Codex 不能在自己的配置里直接改成 Chat。按 CC Switch 配置教程打开本地路由，格式选 Chat Completions。

端点总览

协议	端点	认证头
OpenAI Chat	`POST /v1/chat/completions`	`Authorization: Bearer <令牌>`
OpenAI Responses	`POST /v1/responses`	`Authorization: Bearer <令牌>`
Anthropic Messages	`POST /v1/messages`	`x-api-key: <令牌>`
Gemini	`POST /v1beta/models/{model}:generateContent`	`x-goog-api-key: <令牌>`

其它常用端点：

用途	端点
模型列表	`GET /v1/models`
向量化	`POST /v1/embeddings`
图像生成	`POST /v1/images/generations`
图像编辑	`POST /v1/images/edits`
视频生成	`POST /v1/videos`
语音转文字	`POST /v1/audio/transcriptions`
文字转语音	`POST /v1/audio/speech`
重排序	`POST /v1/rerank`
内容审核	`POST /v1/moderations`
实时语音	`GET /v1/realtime`（WebSocket）

OpenAI 兼容协议

Base URL：https://api.52pay.com/v1

支持全部站内模型——包括 Claude 和 Gemini，本站会自动换成对应模型的格式。

curl

bash

curl https://api.52pay.com/v1/chat/completions \
  -H "Authorization: Bearer <您的令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {"role": "system", "content": "你是一个简洁的助手"},
      {"role": "user", "content": "用一句话解释 TCP 三次握手"}
    ],
    "max_tokens": 512,
    "stream": false
  }'

Python (openai SDK)

python

from openai import OpenAI

client = OpenAI(
    api_key="<您的令牌>",
    base_url="https://api.52pay.com/v1",
)

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "ping"}],
)
print(resp.choices[0].message.content)

Node.js

javascript

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: '<您的令牌>',
  baseURL: 'https://api.52pay.com/v1',
})

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

流式

python

stream = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "写一首五言绝句"}],
    stream=True,
    stream_options={"include_usage": True},   # 让最后一个 chunk 带 usage
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

stream_options.include_usage

加上它，流式结束时最后一个 chunk 会带 usage 字段，你能直接拿到本次的 token 消耗，不用自己数。做成本统计强烈建议开。

工具调用

python

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "北京今天天气怎么样"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "查询指定城市的天气",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }],
)
print(resp.choices[0].message.tool_calls)

Anthropic 原生协议

Base URL：https://api.52pay.com（不带 /v1，SDK 自己拼 /v1/messages）

跑 Claude 系模型时优先用这条：prompt cache、thinking、tool use 的语义最完整，不经过转换层。

curl

bash

curl https://api.52pay.com/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"}]
  }'

Python (anthropic SDK)

python

import anthropic

client = anthropic.Anthropic(
    api_key="<您的令牌>",
    base_url="https://api.52pay.com",
)

msg = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "ping"}],
)
print(msg.content[0].text)

Prompt Cache

在需要缓存的内容块上打 cache_control，本站会原样转发：

python

msg = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "<这里放很长的项目规范 / 文档 / 代码库摘要>",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "按上面的规范审查这段代码"}],
)
print(msg.usage)
# cache_creation_input_tokens / cache_read_input_tokens

命中缓存的部分按原价的十分之一计费（Claude 系是 0.1）。详见成本优化策略。

扩展思考（thinking）

python

msg = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=8000,
    thinking={"type": "enabled", "budget_tokens": 4000},
    messages=[{"role": "user", "content": "证明勾股定理"}],
)

thinking 产生的 token 按输出计价，注意控制 budget_tokens。

1M 上下文

bash

curl https://api.52pay.com/v1/messages \
  -H "x-api-key: <您的令牌>" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: context-1m-2025-08-07" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":1024,"messages":[{"role":"user","content":"..."}]}'

anthropic-beta 本站会原样转发。若返回 400/503，说明当前线路没有 1M 权限，重试或去掉该头。

Responses API

端点：POST /v1/responses

OpenAI 的新一代协议，GPT-5 系和 Grok 系支持。Codex CLI 默认走这条。

bash

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

Python：

python

from openai import OpenAI

client = OpenAI(api_key="<您的令牌>", base_url="https://api.52pay.com/v1")

resp = client.responses.create(
    model="gpt-5.5",
    input="用一句话解释什么是幂等",
    reasoning={"effort": "high"},
)
print(resp.output_text)

不是所有模型都支持

只有支持 Responses 的模型能走这条。其它模型请用 /v1/chat/completions。

Gemini 原生协议

Base URL：https://api.52pay.com（SDK 自己拼 /v1beta/...）

curl

bash

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

流式用 :streamGenerateContent：

bash

curl "https://api.52pay.com/v1beta/models/gemini-3.1-pro:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: <您的令牌>" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"写一首诗"}]}]}'

Python (google-genai SDK)

python

from google import genai
from google.genai import types

client = genai.Client(
    api_key="<您的令牌>",
    http_options=types.HttpOptions(base_url="https://api.52pay.com"),
)

resp = client.models.generate_content(
    model="gemini-3.1-pro",
    contents="ping",
)
print(resp.text)

安全策略

Gemini 默认会拦截部分内容。放宽：

json

{
  "contents": [{"parts": [{"text": "..."}]}],
  "safetySettings": [
    {"category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_NONE"},
    {"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE"},
    {"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "threshold": "BLOCK_NONE"},
    {"category": "HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "BLOCK_NONE"}
  ]
}

返回里 finishReason 为 SAFETY 就是被拦了。

图像生成

参数见模型与分组 → 图像模型。这一节只给可以直接复制的请求。

OpenAI 格式

bash

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

图生图与遮罩

POST /v1/images/edits，multipart。字段见生图参数。

bash

curl https://api.52pay.com/v1/images/edits -H "Authorization: Bearer <您的令牌>" -F "model=gpt-image-2" -F "prompt=把透明区域换成红色围巾" -F "size=1024x1024" -F "n=2" -F "image=@photo.png" -F "mask=@mask.png"

异步出图

不传 async 时，接口会一直等到图片生成完才返回。gpt-image-2、gpt-image-2.5 有时要十几分钟。客户端如果一直占着这条连接，可能在图还没好时就断开，后面就收不到。

需要长时间等待时，JSON 里加 "async": true，或加请求头 X-Kmt-Async: 1。编辑接口同样支持，表单字段 async=true 或同样的请求头。接口马上返回任务号，生成在后台继续。用同一把密钥轮询：

GET /v1/images/tasks/{id}

status 为 queued 或 in_progress 时，过几秒再查。completed 的 data 与同步出图一样，是图片数组。failed 看 error.message。扣费仍在出图成功时发生。结果保留 24 小时。同一密钥同时进行中的异步任务最多 8 个。

bash

curl https://api.52pay.com/v1/images/generations -H "Authorization: Bearer <您的令牌>" -H "Content-Type: application/json" -d '{"model":"gpt-image-2","prompt":"一只戴墨镜的柴犬","n":1,"size":"1024x1024","async":true}'

bash

curl https://api.52pay.com/v1/images/tasks/imgt_任务号 -H "Authorization: Bearer <您的令牌>"

Gemini 图像模型

bash

curl "https://api.52pay.com/v1beta/models/gemini-3-pro-image:generateContent" \
  -H "x-goog-api-key: <您的令牌>" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"一只戴墨镜的柴犬"}]}]}'

返回里图片在 candidates[].content.parts[].inlineData.data（base64）。参考图放在 contents.parts 的 inlineData 里，和提示词一起提交。这条不认 mask。

视频生成

端点 POST /v1/videos。提交后用返回的任务号轮询 GET /v1/videos/{id}，见查询进度。模型介绍和必填参数见模型与分组 → 视频模型。价格以模型广场公示为准。缺参返回 400，body 为 {"error":{"type":"invalid_request_error","code":"missing_required_parameter"}}。

查询进度

提交后不会马上返回视频，要隔几秒查一次。任务号用返回 JSON 里的 id；没有 id 就用 task_id。这两个字段有时放在 data 里面。不要调用 /v1/videos/generations。

状态字段 status 在最外层，或者在 data.status。完成：completed、succeeded、success、done。失败：failed、fail、error、canceled、cancelled，原因在 error.message。其它状态表示还在排队或生成，继续查。完成后先看 video_url 或 url（最外层和 data 里都看）。路径里同时有 /v1/videos/ 和 /content 的地址不能当播放链接，那是下载接口。没有可播放的地址时，用同一把令牌请求下面第二条，保存成文件。

bash

curl https://api.52pay.com/v1/videos/task_xxx -H "Authorization: Bearer <您的令牌>"
curl -L https://api.52pay.com/v1/videos/task_xxx/content -H "Authorization: Bearer <您的令牌>" -o result.mp4

MiniMax H3

下面是只写提示词、不带图片的请求。参数说明在模型页。

bash

curl https://api.52pay.com/v1/videos -H "Authorization: Bearer <您的令牌>" -H "Content-Type: application/json" -d '{"model":"MiniMax-H3","prompt":"一只橘猫在雨夜街道上缓慢行走，电影级光影","seconds":"8","resolution":"768P","aspect_ratio":"16:9"}'

MiniMax H3 图生

图生要在上一例上加 input_reference，值必须是公网图片地址，不能传电脑上的文件。

bash

curl https://api.52pay.com/v1/videos -H "Authorization: Bearer <您的令牌>" -H "Content-Type: application/json" -d '{"model":"MiniMax-H3","prompt":"让画面中的主体缓慢转向镜头，电影感光线","seconds":"8","resolution":"2K","aspect_ratio":"16:9","input_reference":{"image_url":"https://example.com/first-frame.jpg"}}'

可灵 O3

当前在售的可灵是 KlingO3。下面是带一张参考图的请求，其它参数在模型页。

bash

curl https://api.52pay.com/v1/videos -H "Authorization: Bearer <您的令牌>" -H "Content-Type: application/json" -d '{"model":"KlingO3","prompt":"让参考图里的猫转头","seconds":"8","resolution":"720p","referenceImages":["https://example.com/cat.jpg"]}'

Veo 3.1（未在售）

当前没有在售线路，调用会失败。字段见模型页。线路恢复之前都会失败。恢复之后可以按下面的请求调用。

bash

curl https://api.52pay.com/v1/videos -H "Authorization: Bearer <您的令牌>" -H "Content-Type: application/json" -d '{"model":"veo-3.1-fast-generate-preview","prompt":"海边日落，镜头缓慢前推","seconds":"8","aspect_ratio":"16:9","generate_audio":false}'

可灵 3.0（未在售）

当前没有在售线路，调用会失败。要可灵请用上面的 KlingO3。下面是恢复后的写法，字段说明在模型页。

bash

curl https://api.52pay.com/v1/videos -H "Authorization: Bearer <您的令牌>" -H "Content-Type: application/json" -d '{"model":"kling-3.0","prompt":"一只猫在阳光下行走","seconds":"8","metadata":{"duration":"8","aspect_ratio":"16:9","mode":"std"}}'

万相

模型名填 wan3.0。这一例同时带了参考图、参考视频和参考音频，数量限制在模型页。

bash

curl https://api.52pay.com/v1/videos -H "Authorization: Bearer <您的令牌>" -H "Content-Type: application/json" -d '{"model":"wan3.0","prompt":"让参考图里的人物转头看向镜头","seconds":"5","resolution":"720p","ratio":"16:9","referenceImages":["https://example.com/person.jpg"],"referenceVideos":["https://example.com/move.mp4"],"referenceAudios":["https://example.com/voice.mp3"]}'

Seedance 官方

官方 Seedance（2.0、2.5、-ref）的图片和音视频都放在 metadata.content 里。用 2.5 时把 model 改成 seedance-2.5。只有一张图时，role 填 first_frame（首帧）；参考视频的 role 填 reference_video。更多规则在模型页。

bash

curl https://api.52pay.com/v1/videos -H "Authorization: Bearer <您的令牌>" -H "Content-Type: application/json" -d '{"model":"seedance-2.0-mini","prompt":"参考图里的产品缓慢转向镜头","seconds":"8","aspect_ratio":"16:9","resolution":"720p","metadata":{"content":[{"type":"image_url","image_url":{"url":"https://example.com/product.jpg"},"role":"reference_image"},{"type":"video_url","video_url":{"url":"https://example.com/move.mp4"},"role":"reference_video"},{"type":"audio_url","audio_url":{"url":"https://example.com/voice.mp3"},"role":"reference_audio"}]}}'

Seedance 本地文件

本地文件用 multipart，字段名 image、video、audio。图片不要超过 12MB，音视频不要超过 80MB。参考视频的格式、帧率、时长和尺寸见参考视频要求。再大就改用公网地址。

bash

curl https://api.52pay.com/v1/videos -H "Authorization: Bearer <您的令牌>" -F "model=seedance-2.0-mini" -F "prompt=把视频里的衣服换成素材图" -F "seconds=8" -F "aspect_ratio=9:16" -F "image=@cloth.png" -F "video=@ref.mp4"

Seedance 海外

模型名里带「海外」的，以及 sd- 开头和 K1，图片、视频、音频分别放进 referenceImages、referenceVideos、referenceAudios。比例用 ratio，不要传 metadata.content。K1 的分辨率只能写 720p，时长最短 5 秒。

bash

curl https://api.52pay.com/v1/videos -H "Authorization: Bearer <您的令牌>" -H "Content-Type: application/json" -d '{"model":"Seedance 2.0 Fast 海外","prompt":"让参考图里的人物缓慢转向镜头","duration":5,"ratio":"16:9","resolution":"720p","referenceImages":["https://example.com/person.jpg"],"referenceVideos":["https://example.com/demo.mp4"],"referenceAudios":["https://example.com/voice.mp3"]}'

音频

bash

# 语音转文字
curl https://api.52pay.com/v1/audio/transcriptions \
  -H "Authorization: Bearer <您的令牌>" \
  -F file=@audio.mp3 \
  -F model=whisper-1

# 文字转语音
curl https://api.52pay.com/v1/audio/speech \
  -H "Authorization: Bearer <您的令牌>" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","input":"你好","voice":"alloy"}' \
  --output speech.mp3

具体可用的音频模型和单价以模型广场公示为准。

向量化

POST /v1/embeddings。模型用 doubao-embedding-vision-251215。令牌分组用 auto 或「豆包」。

默认 2048 维。dimensions 可传 1024。

输入	单价
文本	0.0007 元/千 token（¥0.70 / 百万 token）
图片	0.0018 元/千 token（¥1.80 / 百万 token）

返回里的 usage.prompt_tokens 是按这两个单价折算后的计费 token。原始数量在 usage.prompt_tokens_details 的 text_tokens 和 image_tokens。

文本

input 传字符串，或字符串数组。数组里每段文本各返回一条向量，一次最多 8 段。

python

resp = client.embeddings.create(
    model="doubao-embedding-vision-251215",
    input=["第一段文本", "第二段文本"],
)
print(len(resp.data[0].embedding))

bash

curl https://api.52pay.com/v1/embeddings \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{"model":"doubao-embedding-vision-251215","input":"要向量化的文本"}'

图片

图片用 type=image_url。地址用 https 链接，或 data:image/png;base64,...。一次最多 8 张。文本和图片放在同一个数组里，得到一条向量。

python

resp = client.embeddings.create(
    model="doubao-embedding-vision-251215",
    input=[
        {"type": "text", "text": "图里有什么"},
        {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}},
    ],
)
print(resp.usage.prompt_tokens_details.image_tokens)
print(len(resp.data[0].embedding))

bash

curl https://api.52pay.com/v1/embeddings \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{"model":"doubao-embedding-vision-251215","dimensions":1024,"input":[{"type":"text","text":"图里有什么"},{"type":"image_url","image_url":{"url":"https://example.com/photo.jpg"}}]}'

错误响应格式

失败时返回标准的 OpenAI 错误结构：

json

{
  "error": {
    "message": "当前分组 default 下对于模型 xxx 无可用渠道",
    "type": "new_api_error",
    "code": "channel_not_found"
  }
}

对照表见错误代码。

排查时先看响应头

每个响应都带 X-Oneapi-Request-Id。把这个 ID 报给客服，可以直接定位到那一条日志。

原生 API 调用 ​

调用格式怎么选 ​

端点总览 ​

OpenAI 兼容协议 ​

curl ​

Python (openai SDK) ​

Node.js ​

流式 ​

工具调用 ​

Anthropic 原生协议 ​

curl ​

Python (anthropic SDK) ​

Prompt Cache ​

扩展思考（thinking） ​

1M 上下文 ​

Responses API ​

Gemini 原生协议 ​

curl ​

Python (google-genai SDK) ​

安全策略 ​

图像生成 ​

OpenAI 格式 ​

图生图与遮罩 ​

异步出图 ​

Gemini 图像模型 ​

视频生成 ​

查询进度 ​

MiniMax H3 ​

MiniMax H3 图生 ​

可灵 O3 ​

Veo 3.1（未在售） ​

可灵 3.0（未在售） ​

万相 ​

Seedance 官方 ​

Seedance 本地文件 ​

Seedance 海外 ​

音频 ​

向量化 ​

文本 ​

图片 ​

错误响应格式 ​

配套阅读 ​

原生 API 调用

调用格式怎么选

端点总览

OpenAI 兼容协议

curl

Python (openai SDK)

Node.js

流式

工具调用

Anthropic 原生协议

curl

Python (anthropic SDK)

Prompt Cache

扩展思考（thinking）

1M 上下文

Responses API

Gemini 原生协议

curl

Python (google-genai SDK)

安全策略

图像生成

OpenAI 格式

图生图与遮罩

异步出图

Gemini 图像模型

视频生成

查询进度

MiniMax H3

MiniMax H3 图生

可灵 O3

Veo 3.1（未在售）

可灵 3.0（未在售）

万相

Seedance 官方

Seedance 本地文件

Seedance 海外

音频

向量化

文本

图片

错误响应格式

配套阅读