API 总览

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

基础 URL

https://viewmax.studio

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

快速上手

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

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

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。

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

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。与其他端点不同，它在任务运行期间返回 202，错误响应只有 code 和 message（没有 error 对象）。

所有创建类端点都从与网页端相同的账户扣除积分。机器可读的契约见 OpenAPI（YAML）。

响应信封

成功响应：

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

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

{
  "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 错误列出了所有消息以及是否应重试。

在每个创建任务的 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 结束时自动退回。服务端没有超时，请自行设置截止时间。参见任务。

给 AI 智能体

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

继续阅读视频、图片、音乐或音频生成、任务、错误，或模型参考。