# Clavue API — 代理发现索引 > 本文档面向编码代理(Claude Code、Clavue Code、Codex、WorkBuddy)。人类可读完整版见下方链接。 - 完整文档(Markdown,可下载):https://api.clavue.com/docs/clavue-api.md - 在线阅读:https://api.clavue.com/docs/ - 模型清单(机器可读,权威来源):https://api.clavue.com/v1/models - 端点一览:https://api.clavue.com/v1 - 账号与密钥:https://www.clavue.com/developers ## 一分钟接入 Base URL:`https://api.clavue.com/v1` 认证:`Authorization: Bearer $CLAVUE_API_KEY`(会员密钥 `cv_live_` 开头,企业密钥 `cv_ent_` 开头) ### OpenAI 兼容(Codex / WorkBuddy / OpenAI SDK) ```bash export OPENAI_BASE_URL="https://api.clavue.com/v1" export OPENAI_API_KEY="$CLAVUE_API_KEY" ``` ```bash 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":"reply with exactly: PONG"}],"max_tokens":16}' ``` ### Anthropic Messages(Claude Code) ```bash export ANTHROPIC_BASE_URL="https://api.clavue.com" export ANTHROPIC_AUTH_TOKEN="$CLAVUE_API_KEY" export ANTHROPIC_MODEL="clavue-2.1" ``` ```bash curl -sS https://api.clavue.com/v1/messages \ -H "x-api-key: $CLAVUE_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{"model":"clavue-2.1","max_tokens":1024,"messages":[{"role":"user","content":"hi"}]}' ``` ## 公开模型(11 个) 对话:`auto`、`clavue`、`clavue-2.1`、`clavue-2.1-fast`、`clavue-2.1-pro`、`clavue-2.1-rev`、`clavue-2.1-search` 其他:`clavue-img`(图像)、`clavue-ocr`(识图取字)、`clavue-music`(音乐)、`clavue-tts`(播报语音)、`clavue-video`(文生视频 / 图生视频) 具体上下文长度、输出上限、单次输入上限以 `GET /v1/models` 为准,不要硬编码。 ## 端点速查 | 用途 | 方法与路径 | |---|---| | 模型列表 | `GET /v1/models` | | 对话 | `POST /v1/chat/completions` | | Anthropic 协议 | `POST /v1/messages` | | 文生图 | `POST /v1/images/generations` | | 改图 | `POST /v1/images/edits` | | 视频生成 | `POST /v1/videos/generations`(`model=clavue-video`,异步;查 `GET /v1/videos/generations/`,下载 `GET /v1/videos//content`) | | 语音(TTS/音乐) | `POST /v1/audio/speech` | | 转写 | `POST /v1/audio/transcriptions` | | 结构化判定 | `POST /v1/systemone`、`POST /v1/judge`(`model=clavue-jev`) | | 翻译 | `POST /v1/translate`(访客);或 `POST /v1/chat/completions` + `model=clavue-trans` | | 向量 | `POST /v1/embeddings`(`clavue-emb`,1024 维) | | 检索 | `POST /v1/public/search`(免密钥) | | 公开 OCR | `POST /v1/public/ocr`(免密钥) | | MCP | `GET /v1/mcp`(列工具,POST 会 405)、`POST /v1/mcp/tools/call` | | 额度 | `GET /v1/quota` | ## 约定 - `prompt + max_tokens` 不超过该模型的上下文;`max_tokens` 不超过最大输出。 - 流式:`"stream": true`,以 `data: [DONE]` 结束。 - 可重试:`429`、`502`、`503`。不要重试:`400`、`401`、`403`、`404`、`422`。 - 超时建议:短对话 60s,长文 180s,图像 120–300s,音乐 1200s,视频轮询总时长 25min。 - 模型名不要串路径:图像模型走图像端点,语音模型走语音端点,视频走 `/v1/videos/*`。 - 视频是异步的:先提交拿 `id`,再轮询到 `completed`,最后下载 `content`。别在一次请求里等结果。 - 视频任务的 `status` 取值:`queued` → `in_progress` → `completed` / `failed`。查询不存在的 ID 返回 404。 - 视频用 `model=clavue-video`;响应体 `model` 回显引擎名 `minimax-h3`,属正常现象。 - 视频三条路由都已开在公网 `api.clavue.com`:提交 `POST /v1/videos/generations`、轮询 `GET /v1/videos/generations/`、下载 `GET /v1/videos//content`。**客户端不需要连内网 NodePort。** - 视频支持 `mode=t2v`(默认)与 `mode=i2v`。I2V 必须传 `first_frame`,可选 `last_frame`;`image` 是首帧别名。图片接受 PNG/JPEG/WebP/GIF 的裸 Base64、Data URL 或公网 URL,单张默认最大 10 MiB;宽高按 32 对齐,`length` 满足 `17n+5`。 - 2026-11-15 I2V 已在公网上线并完成实片验收:HTTP 200 提交,生成并下载 864×480、124 帧 MP4。 - 视频公网 JSON 图生示例见 `clavue-api.md` 的视频章节。下载未完成的任务返回 409 `video_not_ready`,继续轮询即可。