# Clavue API

更新日期：2026-11-15

这是 [https://api.clavue.com](https://api.clavue.com) 的公开接入说明，面向人读，也面向编码代理（Claude Code、Clavue Code、Codex、WorkBuddy 等）直接读取。

- 在线阅读：<https://api.clavue.com/docs/>
- 下载本文件：<https://api.clavue.com/docs/clavue-api.md>
- 供代理发现的索引：<https://api.clavue.com/docs/llms.txt>
- 账号与密钥：<https://www.clavue.com/developers>

机器可读的真实来源是 `GET /v1/models`。本文的模型表由它生成，两者不一致时以 `/v1/models` 为准。

---

## 1. 接入

Base URL：

```text
https://api.clavue.com/v1
```

认证，二选一：

```http
Authorization: Bearer $CLAVUE_API_KEY
```

或带上登录会话 Cookie。会员密钥以 `cv_live_` 开头，企业密钥以 `cv_ent_` 开头。

**浏览器 / Web 应用可直接跨域调用。** 所有 `/v1/*` 端点都返回 CORS 头，`OPTIONS` 预检回 204 并回显请求的 `Origin`。用 Bearer 头鉴权即可，不依赖 Cookie。

```bash
export CLAVUE_API_KEY="cv_live_..."
export CLAVUE_BASE_URL="https://api.clavue.com/v1"
```

服务根路径：

| 用途 | 地址 | 说明 |
|---|---|---|
| 服务说明 | `GET /` | 返回 `service`、`v1`、`docs` |
| 端点一览 | `GET /v1` | 返回全部端点路径 |
| 模型列表 | `GET /v1/models` | 只含对外公开的产品名 |
| 机器注册表 | `GET /v1/model-registry` | `context` / `maxOutput` |
| 账户额度 | `GET /v1/quota` | 需密钥 |

```bash
curl -sS https://api.clavue.com/v1/models \
  -H "Authorization: Bearer $CLAVUE_API_KEY"
```

`GET /v1/models` 只返回官方产品名。模型名不能串到别的路径：图像模型走图像端点，语音模型走语音端点。

---

## 2. 官方模型

下表与 `GET /v1/models` 一致。`上下文` = `context_length`，`最大输出` = `max_output_tokens`，`单次输入上限` = `execution_max_input_tokens`。

| 模型 | 名称 | 池 | 上下文 | 最大输出 | 单次输入上限 | 用途 |
|---|---|---|---|---|---|---|
| `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/*` 端点 |

对话模型（前 7 个）能力为 `chat` + `tools`；`clavue-ocr` 额外有 `vision`、`ocr`；`clavue-img` 有 `image_generation`、`image_edit`；`clavue-music` 有 `audio_music`；`clavue-tts` 有 `audio_speech`。

`prompt + max_tokens` 不得超过该模型的 `上下文`，单次 `max_tokens` 不得超过 `最大输出`。

### 不在 `/v1/models` 里、但有独立端点的能力

这些独立能力走对应端点；`clavue-video` 也已列入上方官方模型表：

| 能力 | 端点 | 说明 |
|---|---|---|
| 判定 | `POST /v1/systemone`、`POST /v1/judge` | 结构化问答，`model` 填 `clavue-jev` |
| 翻译 | `POST /v1/translate` | 访客可用，IP 限流 |
| 翻译（走对话面） | `POST /v1/chat/completions` + `model=clavue-trans` | 支持带图，见第 7 节 |
| 向量 | `POST /v1/embeddings` | `clavue-emb`，1024 维 |
| 公开 OCR | `POST /v1/public/ocr` | 无需密钥 |
| 公开检索 | `POST /v1/public/search` | 无需密钥 |
| 视频生成 | `POST /v1/videos/generations` | `model` 填 `clavue-video`，异步任务，见第 5 节 |

---

## 3. 对话（OpenAI 兼容）

`POST /v1/chat/completions`。质量、速度、规划、审阅、检索都走这一条，只换 `model`。

```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": "system", "content": "你是一个严谨的编码助手。"},
      {"role": "user", "content": "用三句话说明这笔重复扣款该怎么处理。"}
    ],
    "max_tokens": 512,
    "temperature": 0.2
  }'
```

流式：加 `"stream": true`，响应为 `text/event-stream`，以 `data: [DONE]` 结束。

工具调用：对话模型都接受 OpenAI 的 `tools` / `tool_choice`，返回 `tool_calls`。

```json
{
  "model": "clavue-2.1",
  "messages": [{"role": "user", "content": "北京现在几度？"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "查询城市天气",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}
```

超时建议：短对话 60 秒，长文或大上下文 180 秒。

---

## 4. 接入编码代理

同一个模型面提供两种协议，`model` 都填上表的对话模型。

| 代理 | 协议 | 端点 |
|---|---|---|
| Claude Code | Anthropic Messages | `POST /v1/messages` |
| Codex / WorkBuddy / OpenAI SDK | OpenAI Chat Completions | `POST /v1/chat/completions` |

**当前请只使用上面两条。** `POST /v1/responses` 不可用（返回 404），已于 2026-11-12 从 `GET /v1` 端点表移除。需要 Responses 语义的客户端请改走 `POST /v1/chat/completions`，其请求/响应内容等价。

### 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": "解释这个报错：KeyError: 0"}]
  }'
