# 任务

轮询任意 ViewMax 生成任务、读取结果 URL，并处理失败与退款。

## 查询任务

```http
GET https://viewmax.studio/api/v1/tasks/{taskId}
Authorization: Bearer sk-your-api-key
```

使用任一创建端点返回的 `data.id`：`POST /api/v1/videos`、`images`、`music`、`speech` 或 `sound-effects`。创建响应和本端点返回相同的任务对象。

```bash
curl -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  https://viewmax.studio/api/v1/tasks/0f6c2d1e-3b7a-4c55-9d0e-6a8f2b1c4e77
```

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "0f6c2d1e-3b7a-4c55-9d0e-6a8f2b1c4e77",
    "status": "success",
    "mediaType": "video",
    "scene": "text-to-video",
    "model": "viewmax-c1/text-to-video",
    "prompt": "A paper boat drifting down a rainy street at dusk",
    "options": "{\"resolution\":\"768P\",\"duration\":5,\"aspect_ratio\":\"16:9\",\"mode\":\"text-to-video\"}",
    "taskUrls": ["https://…/video.mp4"],
    "costCredits": 10,
    "waivedCredits": 0,
    "createdAt": "2026-09-29T08:00:00.000Z",
    "updatedAt": "2026-09-29T08:01:12.000Z"
  }
}
```

示例省略了诊断字段和内部字段。

## 任务字段

| 字段                                                      | 类型         | 说明                                                                  |
| --------------------------------------------------------- | ------------ | --------------------------------------------------------------------- |
| `id`                                                      | string       | 任务 ID，轮询时使用                                                   |
| `status`                                                  | string       | `pending`、`processing`、`success`、`failed` 或 `canceled`            |
| `mediaType`                                               | string       | `video`、`image`、`music` 或 `audio`                                  |
| `scene`                                                   | string       | 模式，例如 `text-to-video` 或 `text-to-image`                         |
| `model`                                                   | string       | 实际渲染所用的模型 ID，可能与你发送的目录 ID 不同                     |
| `prompt`                                                  | string       | 提交的提示词                                                          |
| `options`                                                 | string       | 发送给模型的选项（JSON 字符串），包含自动补全的默认值和模式           |
| `taskUrls`                                                | string[]     | 结果 URL。始终为数组；结果生成前为空                                  |
| `costCredits`                                             | integer      | 扣除的积分。套餐额度覆盖时为 `0`                                      |
| `waivedCredits`                                           | integer      | 套餐额度覆盖的积分                                                    |
| `fairUseKey`                                              | string\|null | 套餐额度覆盖该任务时有值                                              |
| `createdAt`、`updatedAt`                                  | string       | UTC 的 ISO 8601 时间戳                                                |
| `taskInfo`、`taskResult`                                  | string\|null | JSON 字符串形式的诊断信息。运行中或成功时结构因模型而异；失败时见下文 |
| `userId`、`taskId`、`creditId`、`visibility`、`deletedAt` | —            | 内部字段，请勿依赖                                                    |

创建响应的 `data` 顶层同样包含 `costCredits`。

## 状态

| 状态         | 终态 | 含义                                         | 操作         |
| ------------ | ---- | -------------------------------------------- | ------------ |
| `pending`    | 否   | 已受理并扣费；等待模型确认或开始             | 继续轮询     |
| `processing` | 否   | 模型正在生成                                 | 继续轮询     |
| `success`    | 是   | 已完成。媒体任务的 `taskUrls` 至少有一个 URL | 下载结果     |
| `failed`     | 是   | 生成失败，积分已退回                         | 读取失败载荷 |
| `canceled`   | 是   | 模型取消了任务，积分已退回                   | 读取失败载荷 |

## 轮询

- 每 5–10 秒轮询一次。每次轮询未完成的任务都会实时查询模型进度，更频繁地轮询并不会加快生成。
- 到达终态（`success`、`failed` 或 `canceled`）后停止。
- 服务端没有超时。请自行设置截止时间并保存任务 ID；较慢的任务之后仍可能完成。
- 轮询时出现 `500` 属于暂时性错误，继续轮询同一个 ID 即可。
- 即使不轮询，任务也会继续推进，你可以稍后再查询。

## 积分与退款

积分在创建任务时扣除。以 `failed` 或 `canceled` 结束的任务会自动退款，包括其占用的套餐额度。失败任务无需申请退款。

如果创建请求在任务创建之后失败，错误中会包含 `error.task_id`。重试前先轮询该任务：若为 `failed`，积分已退回，可以重试；若仍为 `pending` 或 `processing`，模型可能仍会交付，此时重试会再次扣费。参见 [API 错误](https://viewmax.studio/zh/docs/api/errors)。

## 失败载荷

当 `status` 为 `failed` 或 `canceled` 时，`taskInfo` 和 `taskResult` 都是同一个 JSON 字符串：

```json
{
  "errorCode": "invalid_input",
  "error": "the generation request uses unsupported settings",
  "errorMessage": "Please reduce the prompt length."
}
```

| `errorCode`            | 含义                                        |
| ---------------------- | ------------------------------------------- |
| `invalid_input`        | 模型拒绝了这些设置；`errorMessage` 说明原因 |
| `content_rejected`     | 审核拒绝了提示词或源素材                    |
| `provider_unavailable` | 模型服务不可用                              |
| `rate_limited`         | 模型服务繁忙                                |
| `request_cancelled`    | 请求在上游被取消                            |
| `insufficient_credits` | 积分不足                                    |
| `auth_required`        | 需要认证                                    |
| `busy`                 | 已有另一个请求在运行                        |
| `duplicate_request`    | 相同请求已在运行                            |
| `generic`              | 其他失败                                    |

只有 `invalid_input` 时 `errorMessage` 才包含模型给出的原因；其他代码下它与 `error` 相同。

## 结果 URL

`taskUrls` 列出生成的文件。任务成功后请尽快下载并保存副本。结果 URL 不是永久的：部分由模型服务商托管，可能在一天内过期，ViewMax 也不保证生成媒体的保存期限。

## 访问与查询

- key 可以读取所属账户的所有任务，包括在网页端或通过 MCP 创建的任务。
- 任务 ID 不存在或属于其他账户时，返回 `404`，`message` 为 `"task not found"`。
- v1 没有列出任务的端点。请保存你创建的每个任务 ID；使用 `Idempotency-Key` 时，也可以通过重复创建请求找回任务。
- v1 没有取消任务的端点。`canceled` 只会由模型设置。

## 幂等重放

用相同的 `Idempotency-Key` 重复创建请求，会返回原任务的当前状态且不扣费，即使该任务已失败。要重新尝试，请使用新的 key。