API 错误

ViewMax v1 错误信封、HTTP 状态码、全部错误消息，以及何时重试。

错误响应

每个 v1 错误都是包含 code、message 和 error 对象的 JSON，没有 data。

{
  "code": -1,
  "message": "viewmax-c1 text-to-video supports duration 1s|2s|3s|4s|5s|6s|7s|8s|9s|10s|11s|12s|13s|14s|15s, got 30s",
  "error": {
    "type": "invalid_request",
    "hint": "Fix the request using this message, then retry. Refresh GET /api/v1/models before repeating an unsupported model or option.",
    "docs": "https://viewmax.studio/docs/api/errors"
  }
}

字段	说明
`code`	`-1`、`-1001`（未认证）或 `-1002`（积分不足）
`message`	出错原因，消息列表见下文
`error.type`	`invalid_request`、`content_rejected`、`unauthorized`、`insufficient_credits`、`not_found` 或 `internal_error`
`error.hint`	下一步操作，包括重试是否有用
`error.docs`	文档链接
`error.task_id`	请求在失败前已创建任务时出现

状态码

HTTP	`code`	`error.type`	何时出现	是否重试？
`400`	`-1`	`invalid_request`	请求、模型、模式或选项无效，或模型拒绝了这些设置	否，先修正请求
`400`	`-1`	`content_rejected`	提示词或源素材被安全检查拒绝	否，更换内容
`401`	`-1001`	`unauthorized`	缺少或无效的 API key	否，发送有效 key
`402`	`-1002`	`insufficient_credits`	余额低于费用，未创建任务	否，先充值
`404`	`-1`	`not_found`	任务不存在、属于其他账户，或端点不存在	否
`405`	—	—	路径存在但不支持此方法，响应体为空	否，使用文档中的方法
`500`	`-1`	`internal_error`	服务商或服务器故障	检查 `error.task_id` 后重试一次
`503`	`-1`	`internal_error`	内容安全检查暂时不可用	是，稍后重试

是否应该重试？

400、401、402、404：不要重复同一请求，按消息修正。
503：稍后重试同一请求。
没有 error.task_id 的 500：稍等片刻后重试一次。
任何带 error.task_id 的错误：先查询 GET /api/v1/tasks/{task_id}。
- failed：积分已退回。阅读失败载荷，必要时再创建新任务。
- pending 或 processing：模型仍可能交付该任务。请继续轮询而不是重试；新请求会再次扣费。
重试创建请求时，如果不确定第一次请求是否到达 ViewMax，请复用同一个 Idempotency-Key。已存在的任务会直接返回，不会重复扣费。

Idempotency-Key

在每个创建请求上发送 Idempotency-Key：POST /api/v1/videos、images、music、speech 和 sound-effects。

key 为 1–200 个可见 ASCII 字符、不含空格，例如 UUID。其他格式返回 400，消息为 Idempotency-Key must be 1-200 visible ASCII characters without spaces。
重复的 key 返回首次请求创建的任务及其原始 costCredits，不会扣费。不会比较请求体。
key 的作用域是你的账户，在所有创建端点间共享。
即使原任务已失败，重放也会返回它。新的尝试请使用新 key。
不带该请求头时，每个 POST 都会创建并扣费一个新任务。

400 `invalid_request` 消息

尖括号表示随请求变化的值。

所有创建端点

消息	原因	处理
JSON 解析器消息，例如 `Unexpected end of JSON input`	请求体不是合法 JSON	使用 `Content-Type: application/json` 发送 JSON 对象
`request body must be an object`	请求体是 JSON 但不是对象	发送 JSON 对象
`Idempotency-Key must be 1-200 visible ASCII characters without spaces`	`Idempotency-Key` 请求头格式错误	使用 UUID 或其他短令牌
`model is required`	缺少 `model`（videos、images）	发送 `GET /api/v1/models` 中的 ID
`prompt is required`	缺少 `prompt` 或为空	发送非空提示词
`options must be an object`	`options` 不是对象	以 JSON 对象发送 options
`image_urls must be an array of URLs`	`image_urls` 不是字符串数组	发送公开 HTTP(S) URL 数组
`This capability is unavailable.`	模型或模式已停用，例如 Motion Control	换用其他模型；重试仍会失败
`the generation request uses unsupported settings`	任务创建后模型拒绝了这些设置。任务已失败并退款，`error.task_id` 有值	读取该任务的 `taskInfo.errorMessage`，调整后创建新任务
`invalid params or unsupported model for scene`	该模型不支持此模式	从目录中选择模型和模式

视频（`POST /api/v1/videos`）

