ClavueClavue API

Clavue API 文档

更新日期:2026-11-15。面向人读,也面向编码代理(Claude Code、Clavue Code、Codex、WorkBuddy)。

下载完整文档(Markdown) 代理速查索引(llms.txt) 模型清单 JSON 端点一览 JSON OpenAPI 3.1 JSON 交互式 API Explorer

机器可读的真实来源是 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。

官方模型

模型名称池上下文最大输出单次输入上限用途
autoAutofast100000012800056000默认入口,短回合与日常编码
clavueClavuepremium100000012800056000会员主对话,代理/工具/IDE
clavue-2.1Clavue 2.1premium1000000128000200000旗舰,长编码循环与难题
clavue-2.1-fastClavue 2.1 Fastfast100000012800012000高吞吐,聊天/探测/批量改写
clavue-2.1-proClavue 2.1 Propremium10000001280001000000长程规划与多代理
clavue-2.1-revClavue 2.1 Revpremium10000001280001000000审阅 diff / PR / 验证
clavue-2.1-searchClavue 2.1 Searchpremium1310723276832000联网检索,带来源
clavue-imgClavue Imgpremium32768409632000文生图 / 改图
clavue-ocrClavue OCRfast16000409616000文档与扫描件识图取字
clavue-musicClavue Musicpremium500010245000歌曲生成
clavue-ttsClavue TTSfast3276840964000播报语音,仅语音端点
clavue-videoClavue Videopremium———文生视频 / 图生视频,仅 /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 CodeAnthropic MessagesPOST /v1/messages
Codex / WorkBuddy / OpenAI SDKOpenAI Chat CompletionsPOST /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
modet2vt2v 文生视频;i2v 图生视频
first_frame / last_frame无 / 无I2V 首帧必填,尾帧可选;image 是首帧别名
width / height864 / 480分辨率,必须是 32 的倍数
length124帧数,满足 17n+5(如 124、192)
steps4采样步数
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 区分,响应体是音频字节。

转写: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/judgemodel 填 clavue-jev;questions 必须是对象(问题 id → 规格),传数组会 422
向量POST /v1/embeddingsclavue-emb,1024 维,一批最多 256 条
公开检索POST /v1/public/search免密钥
MCPGET /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 不要重试。