任务

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

查询任务

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。创建响应和本端点返回相同的任务对象。

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

{
  "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 错误。

失败载荷

当 status 为 failed 或 canceled 时，taskInfo 和 taskResult 都是同一个 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。

任务

On this page