# API 总览

ViewMax v1 媒体 API 的基础 URL、快速上手、端点、响应信封、幂等和任务生命周期。

## 基础 URL

```text
https://viewmax.studio
```

所有端点均为 HTTPS 上的 JSON 接口。请从服务端调用：v1 API 不返回 CORS 头，来自其他来源的浏览器请求会失败。需要认证的端点使用 `Authorization: Bearer sk-...`，参见[认证](https://viewmax.studio/zh/docs/api/authentication)。

## 快速上手

1. 选择模型并查看其选项。模型目录公开可读：

```bash
curl https://viewmax.studio/api/v1/models
```

2. 创建任务。携带 `Idempotency-Key`，这样重试请求不会重复扣费：

```bash
curl -X POST https://viewmax.studio/api/v1/videos \
  -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2f1c9a7e-quickstart" \
  -d '{
    "model": "viewmax-c1",
    "mode": "text-to-video",
    "prompt": "A paper boat drifting down a rainy street at dusk",
    "options": { "duration": "5s", "resolution": "768P", "aspect_ratio": "16:9" }
  }'
```

该请求消耗 10 积分（ViewMax C1 每秒 2 积分）。响应的 `data` 即任务对象，请保存 `data.id`。

3. 每 5–10 秒轮询一次，直到 `data.status` 变为 `success`、`failed` 或 `canceled`，然后下载 `data.taskUrls` 中的 URL：

```bash
curl -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  https://viewmax.studio/api/v1/tasks/TASK_ID
```

## 端点

| 方法   | 端点                                                   | 需要 key | 用途                                                      |
| ------ | ------------------------------------------------------ | -------- | --------------------------------------------------------- |
| `GET`  | `/api/v1/models`                                       | 否       | 模型目录与定价；`?type=video`（默认）、`image` 或 `music` |
| `GET`  | `/api/v1/voices`                                       | 否       | 文本转语音音色目录                                        |
| `POST` | `/api/v1/videos`                                       | 是       | 创建视频任务                                              |
| `POST` | `/api/v1/images`                                       | 是       | 创建图片任务                                              |
| `POST` | `/api/v1/music`                                        | 是       | 创建音乐任务                                              |
| `POST` | `/api/v1/speech`                                       | 是       | 文本转语音                                                |
| `POST` | `/api/v1/sound-effects`                                | 是       | 生成音效                                                  |
| `GET`  | `/api/v1/tasks/{taskId}`                               | 是       | 查询任务状态和结果 URL（所有媒体类型）                    |
| `GET`  | `/api/v1/credits`                                      | 是       | 查询账户剩余积分                                          |
| `POST` | `/api/v1/shorts-studio`                                | 是       | 进阶：用已完成的人像分割任务合成风格化 Short              |
| `GET`  | `/api/v1/shorts-studio?taskId=...` 或 `?requestId=...` | 是       | 进阶：轮询 Shorts Studio 任务                             |
| `GET`  | `/openapi.json`、`/api/openapi.yaml`                   | 否       | 上述端点的 OpenAPI 3.1 描述                               |

`GET /api/v1/credits` 返回 `{ "remainingCredits": <integer> }`，即所有 key、网页端和 MCP 共用的余额。

Shorts Studio 是进阶端点，用 ViewMax 应用中创建的人像分割任务合成 Short，请求结构见 [OpenAPI](https://viewmax.studio/openapi.json)。与其他端点不同，它在任务运行期间返回 `202`，错误响应只有 `code` 和 `message`（没有 `error` 对象）。

所有创建类端点都从与网页端相同的账户扣除积分。机器可读的契约见 [OpenAPI](https://viewmax.studio/openapi.json)（[YAML](https://viewmax.studio/api/openapi.yaml)）。

## 响应信封

成功响应：

```json
{
  "code": 0,
  "message": "ok",
  "data": {}
}
```

错误响应没有 `data`，而是带有 `error` 对象：机器可读的 `type`、说明下一步的 `hint`、文档链接 `docs`，以及请求在失败前已创建任务时的 `task_id`：

```json
{
  "code": -1,
  "message": "the generation request uses unsupported settings",
  "error": {
    "type": "invalid_request",
    "hint": "The provider rejected these settings and the credits were refunded. Read taskInfo.errorMessage from GET /api/v1/tasks/0f6c2d1e-3b7a-4c55-9d0e-6a8f2b1c4e77, adjust the request, then create a new task.",
    "docs": "https://viewmax.studio/docs/api/errors",
    "task_id": "0f6c2d1e-3b7a-4c55-9d0e-6a8f2b1c4e77"
  }
}
```

| HTTP  | `code`  | `error.type`                          | 含义                                       |
| ----- | ------- | ------------------------------------- | ------------------------------------------ |
| `200` | `0`     | —                                     | 成功                                       |
| `400` | `-1`    | `invalid_request`、`content_rejected` | 修正请求或更换内容                         |
| `401` | `-1001` | `unauthorized`                        | 缺少或无效的 API key                       |
| `402` | `-1002` | `insufficient_credits`                | 积分不足；未创建任务                       |
| `404` | `-1`    | `not_found`                           | 任务或端点不存在                           |
| `405` | —       | —                                     | 该路径不支持此方法（响应体为空）           |
| `500` | `-1`    | `internal_error`                      | 服务商或服务器故障；重试前先检查 `task_id` |
| `503` | `-1`    | `internal_error`                      | 内容安全检查暂时不可用；稍后重试           |

HTTP 状态码用于传输层处理，`error.type` 用于程序逻辑。[API 错误](https://viewmax.studio/zh/docs/api/errors)列出了所有消息以及是否应重试。

## 幂等

在每个创建任务的 `POST`（videos、images、music、speech、sound-effects）上发送 `Idempotency-Key: <你的唯一 ID>`。重复的 key 会返回首次请求创建的任务及其原始 `costCredits`，不会再次扣费。不带该请求头时，每个 `POST` 都会创建并扣费一个新任务。key 为 1–200 个可见 ASCII 字符、不含空格，作用域为你的账户。

## 任务生命周期

视频和图片任务是异步的：创建调用返回 `pending` 或 `processing`。音乐、语音和音效在创建调用中完成渲染，通常直接返回 `success`，结果 URL 已在 `taskUrls` 中；同一个 `id` 仍可通过任务端点查询。

| 状态         | 操作                          |
| ------------ | ----------------------------- |
| `pending`    | 继续轮询                      |
| `processing` | 继续轮询                      |
| `success`    | 下载 `data.taskUrls` 中的结果 |
| `failed`     | 停止；积分已退回              |
| `canceled`   | 停止；积分已退回              |

积分在创建任务时扣除，任务以 `failed` 或 `canceled` 结束时自动退回。服务端没有超时，请自行设置截止时间。参见[任务](https://viewmax.studio/zh/docs/api/tasks)。

## 给 AI 智能体

- [llms.txt](https://viewmax.studio/llms.txt) 概述产品以及何时调用哪个端点。
- 每个文档页面都可以按 Markdown 获取：请求时带上 `Accept: text/markdown`，例如 `curl -H "Accept: text/markdown" https://viewmax.studio/docs/api/tasks`。
- [OpenAPI](https://viewmax.studio/openapi.json) 是机器可读的契约。支持 MCP 的智能体也可以使用 [MCP 服务](https://viewmax.studio/zh/docs/mcp)，而不是 REST。
- 创建任务前务必读取 `GET /api/v1/models`：其中列出了每个模式的选项、默认值和价格。

继续阅读[视频](https://viewmax.studio/zh/docs/api/video-generation)、[图片](https://viewmax.studio/zh/docs/api/image-generation)、[音乐](https://viewmax.studio/zh/docs/api/music-generation)或[音频](https://viewmax.studio/zh/docs/api/audio-generation)生成、[任务](https://viewmax.studio/zh/docs/api/tasks)、[错误](https://viewmax.studio/zh/docs/api/errors)，或[模型参考](https://viewmax.studio/zh/docs/api/models)。