Clavue API 文档
更新日期:2026-11-15。面向人读,也面向编码代理(Claude Code、Clavue Code、Codex、WorkBuddy)。
机器可读的真实来源是 GET /v1/models。本文的模型表由它生成,两者不一致时以 /v1/models 为准。
接入
Base URL:https://api.clavue.com/v1
Authorization: Bearer $CLAVUE_API_KEY
会员密钥以 cv_live_ 开头,企业密钥以 cv_ent_ 开头。也可以带登录会话 Cookie。
浏览器 / Web 应用可直接跨域调用。 所有 /v1/* 端点都返回 CORS 头,OPTIONS 预检回 204 并回显请求的 Origin。用 Bearer 头鉴权即可,不依赖 Cookie。
官方模型
| 模型 | 名称 | 池 | 上下文 | 最大输出 | 单次输入上限 | 用途 |
|---|---|---|---|---|---|---|
auto | Auto | fast | 1000000 | 128000 | 56000 | 默认入口,短回合与日常编码 |
clavue | Clavue | premium | 1000000 | 128000 | 56000 | 会员主对话,代理/工具/IDE |
clavue-2.1 | Clavue 2.1 | premium | 1000000 | 128000 | 200000 | 旗舰,长编码循环与难题 |
clavue-2.1-fast | Clavue 2.1 Fast | fast | 1000000 | 128000 | 12000 | 高吞吐,聊天/探测/批量改写 |
clavue-2.1-pro | Clavue 2.1 Pro | premium | 1000000 | 128000 | 1000000 | 长程规划与多代理 |
clavue-2.1-rev | Clavue 2.1 Rev | premium | 1000000 | 128000 | 1000000 | 审阅 diff / PR / 验证 |
clavue-2.1-search | Clavue 2.1 Search | premium | 131072 | 32768 | 32000 | 联网检索,带来源 |
clavue-img | Clavue Img | premium | 32768 | 4096 | 32000 | 文生图 / 改图 |
clavue-ocr | Clavue OCR | fast | 16000 | 4096 | 16000 | 文档与扫描件识图取字 |
clavue-music | Clavue Music | premium | 5000 | 1024 | 5000 | 歌曲生成 |
clavue-tts | Clavue TTS | fast | 32768 | 4096 | 4000 | 播报语音,仅语音端点 |
clavue-video | Clavue Video | premium | — | — | — | 文生视频 / 图生视频,仅 /v1/videos/* 端点 |
prompt + max_tokens 不得超过该模型的上下文,单次 max_tokens 不得超过最大输出。模型名不要串路径:图像模型走图像端点,语音模型走语音端点。
对话(OpenAI 兼容)
POST /v1/chat/completions。质量、速度、规划、审阅、检索都走这一条,只换 model。
curl -sS https://api.clavue.com/v1/chat/completions \
-H "Authorization: Bearer $CLAVUE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "clavue-2.1",
"messages": [{"role": "user", "content": "用三句话说明这笔重复扣款该怎么处理。"}],
"max_tokens": 512
}'
流式加 "stream": true,以 data: [DONE] 结束。对话模型都接受 OpenAI 的 tools / tool_choice。
超时建议:短对话 60 秒,长文或大上下文 180 秒。
接入编码代理
| 代理 | 协议 | 端点 |
|---|---|---|
| Claude Code | Anthropic Messages | POST /v1/messages |
| Codex / WorkBuddy / OpenAI SDK | OpenAI Chat Completions | POST /v1/chat/completions |
Claude Code
export ANTHROPIC_BASE_URL="https://api.clavue.com"
export ANTHROPIC_AUTH_TOKEN="$CLAVUE_API_KEY"
export ANTHROPIC_MODEL="clavue-2.1"
OpenAI SDK / Codex / WorkBuddy
export OPENAI_BASE_URL="https://api.clavue.com/v1"
export OPENAI_API_KEY="$CLAVUE_API_KEY"
当前请只使用上面两条。 POST /v1/responses 不可用(返回 404 responses_not_supported),已于 2026-11-12 从 GET /v1 端点表移除。需要 Responses 语义的客户端请改走 POST /v1/chat/completions,其请求/响应内容等价。
图像
文生图 POST /v1/images/generations(默认 WebP,output_format 可取 webp/jpeg/jpg/png,aspect_ratio 可取 1:1/9:16/16:9)。图像在 b64_json。超时 120–300 秒。
改图 POST /v1/images/edits。正文是 JSON,不是 multipart/form-data(实测发 multipart 会返回 400 Invalid JSON body)。图片以 data URL 放进 image:
curl -sS -m 300 https://api.clavue.com/v1/images/edits \
-H "Authorization: Bearer $CLAVUE_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"model\":\"clavue-img\",\"prompt\":\"换成冬装,保留脸\",\"image\":\"data:image/png;base64,$B64\"}"
视频
视频生成 POST /v1/videos/generations,model 填 clavue-video(旧名 minimax-h3 仍可用,回显里也是它)。异步:提交返回 queued 与任务 id,再用 GET /v1/videos/generations/<id> 轮询,completed 后从 GET /v1/videos/<id>/content 下载 MP4。
| 参数 | 默认 | 说明 |
|---|---|---|
prompt | 必填 | 画面描述,为空返回 400 |
mode | t2v | t2v 文生视频;i2v 图生视频 |
first_frame / last_frame | 无 / 无 | I2V 首帧必填,尾帧可选;image 是首帧别名 |
width / height | 864 / 480 | 分辨率,必须是 32 的倍数 |
length | 124 | 帧数,满足 17n+5(如 124、192) |
steps | 4 | 采样步数 |
seed | 随机 | 固定可复现 |
curl -sS https://api.clavue.com/v1/videos/generations \
-H "Authorization: Bearer $CLAVUE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"clavue-video","mode":"t2v","prompt":"清晨窗边,暖光","length":124}'
图生视频传 mode=i2v 和 first_frame;图片支持 PNG / JPEG / WebP / GIF 的裸 Base64、data:image/...;base64,... 或公网 HTTP(S) URL,单张默认最大 10 MiB。inline Base64 图片会在提交前自动按生成画布等比缩放并压缩到约 1.5 MB 内,响应带压缩元数据;HTTP(S) URL 由适配器下载校验,暂不预压缩。首尾帧用同一 JSON 请求体,不是 multipart/form-data。完整示例见 可下载文档。
python3 - <<'PY' >/tmp/clavue-i2v-request.json
import base64, json
from pathlib import Path
image = base64.b64encode(Path("first.png").read_bytes()).decode()
print(json.dumps({
"model": "clavue-video", "mode": "i2v",
"prompt": "人物缓慢转向镜头,头发被微风带动",
"first_frame": "data:image/png;base64," + image,
"width": 864, "height": 480, "length": 124
}))
PY
curl -sS https://api.clavue.com/v1/videos/generations \
-H "Authorization: Bearer $CLAVUE_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @/tmp/clavue-i2v-request.json
status 依次为 queued → in_progress → completed(带 url 与 elapsed)/ failed(看 error)。单任务服务端超时 1200 秒,客户端每 5 秒轮询、最长 25 分钟。服务端不传 seed 时随机生成并回传,记下即可复现。
查询不存在的任务 ID 返回 404。所有 worker 忙时返回 503 all H3 workers busy,应退避而不是并发重投。
curl -sS "https://api.clavue.com/v1/videos/generations/$VIDEO_ID" \
-H "Authorization: Bearer $CLAVUE_API_KEY"
curl -sS -o out.mp4 "https://api.clavue.com/v1/videos/$VIDEO_ID/content" \
-H "Authorization: Bearer $CLAVUE_API_KEY"
入口现状(2026-11-12 实测,已打通)。 公网 api.clavue.com 的提交、轮询、下载三条路由都可用,客户端只需要 api.clavue.com 一个域名,不必也不应去连内网 NodePort:
| 用途 | 端点 |
|---|---|
| 提交 | POST /v1/videos/generations |
| 轮询 | GET /v1/videos/generations/<id> |
| 下载 | GET /v1/videos/<id>/content |
实测:提交 0.5s 返回 queued;864×480 的片子生成约 200–250s,但排队时间另计——池子繁忙时可能多等 5–10 分钟。2026-11-12 复测有一次从提交到 completed 约 6 分钟(含排队)。客户端轮询要按 25 分钟上限来,不要假设「几分钟内必有结果」。下载约 500KB MP4。
2026-11-15 图生视频已上线并完成实片验收:公网提交 mode=i2v 返回 HTTP 200,实测生成并下载 864×480、124 帧 H.264/AAC MP4。支持首帧 / 首尾帧及 image 首帧别名,不再返回旧的 reference_images_unsupported。
下载未完成的任务返回 409 video_not_ready(不是 404),按 status 继续轮询即可。
语音
三条都是 POST /v1/audio/speech,用 model 区分,响应体是音频字节。
clavue-tts:voice推荐Uncle_Fu、Vivian、Serena;其他值(如alloy)不会报错,会回退到默认音色。服务端超时 600 秒;客户端超时必须给到 300 秒以上。中文长句单条合成常需 60–200 秒(2 字短句也要 50–130 秒)。按 120 秒掐断会把本来成功的请求误判成失败,还会在网关侧留下占用连接,拖慢后续请求。clavue-music:歌词放input,风格(曲风 / 情绪 / 配器)放instructions,时长用秒写在audio_duration(也接受duration)。不写默认 30 秒;服务端把时长钳制在 10–110 秒,超出按边界处理。voice对音乐无意义,不要传。可选seed复现同一版。服务端超时 1200 秒,单曲通常 60–180 秒,客户端超时必须给到 300 秒以上。
curl -sS -m 600 https://api.clavue.com/v1/audio/speech \
-H "Authorization: Bearer $CLAVUE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"clavue-music","input":"[verse]\nhello world sing along","instructions":"pop, warm","audio_duration":30}' \
-o song.wav # 响应体是 WAV(16-bit 32kHz 立体声)
转写:POST /v1/audio/transcriptions,multipart/form-data。字段 file(音频,必填)、model(可选,默认 faster-whisper-medium,服务端会在 faster-whisper-medium → funasr → sensevoice 间自动回退)、language(可选)、response_format(json/text/srt/vtt)。
curl -sS https://api.clavue.com/v1/audio/transcriptions \
-H "Authorization: Bearer $CLAVUE_API_KEY" \
-F file=@speech.wav \
-F model=faster-whisper-medium
# -> {"ok":true,"text":"...","model":"faster-whisper-medium"}
识图与翻译
识图 clavue-ocr 走 POST /v1/chat/completions,图用 data URI 或公网 URL。免密钥入口 POST /v1/public/ocr,正文相同,model 固定为 clavue-ocr。
public/ocr 必须用 messages 结构传图(与对话接口一致)。直接传 {"image": ...} 或 {"url": ...} 会返回 500 field messages is required。
curl -sS https://api.clavue.com/v1/public/ocr \
-H "Content-Type: application/json" \
-d '{"model":"clavue-ocr","messages":[{"role":"user","content":[
{"type":"text","text":"把图中的字读出来"},
{"type":"image_url","image_url":{"url":"data:image/png;base64,..."}}
]}]}'
翻译 clavue-trans 走 POST /v1/chat/completions,语言与质检在 translation_options,不要开 stream(响应 content 是含 translated_text 的 JSON 字符串)。免密钥入口 POST /v1/translate。
判定、向量与检索
| 能力 | 端点 | 说明 |
|---|---|---|
| 结构化判定 | POST /v1/systemone、POST /v1/judge | model 填 clavue-jev;questions 必须是对象(问题 id → 规格),传数组会 422 |
| 向量 | POST /v1/embeddings | clavue-emb,1024 维,一批最多 256 条 |
| 公开检索 | POST /v1/public/search | 免密钥 |
| MCP | GET /v1/mcp、POST /v1/mcp/tools/call | 需要密钥;列工具用 GET,POST 会 405 |
| 额度 | GET /v1/quota | 需要密钥 |
每道问题必须带 type,取值只有三种:noul(回 0–1 概率)、choice(回 criteria 的键)、score(回 criteria 下标,2–10 档)。缺 type 或 criteria 的问题会被静默跳过,全部跳过时返回 502 The decision head returned no answers.,看起来像服务故障,其实是请求体不合规。
curl -sS https://api.clavue.com/v1/judge \
-H "Authorization: Bearer $CLAVUE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "clavue-jev",
"state": "非常满意,物流很快,质量很好,强烈推荐!",
"questions": {
"sentiment": {"type": "choice", "instructions": "整体情感倾向",
"criteria": {"positive": "整体好评", "negative": "整体差评"}},
"score": {"type": "score", "instructions": "满意度打分,0 最差 4 最好",
"criteria": ["很差", "一般", "还行", "不错", "很好"]},
"refund": {"type": "noul", "instructions": "用户是否要求退款"}
}
}'
# -> {"model":"clavue-jev","answers":{
# "sentiment":{"choice":"positive","confidence":0.9999},
# "score":{"score":4,"confidence":0.9993},
# "refund":{"noul":0.001}}}
instructions 强烈建议每条都写:它是发送给判定模型的「问题本身」。不写时退化为用 question id(如 sentiment)当问题,判定会明显变差。criteria 的键只是返回时的枚举值,不会被当成语义描述传给模型;noul 固定回 yes/no 的概率,不受 criteria 影响。
判定头对混合情绪偏保守:像「发货太慢但客服不错」这类正负交织的长句,往往被判到接近最差档。需要稳定档位时,先把 state 摘要成单一倾向再送入,或改用 choice 二分而不是 score 多档。
一次最多 64 问,但实际耗时约 1.1 秒 / 问且串行累加(实测 1 问 1.2 秒、8 问 8.9 秒、16 问 22.5 秒)。超过约 40 问会先撞上 60 秒的网关超时,返回 504 而不是结果。建议单次 ≤ 32 问;更多请分批并发提交,每批之间不要串行等待。
错误码
| HTTP | 含义 | 处理 |
|---|---|---|
| 400 | 请求体不是合法 JSON | 检查序列化 |
| 401 | 密钥无效或缺失 | 到账号页重新创建 |
| 403 | 账号不可调用该面 | 查看订阅 |
| 404 | 路径不存在 | 对照 GET /v1 |
| 413 | 请求体过大 | 压缩或拆分 |
| 422 | 缺字段或类型不对 | 看 detail |
| 429 | 频率/并发/当日额度超限 | 退避重试,指数增长 |
| 502 | 上游未按契约返回 | 可重试 |
| 503 | 上游暂时不可用 | 退避重试 |
重试建议:429、502、503 可重试;400、401、403、404、422 不要重试。
Clavue API