```

`/v1/messages` 同时接受 `x-api-key` 与 `Authorization: Bearer`。流式用 `"stream": true`。

### OpenAI SDK / Codex / WorkBuddy

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.clavue.com/v1",
    api_key=os.environ["CLAVUE_API_KEY"],
)

r = client.chat.completions.create(
    model="clavue-2.1",
    messages=[{"role": "user", "content": "写一个 Python 快排"}],
)
print(r.choices[0].message.content)
```

```bash
export OPENAI_BASE_URL="https://api.clavue.com/v1"
export OPENAI_API_KEY="$CLAVUE_API_KEY"
```

把这份文档直接交给代理时，建议让它先读 `GET /v1/models` 确认产品名，再按上面的协议接入。

---

## 5. 图像与视频

### 文生图 `clavue-img`

`POST /v1/images/generations`。默认 WebP。

- `output_format`：`webp`、`jpeg`、`jpg`、`png`
- `aspect_ratio`：`1:1`、`9:16`、`16:9`
- 或用 `size`：`1024x1024`、`768x1344`、`1344x768`

```bash
curl -sS -m 120 https://api.clavue.com/v1/images/generations \
  -H "Authorization: Bearer $CLAVUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "clavue-img",
    "prompt": "清晨窗边，暖光，胶片感",
    "aspect_ratio": "1:1",
    "output_format": "webp"
  }'
```

响应图像在 `b64_json`，按 `output_format` 解码。客户端超时给到 120 秒。

### 改图 `clavue-img`

`POST /v1/images/edits`。单张约 75 秒，超时给到 300 秒。

**正文是 JSON，不是 `multipart/form-data`**（实测发 multipart 会返回 400 `Invalid JSON body`）。图片以 data URL 放进 `image`：

```bash
B64=$(base64 -w0 in.png)
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\"}"
```

响应同样是 `b64_json`。

### 视频生成 `clavue-video`

`POST /v1/videos/generations`。**异步任务**：提交后立刻拿到任务 ID，再按 ID 轮询，完成后再下载文件。它不是同步接口，不要按一次请求等结果的方式写。

请求里统一用 `clavue-video`。网关把它当作视频面产品名，`target_model` 指向引擎 id `minimax-h3`（与 `clavue-img`、`clavue-tts` 同一套产品名约定）。旧名 `minimax-h3` 仍可路由，但那是内部引擎名，不要写进新代码。

注意：响应体里的 `model` 字段回显的是引擎 id `minimax-h3`，不是 `clavue-video`——适配层写死了这个名字。判断请求是否发对，看请求体而不是响应体。