消息	原因	处理
`video_urls must be an array of URLs`	`video_urls` 不是字符串数组	发送公开 HTTP(S) URL 数组
`mode must be one of text-to-video\|image-to-video\|video-to-video\|frames-to-video\|reference-to-video, got <mode>`	未知模式	使用五种模式 ID 之一
`unsupported video model: <model>`	未知模型 ID	使用 `GET /api/v1/models` 中的 `id`
`video model temporarily unavailable: <model>. The provider is not serving this model right now — pick a different model.`	模型已下线，例如 `sora-2`	换用其他模型
`<model> does not support mode <mode>`	模式不在该模型的 `modes` 中	选择列出的模式
`<model> prompt must be <max> characters or fewer, got <length>`	去除首尾空白后的提示词超过 `max_prompt_length`	缩短提示词
`image_urls must contain valid http(s) URLs`	URL 不是以 `http://` 或 `https://` 开头	发送公开 HTTP(S) URL（`video_urls` 同理）
`<model> <mode> requires image_urls`	该模式需要图片	添加图片 URL
`<model> <mode> requires image_urls (at least 2)`	`frames-to-video` 需要首帧和尾帧	发送两个图片 URL
`<model> <mode> requires video_urls`	`video-to-video` 需要源视频	添加一个视频 URL
`<model> <mode> does not accept image_urls; supported inputs: <inputs>`	该模式不接受图片（或视频）	移除该输入或换用其他模式
`<model> <mode> supports at most <n> image_urls, got <count>`	输入过多（`video_urls` 同理）	减少 URL 数量
`<model> <mode> requires options.source_video_duration_seconds when video_urls is provided`	按秒计费的模型收到了视频	发送源视频时长（秒）
`<model> <mode> supports duration <values>, got <value>`	不支持的 `duration`	使用该模式 `durations` 中的值
`<model> <mode> supports duration <values> at <resolution>, got <value>`	该分辨率下不提供此时长	调整时长或分辨率
`<model> <mode> supports resolution <values>, got <value>`	不支持的 `resolution`（列表为空表示不要发送）	使用 `resolutions` 中的值，或省略
`<model> <mode> supports aspect_ratio <values>, got <value>`	不支持的 `aspect_ratio`	使用 `aspect_ratios` 中的值，或省略
`<model> <mode> supports audio false, got true`	该模式没有音频开关	移除 `audio` 或发送 `false`

示例：kling-2-6 text-to-video supports duration 5s|10s, got 30s；runway text-to-video supports duration 5s at 1080p, got 10s。

图片、音乐、语音和音效

消息	端点	处理
`scene must be one of text-to-image\|image-to-image, got <scene>`	`images`	使用列出的 scene
`unsupported image model: <model>. Supported models: <ids>`	`images`	使用 `GET /api/v1/models?type=image` 中的 ID
`<model> supports scene <scenes>, got <scene>`	`images`	选择该模型支持的 scene
`image-to-image requires image_urls`	`images`	添加图片 URL
`Invalid GPT Image 2.5 quality`、`resolution`、`aspect ratio` 或 `pixel dimensions`	`images`	使用 GPT Image 2.5 模型列出的值
`options.duration_seconds must be a number from 3 to 300`	`music`	发送 3 到 300 之间的数字
`options.duration is not supported; use options.duration_seconds`	`music`	改用 `duration_seconds`（`music_length_ms` 同理）
`text is required`、`voice_id is required`	`speech`	两个字段都要发送
`unknown voice_id: <id>. Call GET /api/v1/voices (MCP: list_voices) for available voices.`	`speech`	使用 `GET /api/v1/voices` 中的 ID
`options.duration_seconds must be a number from 0.5 to 22`	`sound-effects`	发送范围内的数字
`options.prompt_influence must be a number from 0 to 1`	`sound-effects`	发送范围内的数字

400 `content_rejected` 消息

消息	原因	处理
`input content was rejected by safety filters`	提示词提及禁止用途（deepfake、换脸或冒充他人）。在创建任务和扣费前检查，即使出现在否定指令中（如“不要换脸”）也会命中	删除相关措辞；原样重试仍会失败
`input content was rejected by safety filters`	任务创建后模型审核拒绝了提示词或素材。任务已失败并退款，`error.task_id` 有值	更换内容后创建新任务
`Prompt was blocked by content safety review.`	内容安全审核拦截了提示词	修改提示词

其他状态

HTTP	消息	说明
`401`	`unauthorized`	参见认证
`402`	`insufficient credits`	在创建任务前检查，包括两个请求争用同一余额的情况。`error.docs` 指向价格页
`404`	`task not found`	任务 ID 不存在或属于其他账户
`404`	`endpoint not found`	未知的 `/api/...` 路径。参见 OpenAPI
`500`	`the generation service is temporarily unavailable`	模型服务故障或无响应。重试前检查 `error.task_id`
`500`	`media generation failed`	其他失败。重试前检查 `error.task_id`
`500`	`the generation service is busy; try again later`	模型服务限流，稍后重试
`500`	`the generation request was cancelled`	请求在上游被取消，重试一次
`503`	`Content safety check is temporarily unavailable. Please try again in a moment.`	稍后重试

轮询 GET /api/v1/tasks/{taskId} 时出现的 500 是暂时性的：继续轮询同一任务即可。

API 错误

On this page