> **入口现状（2026-11-12 实测，已打通）。** 公网 `https://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；任务完成后可下载 MP4。实测 864×480、124 帧、H.264/AAC，生成约 327 秒。图片在同一 ComfyUI worker 上传并参与工作流；兼容 `image` 作为首帧别名。
>
> 下载未完成的任务返回 **409** `video_not_ready`（不是 404），按 `status` 继续轮询即可。

| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `model` | string | 必填 | 填 `clavue-video` |
| `prompt` | string | 必填 | 画面描述。为空返回 400 `prompt is required` |
| `mode` | string | `t2v` | `t2v` 文生视频；`i2v` 图生视频，必须提供 `first_frame`。不支持 `r2v` |
| `first_frame` | string | 无 | I2V 首帧。裸 Base64、`data:image/...;base64,...` 或公网 HTTP(S) URL |
| `last_frame` | string | 无 | 可选结束帧，输入格式同首帧；需与 `mode=i2v` 一起使用 |
| `image` | string | 无 | `first_frame` 的兼容别名；两者同时传时内容必须一致 |
| `width` | int | 864 | 视频宽，必须是 32 的倍数 |
| `height` | int | 480 | 视频高，必须是 32 的倍数 |
| `length` | int | 124 | 帧数，必须满足 `17n+5`，例如 124、192 |
| `steps` | int | 4 | 采样步数，生产适配器固定使用 Turbo |
| `seed` | int | 随机 | 不传则每次随机；响应回显实际种子 |

图片支持 PNG、JPEG、WebP、GIF，单张默认最大 10 MiB。服务端会自动把 inline Base64 图片按生成画布等比缩小并重编码，目标单图不超过约 1.5 MB；响应会返回 `image_preprocessed` / `image_original_bytes` / `image_submitted_bytes` 便于确认。`images`、`reference_images` 不属于这个接口，请改用 `first_frame` / `last_frame`。公网 HTTP(S) 图片 URL 暂不预压缩，由适配器下载校验。

#### 1. 提交任务

```bash
curl -sS -m 120 https://api.clavue.com/v1/videos/generations \
  -H "Authorization: Bearer $CLAVUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "clavue-video",
    "prompt": "清晨窗边，暖光，镜头缓慢推近",
    "width": 864,
    "height": 480,
    "length": 124,
    "steps": 4
  }'
```

返回 `queued`：

```json
{
  "id": "video_53a051ec01c8424bb1e29a517e36de41",
  "object": "video",
  "status": "queued",
  "model": "minimax-h3",
  "created_at": 1793887464
}
```

#### 2. 图生视频（首帧或首尾帧）

下面把本地 PNG 转成 Base64 Data URL，使用标准 JSON 请求体，不是 `multipart/form-data`。图生提示词只描述从首帧开始的变化，不要另起一个无关场景。

```bash
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,
    "steps": 4
}))
PY
curl -sS -m 120 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
```

如果需要约束结束画面，在同一请求增加 `"last_frame": "data:image/png;base64,..."`。提交响应带 `"mode":"i2v"` 及实际 `seed`、`length`、画布和 `steps`。I2V 缺首帧、图片格式错误或图片过大时返回 400/413；进入任务后若图片下载、上传或执行失败，`status=failed`，原因在 `error`，不会退化成文生视频。

#### 3. 轮询状态

公网入口已支持状态查询。客户端只需要 `api.clavue.com`，无需连接内网 NodePort：

```bash
curl -sS "https://api.clavue.com/v1/videos/generations/$VIDEO_ID" \
  -H "Authorization: Bearer $CLAVUE_API_KEY"
```

`status` 依次为：

| 状态 | 含义 | 处理 |
|---|---|---|
| `queued` | 已入队，等 worker | 每 3–10 秒轮询一次 |
| `in_progress` | 正在生成，`progress` 为 0 | 继续轮询，单条通常 100–250 秒 |
| `completed` | 完成，`progress` 为 100，带 `url` | 下载文件 |
| `failed` | 失败，看 `error` | 读 `error` 判断是重试还是改 prompt |

完成时响应形如：

```json
{
  "id": "video_53a051ec01c8424bb1e29a517e36de41",
  "status": "completed",
  "progress": 100,
  "mode": "t2v",
  "model": "minimax-h3",
  "prompt": "清晨窗边，暖光，镜头缓慢推近",
  "width": 864,
  "height": 480,
  "length": 124,
  "steps": 4,
  "seed": 1204053454,
  "elapsed": 212.4,
  "pod": "10.244.29.164:8188",
  "url": "/v1/videos/video_53a051ec01c8424bb1e29a517e36de41/content"
}
```

`elapsed` 是服务端实际耗时（秒），`seed` 回传的是这次真正用的种子——记下它就能复现。

#### 4. 下载视频

```bash
curl -sS -m 120 -L \
  "https://api.clavue.com/v1/videos/$VIDEO_ID/content" \
  -H "Authorization: Bearer $CLAVUE_API_KEY" \
  -o out.mp4
```

响应是 **MP4 字节流**（`video/mp4`），不是 JSON。未完成时公网入口返回 409 `video_not_ready`，应继续轮询而不是把错误体保存成视频。

#### 5. 错误与超时

| 情况 | 表现 | 处理 |
|---|---|---|
| `prompt` 为空 | 400 `prompt is required` | 补上描述 |
| I2V 缺首帧或参数不合规 | 400，错误体说明具体字段 | 补 `first_frame`，或检查格式、尺寸和帧数 |
| 图片或请求体过大 | 400 / 413 | 压缩图片，单张不超过 10 MiB |
| 所有 worker 忙 | 503 `all H3 workers busy` | 退避重试，不要并发堆积 |
| 任务超时 | `status` 变 `failed`，`error` 含 `timeout` | 减少 `length` 或 `steps` 后重提 |
| 生成失败 | `failed`，`error` 为 ComfyUI 报错 | 读 `error`；多为工作流参数问题 |
| 查询不存在的 ID | 404 | 检查 `id` 拼写 |

服务端单任务超时是 **1200 秒**。客户端轮询建议：每 5 秒一次，最长等 25 分钟；超过就放弃并且不要继续轮询。

任务状态保存在 adapter 进程内存里，**重启即丢失**。长时间排队或 adapter 重启后，旧 ID 会查不到，需要重新提交。

---

## 6. 语音

三条都是 `POST /v1/audio/speech`，用 `model` 区分。响应体是音频字节，用 `-o` 保存。

### 播报 `clavue-tts`

`voice` 推荐 `Uncle_Fu`、`Vivian`、`Serena`；其他名字（如 `alloy`）不报错，会回落到默认音色。默认播音腔。

**服务端超时 600 秒；客户端超时必须给到 300 秒以上。** 中文长句单条合成常需 60–200 秒（2 字短句也要 50–130 秒）。按 120 秒掐断会把本来成功的请求误判成失败，还会在网关侧留下占用连接，拖慢后续请求。

```bash
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-tts",
    "input": "今晚八点，市中心气温降到十二度。",
    "voice": "Vivian"
  }' \
  -o speech.wav
```

### 音乐 `clavue-music`

歌词放 `input`，风格（曲风 / 情绪 / 配器）放 `instructions`，时长用秒写在 `audio_duration`（也接受 `duration`）。不写默认 30 秒；服务端把时长钳制在 **10–110 秒**，超出按边界处理。

**`voice` 对音乐没有语义，不要传**（早期文档写「`audio_duration` 与 `voice` 写同一个数」，那是误记：`voice` 是语音合成字段，音乐链路会忽略它）。

响应体默认是 **WAV**（16-bit 32kHz 立体声），与 `response_format` 无关；`response_format: mp3` 并不保证产出 MP3，实测既可能回 WAV，也可能因该参数触发后端 503。**建议不要传 `response_format`，按扩展名 `.wav` 落盘。**

超时给到 1200 秒。实测节奏：10 秒的曲子约需 60–130 秒，30 秒的曲子约需 130–200 秒；池子繁忙时更久。客户端超时必须 ≥ 300 秒，建议 600 秒。

```bash
curl -sS -m 1200 https://api.clavue.com/v1/audio/speech \
  -H "Authorization: Bearer $CLAVUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "clavue-music",
    "input": "[Verse]\n夜车穿过无人的站台\n[Chorus]\n我把今天折进外套口袋",
    "instructions": "lo-fi, slow, rain",
    "audio_duration": 110
  }' \
  -o song.wav
```

生成前可看 `GET /v1/music3/capacity` 判断忙闲。满长度 260 秒时歌词控制在 1500 字以内。

### 转写 `POST /v1/audio/transcriptions`

上传音频文件（`multipart/form-data`），返回文字。

字段：`file`（音频，必填）、`model`（可选，默认 `faster-whisper-medium`，服务端会在 `faster-whisper-medium` → `funasr` → `sensevoice` 间自动回退）、`language`（可选）、`response_format`（`json`/`text`/`srt`/`vtt`，默认 `json`）。

```bash
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"}
```

---

## 7. 识图与翻译

### 识图 `clavue-ocr`

`POST /v1/chat/completions`，图用 data URI 或公网 URL。超时 60 秒。

```bash
curl -sS https://api.clavue.com/v1/chat/completions \
  -H "Authorization: Bearer $CLAVUE_API_KEY" \
  -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,..."}}
      ]
    }]
  }'
```

免密钥入口：`POST /v1/public/ocr`，正文与 `/v1/chat/completions` 相同，`model` 固定为 `clavue-ocr`。

**必须用 `messages` 结构传图**，与对话接口一致；直接传 `{"image": ...}` 或 `{"url": ...}` 会返回 500 `field messages is required`。

```json
{
  "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`，`model` 固定 `clavue-trans`。正文在 `messages`，语言与质检在 `translation_options`。不要开 `stream`：响应 `content` 是 JSON 字符串，里面有 `translated_text`。

```bash
curl -sS https://api.clavue.com/v1/chat/completions \
  -H "Authorization: Bearer $CLAVUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "clavue-trans",
    "temperature": 0,
    "stream": false,
    "translation_options": {
      "source_lang": "zh",
      "target_lang": "en",
      "jev_check": false
    },
    "messages": [{"role": "user", "content": "你好，世界"}]
  }'
```

常用语言短码：`zh`、`zh-tw`、`en`、`ja`、`ko`、`fr`、`de`、`es`。带图时 `messages` 写法与识图相同。

免密钥入口：`POST /v1/translate`（访客，IP 限流）。

---

## 8. 判定（结构化问答）

`POST /v1/systemone`、`POST /v1/judge`，`model` 填 `clavue-jev`。它回答已列好的问题，不写开放式长文。

**`questions` 必须是对象（dict），键是问题 id，不是数组。**传数组会直接 422 `model, state, and questions are required.`——这个报错有误导性，字段其实都传了。

```json
{
  "model": "clavue-jev",
  "state": "今天天气不错，适合出门",
  "questions": {
    "q1": { "type": "noul", "instructions": "这句话在说天气吗" },
    "q2": { "type": "choice", "instructions": "意图", "criteria": { "refund": "退款", "other": "其他" } },
    "q3": { "type": "score", "instructions": "满意度", "criteria": ["差", "一般", "好", "很好"] }
  }
}
```

问题类型：

| type | 必填 | 答案 |
|---|---|---|
| `noul` | `instructions` | `noul` 为 0 到 1，表示「是」的概率 |
| `choice` | `instructions`、`criteria` 对象 | `choice` 必须是 `criteria` 的键 |
| `score` | `instructions`、`criteria` 数组 | `score` 是等级下标（从 0 起，2 到 10 档） |

`noul` 的概率本身就是把握，没有单独的 `confidence`；`choice` 与 `score` 带 `confidence`（0 到 1）。一次最多 64 问，`state` 最长约 24000 字（实测 26000 字仍可）。服务端等待默认 12 秒，客户端超时给到 30 秒。**但耗时约 1.1 秒 / 问且串行累加**（实测 1 问 1.2 秒、8 问 8.9 秒、16 问 22.5 秒），超过约 40 问会先撞 60 秒网关超时、返回 504。建议单次 ≤ 32 问，更多分批并发。账户每分钟约 120 次。

```bash
curl -sS https://api.clavue.com/v1/systemone \
  -H "Authorization: Bearer $CLAVUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "clavue-jev",
    "state": "客户说：扣款重复了，请尽快处理。",
    "questions": {
      "is_urgent": {
        "type": "noul",
        "instructions": "这条消息是否表达了紧急性？"
      },
      "owner": {
        "type": "choice",
        "instructions": "这条消息应先由谁处理？",
        "criteria": {"billing": "账单或重复扣款", "support": "普通咨询"}
      },
      "severity": {
        "type": "score",
        "instructions": "严重程度",
        "criteria": ["低", "中", "高"]
      }
    }
  }'
```

响应：

```json
{
  "model": "clavue-jev",
  "answers": {
    "is_urgent": {"type": "noul", "noul": 0.86},
    "owner": {"type": "choice", "choice": "billing", "confidence": 0.74},
    "severity": {"type": "score", "score": 1, "confidence": 0.66,
                 "legend": {"0": "低", "1": "中", "2": "高"}}
  }
}
```

超过 64 问时，多出来的 id 在 `dropped_question_ids`。错误体是扁平 `detail` + `code`。

`POST /v1/judge` 也接受简表：

```json
{"model": "clavue-jev", "question": "是否先转给账单组？",
 "context": "客户说：扣款重复了，请尽快处理。", "choices": ["是", "否"]}
```

简表响应含 `choice` 与 `probabilities`。选项要用互不相同的字符串。

`GET /v1/systemone` 返回契约说明，不消耗额度。

---

## 9. 向量与检索

### 向量 `clavue-emb`

`POST /v1/embeddings`。1024 维，单条最多约 8192 token，一批最多 256 条。

```bash
curl -sS https://api.clavue.com/v1/embeddings \
  -H "Authorization: Bearer $CLAVUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "clavue-emb", "input": "把这段话做成检索向量"}'
```

`input` 也可以是字符串数组。`GET /v1/embeddings/capabilities` 返回维度与批量上限。

### 检索

对话模型 `clavue-2.1-search` 带来源。免密钥入口：

```bash
curl -sS https://api.clavue.com/v1/public/search \
  -H "Content-Type: application/json" \
  -d '{"query": "Clavue API 的判定接口怎么调用？"}'
```

`query` 必填，响应是对话补全 JSON。

### MCP

`GET /v1/mcp`（列工具）、`POST /v1/mcp/tools/call`（调用工具），需要密钥。

列工具只接受 `GET`；`POST /v1/mcp` 返回 **405**，不要照抄成 POST。

---

## 10. 额度与错误

对话、图像、语音、向量使用会员额度。`GET /v1/quota` 带同一把密钥查看。

判定面在响应头里返回额度：`x-clavue-quota-surface`、`x-clavue-quota-tier`、`x-clavue-quota-limit`、`x-clavue-quota-used`、`x-clavue-quota-remaining`。

| HTTP | 含义 | 处理 |
|---|---|---|
| 400 | 请求体不是合法 JSON | 检查序列化 |
| 401 | 密钥无效或缺失 | 到账号页重新创建 |
| 403 | 账号不可调用该面 | 查看订阅 |
| 404 | 路径不存在 | 对照 `GET /v1` |
| 413 | 请求体过大 | 压缩或拆分 |
| 422 | 缺字段或类型不对 | 看 `detail` |
| 429 | 频率/并发/当日额度超限 | 退避重试，指数增长 |
| 502 | 上游未按契约返回 | 可重试 |
| 503 | 上游暂时不可用 | 退避重试 |

视频面的 `503` 还表示所有 H3 worker 都在忙（错误体 `all H3 workers busy`），此时应退避而不是并发重投。

错误体形如：

```json
{"ok": false, "error": {"message": "...", "type": "...", "code": "..."}}
```

判定接口的错误体是 `{"detail": "...", "code": "..."}`。

重试建议：`429`、`502`、`503` 可重试；`400`、`401`、`403`、`404`、`422` 不要重试。

---

## 11. 最小校验脚本

```bash
#!/usr/bin/env bash
set -euo pipefail

: "${CLAVUE_API_KEY:?请先 export CLAVUE_API_KEY}"

echo "== models =="
curl -sS https://api.clavue.com/v1/models \
  -H "Authorization: Bearer $CLAVUE_API_KEY" \
  | python3 -c 'import json,sys; d=json.load(sys.stdin); print("\n".join(m["id"] for m in d["data"]))'

echo "== chat =="
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}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["choices"][0]["message"]["content"])'
```

---

## 12. 变更记录

| 日期 | 变更 |
|---|---|
| 2026-11-16 | inline Base64 图片服务端自动预压缩：按画布等比缩放，目标单图 ≤ 1.5 MB；响应返回压缩元数据。4.5 MB PNG 实测 6 秒内提交成功 |
| 2026-11-15 | 图生视频（I2V）上线：公网支持 `mode`、`first_frame` / `last_frame`、`image` 别名、图片校验与 JSON 示例；完成提交、生成及 MP4 下载实测。统一公网提交、轮询、下载路径 |
| 2026-11-14 | 公网视频三条路由打通；更新图像编辑、CORS、语音、判定和 MCP 的接口契约 |
| 2026-11-06 | 补视频生成（第 5 节）：提交任务、按 ID 轮询、下载 MP4、错误与超时；模型名统一为 `clavue-video`（网关已注册别名，旧名 `minimax-h3` 仅作引擎回显）；注明公网路由尚未开放 |
| 2026-11-04 | 模型表改为由 `GET /v1/models` 生成；补 Claude Code / Codex / WorkBuddy 接入；补判定、向量、MCP、错误码 |
| 2026-10-23 | 初版公开说明 |
