错误详情

Error 提供比数字错误码更具体的错误分类、原因和处理建议。它是可选的补充信息，不替代 ErrCode、ErrMsg 或 Resp，也不改变 HTTP 状态。现有客户端可以继续使用原有错误处理逻辑，无需添加额外请求头。

数字业务错误码的含义见错误码。任务的执行状态和查询方式见任务状态。

{
  "ErrCode": 400017,
  "ErrMsg": "Required field prompt are missing or empty.",
  "Resp": null,
  "Error": {
    "Type": "FIELD_REQUIRED",
    "Message": "Required field 'prompt' is missing or empty. Provide a value for this field.",
    "Param": {
      "Fields": [
        "prompt"
      ]
    }
  }
}

Error 字段说明

先按现有逻辑判断请求是否失败。如果响应中包含 Error，可以查看 Error.Type 了解错误类型，再查看 Error.Message 和 Error.Param 了解原因与处理建议。没有 Error 时，仍按原有错误码处理；缺少 Error 不代表请求成功。

字段	作用
`Error.Type`	稳定的错误类型标识，可用于判断如何处理错误。一个数字错误码可能对应多种错误类型。
`Error.Message`	失败原因和修改建议。不要根据消息的具体文字判断错误类型。
`Error.Param`	与错误相关的补充信息，为 JSON 对象。没有可用信息时返回 `{}`。

解析响应时，应允许出现不认识的字段。如果遇到不认识的 Error.Type，按通用错误处理，并保留完整响应以便排查。

Error.Param

字段	类型	说明
`Fields`	string[]	与错误相关的请求字段，例如 `["prompt"]`。
`AllowedValues`	string[]	本次请求可使用的值，仅用于 `quality`、`aspect_ratio` 和 `duration`。`duration` 的值也以字符串返回。
`RequiredField`	string	需要改用的请求字段，例如 `img_id`。
`RequiredCount`	integer	模板需要的素材数量，例如 `2`。
`Moderation.LabelName`	string	如果有具体审核原因，会在此返回；多条原因用换行分隔。

这些字段按需返回，不一定同时出现。请以实际响应和接口文档为准，不要自行假定未返回字段的值。

以下是几种常见的错误响应示例，供参考。

字段取值不符合要求

例如，quality 的值不符合接口要求。响应中的 Fields 会指出需要修改的字段，AllowedValues 列出可用的值。

{
  "ErrCode": 400017,
  "ErrMsg": "invalid param",
  "Resp": null,
  "Error": {
    "Type": "FIELD_VALUE_INVALID",
    "Message": "Field 'quality' has an unsupported value. Check the allowed values and format for this endpoint.",
    "Param": {
      "AllowedValues": ["360p", "540p", "720p", "1080p"],
      "Fields": ["quality"]
    }
  }
}

不同接口、模型或模板支持的取值可能不同，请以响应中的 AllowedValues 为准。无法确定完整的可用值列表时，响应可能不包含 AllowedValues。

字段选择不符合要求

例如，没有选择多图模板，却使用了 img_ids。此时 RequiredField 返回 img_id，提示你改用单图字段；若需要多图输入，请选择支持多图的模板。

{
  "ErrCode": 400017,
  "ErrMsg": "img_ids is not supported in this case. Please use `img_id` instead.",
  "Resp": null,
  "Error": {
    "Type": "MULTI_IMAGE_INPUT_UNSUPPORTED",
    "Message": "Field 'img_ids' requires a multi-image template, but 'template_id' is missing or '0'. Replace 'img_ids' with 'img_id' for one image, or set 'template_id' to a multi-image template and supply its required number of image IDs in 'img_ids'.",
    "Param": {
      "Fields": ["img_id", "img_ids", "template_id"],
      "RequiredField": "img_id"
    }
  }
}

素材数量不符合要求

例如，模板需要 2 张图片，但请求只提供了 1 张。响应中的 RequiredCount 为 2，表示需要提供的图片数量。

{
  "ErrCode": 400017,
  "ErrMsg": "For the selected template_id, the img_ids array must contain 2 image（s）.",
  "Error": {
    "Type": "TEMPLATE_IMAGE_COUNT_MISMATCH",
    "Message": "The selected template requires exactly '2' image IDs in 'img_ids'. Adjust the array length to match this count.",
    "Param": {
      "Fields": ["img_ids", "template_id"],
      "RequiredCount": 2
    }
  }
}

所需素材数量请以模板要求和实际返回的 RequiredCount 为准。

素材未通过内容审核

例如，上传的图片未通过内容审核。如果有具体审核原因，可在 Moderation.LabelName 中查看中文说明。

{
  "ErrCode": 500054,
  "ErrMsg": "Content moderation failure. Image maybe contains inappropriate content. Please replace with another image and try again.",
  "Error": {
    "Type": "IMAGE_CONTENT_REJECTED",
    "Message": "The supplied image did not pass content moderation. Moderation reason: '色情内容：可能涉及色情内容。'. Replace the image and try again.",
    "Param": {
      "Moderation": {
        "LabelName": "色情内容：可能涉及色情内容。"
      }
    }
  },
  "Resp": null
}

有多条审核原因时，用换行分隔。没有具体原因时，响应会省略 Moderation，仍返回通用的审核失败消息。不要根据审核说明的具体文字判断错误；没有说明也不代表审核通过。

Error.Type 类型索引

用响应 JSON 中的 Error.Type（如 FIELD_REQUIRED）在下表查找含义和处理建议。

`Error.Type`	含义	处理建议
`API_KEY_INVALID`	API Key 无法验证	检查 Key 是否有效，并确认使用了正确的 API 入口。
`API_KEY_REQUIRED`	缺少 API-KEY 请求头	在请求头提供 API-KEY。
`AUDIO_CONTENT_REJECTED`	输入音频未通过内容审核	更换音频后重新提交，不要原样重试。
`AUDIO_DURATION_BELOW_THRESHOLD`	音频时长低于最小要求	换用符合接口和模型时长要求的音频，具体要求见 `Error.Message`。
`CAMERA_MOVEMENT_MODEL_UNSUPPORTED`	模型不支持所选运镜选项	查看 `Error.Message`，改用模型支持的运镜选项。
`CLIENT_REQUEST_CANCELED`	客户端取消了请求	检查客户端超时与取消逻辑；重发生成请求前确认是否已经创建任务。
`CONCURRENCY_LIMIT_EXCEEDED`	达到并发生成上限	等待进行中的任务结束后再提交。
`DURATION_OUT_OF_RANGE`	生成时长不在支持范围内	将生成时长改为接口和模型支持的值，具体范围见 `Error.Message`。
`EFFECT_QUALITY_UNSUPPORTED`	特效不支持指定清晰度	选择当前模板支持的清晰度，具体可用值见 `Error.Message` 或模板说明。
`EXTENDED_DURATION_EXCEEDS_THRESHOLD`	源视频与延长部分的总时长超限	调整源视频或延长时长，使总时长符合 `Error.Message` 中的要求。
`FEATURE_ACCESS_DENIED`	账号没有当前能力的使用权限	联系支持确认能力权限。
`FIELD_REQUIRED`	必填字段缺失或为空	补全 `Error.Param.Fields` 或 `Error.Message` 中指出的必填字段。
`FIELD_VALUE_INVALID`	字段取值或格式不受支持	如果返回了 `Error.Param.AllowedValues`，从中选择可用值；否则请查看接口文档。
`FUSION_INPUT_REQUIRED`	图片和视频参考均为空	按接口要求补充文件、URL 或素材 ID。
`IMAGE_CONTENT_REJECTED`	输入图片未通过内容审核	更换图片后重新提交，不要原样重试。
`IMAGE_DIMENSIONS_BELOW_THRESHOLD`	图片宽度或高度低于最小要求	换用宽高符合要求的图片，具体尺寸见 `Error.Message`。
`IMAGE_DIMENSIONS_EXCEED_THRESHOLD`	图片宽度或高度超过限制	换用宽高符合要求的图片，具体尺寸见 `Error.Message`。
`IMAGE_FORMAT_UNSUPPORTED`	上传图片的格式不受支持	使用接口支持的格式重新导出并上传。
`IMAGE_INPUT_REQUIRED`	未提供图片文件或图片 URL	按接口要求补充文件、URL 或素材 ID。
`IMAGE_REFERENCE_COUNT_EXCEEDS_THRESHOLD`	参考图片数量超过模型限制	减少参考图片数量，具体上限见 `Error.Message` 或对应接口说明。
`IMAGE_REFERENCE_REQUIRED`	未提供所需的图片 ID	按接口要求补充文件、URL 或素材 ID。
`IMAGE_SIZE_EXCEEDS_THRESHOLD`	图片文件大小超过限制	压缩或更换图片，使文件大小符合接口要求。
`INSUFFICIENT_CREDITS`	积分不足	充值或选择积分消耗更低的生成规格。
`MEDIA_ACCESS_DENIED`	当前账号无权访问该媒体	使用当前账号可访问的媒体。
`MEDIA_FORMAT_UNSUPPORTED`	URL 内容不是受支持的媒体格式	使用接口支持的格式重新导出并上传。
`MEDIA_INPUT_REQUIRED`	未提供媒体文件或媒体 URL	按接口要求补充文件、URL 或素材 ID。
`MEDIA_NOT_FOUND`	引用的媒体不存在	检查媒体 ID、类型和可用性，换用符合接口要求的素材。
`MEDIA_TYPE_MISMATCH`	引用的媒体类型与接口要求不符	检查媒体 ID、类型和可用性，换用符合接口要求的素材。
`MEDIA_UNAVAILABLE`	引用的媒体不能用于当前操作	检查媒体 ID、类型和可用性，换用符合接口要求的素材。
`MEDIA_URL_INVALID`	媒体 URL 无效	检查 URL 是否有效且可公开访问，必要时更换链接。
`MIMIC_VIDEO_DURATION_OUT_OF_RANGE`	动作模仿参考视频时长不符合要求	换用时长符合要求的参考视频，具体范围见 `Error.Message`。
`MODIFY_VIDEO_DURATION_OUT_OF_RANGE`	视频编辑源视频时长不符合要求	换用符合视频编辑接口时长要求的视频，具体范围见 `Error.Message`。
`MOTION_MODE_MODEL_UNSUPPORTED`	模型不支持所选运动模式	查看 `Error.Message`，改用模型支持的运动模式。
`MULTI_IMAGE_INPUT_UNSUPPORTED`	当前模板或模式不接受 img_ids	改用 img_id，或选择支持多图的模板并提供所需数量。
`OPTION_MODEL_UNSUPPORTED`	模型不支持指定选项	按 `Error.Message` 的提示，改用模型支持的选项。
`PARAMETER_COMBINATION_UNSUPPORTED`	生成参数组合不受支持	根据 `Error.Message` 的提示调整参数组合。
`PLAN_RESOLUTION_RESTRICTED`	清晰度超过套餐允许范围	降低清晰度或升级套餐。
`PROMPT_REFERENCE_SYNTAX_INVALID`	提示词中的引用语法错误	使用 @ref_name，并在名称后保留空格。
`PROMPT_REFERENCE_UNDEFINED`	提示词引用没有匹配的 ref_name	确保提示词中的引用名称与素材的 `ref_name` 一致，或删除无效引用。
`QUALITY_DURATION_EXCEEDS_THRESHOLD`	所选清晰度下的时长超过限制	缩短生成时长，使其符合所选清晰度的要求，具体上限见 `Error.Message`。
`QUALITY_DURATION_MODEL_UNSUPPORTED`	模型不支持所选清晰度与时长组合	选择模型支持的清晰度和时长组合，具体要求见 `Error.Message`。
`QUALITY_UNSUPPORTED`	当前操作不支持指定清晰度	改用当前接口和模型支持的清晰度，具体可用值见 `Error.Message` 或接口文档。
`RATE_LIMIT_EXCEEDED`	请求频率超过限制	降低请求频率，等待后重试。
`REFERENCE_NAME_DUPLICATED`	参考素材的 ref_name 重复	为每个参考素材使用唯一的 ref_name。
`REMOTE_MEDIA_UNAVAILABLE`	URL 对应的媒体不存在或不可访问	检查 URL 是否有效且可公开访问，必要时更换链接。
`REQUEST_BINDING_FAILED`	请求体无法解析，或参数不符合接口要求	检查请求体格式、字段类型和必填项。
`REQUEST_FIELD_TYPE_INVALID`	字段的 JSON 类型错误	按接口定义传递正确的 JSON 类型，例如数字不要加引号。
`REQUEST_JSON_INVALID`	请求体不是合法 JSON	修正 JSON 语法后重新提交。
`SINGLE_IMAGE_INPUT_UNSUPPORTED`	多图模板不接受单图字段 img_id	改用 `img_ids`，并按模板要求提供图片。若响应中有 `Error.Param.RequiredField`，可据此确认字段名。
`SUBJECT_NOT_DETECTED`	素材中未检测到清晰主体	更换为包含清晰人物或动物主体的素材。
`SYSTEM_ERROR`	服务处理请求时发生系统异常	稍后重试；持续失败时提供 Ai-trace-id 和任务 ID 联系支持。
`TEMPLATE_AUDIO_OPTION_CONFLICT`	模板与音频开关不能同时使用	按 `Error.Message` 的提示调整音频选项，使其符合模板要求。
`TEMPLATE_FEATURE_UNSUPPORTED`	模板不支持当前生成能力	改用支持该生成能力的模板，或按 `Error.Message` 的提示调整请求。
`TEMPLATE_IMAGE_COUNT_MISMATCH`	图片数量不符合模板要求	按模板要求调整图片数量；如果返回了 `Error.Param.RequiredCount`，以该值为准。
`TEMPLATE_MEDIA_TYPE_MISMATCH`	模板输出类型与接口不符	选择与当前接口输出类型一致的模板，或改用与模板对应的接口。
`TEMPLATE_UNAVAILABLE`	模板当前未启用	选择已启用的模板；无法使用时联系支持。
`TEXT_CONTENT_REJECTED`	输入文本未通过内容审核	修改文本后重新提交，不要原样重试。
`TEXT_LENGTH_EXCEEDS_THRESHOLD`	文本长度超过当前限制	按 `Error.Message` 提示的长度上限缩短文本。
`VIDEO_CONTENT_REJECTED`	输入视频未通过内容审核	更换视频后重新提交，不要原样重试。
`VIDEO_DIMENSIONS_EXCEED_THRESHOLD`	视频分辨率超过限制	换用分辨率符合要求的视频，具体限制见 `Error.Message`。
`VIDEO_DURATION_EXCEEDS_THRESHOLD`	输入视频时长超过接口限制	换用时长符合要求的视频，具体上限见 `Error.Message`。
`VIDEO_ID_INVALID`	视频 ID 不是有效的正数 ID	使用视频生成接口返回的正数 video_id。
`VIDEO_INPUT_REQUIRED`	未提供源视频 ID	按接口要求补充文件、URL 或素材 ID。
`VIDEO_REFERENCE_TOTAL_DURATION_EXCEEDS_THRESHOLD`	参考视频总时长超过限制	调整参考视频，使总时长符合接口要求；具体上限见 `Error.Message`。
`VIDEO_SIZE_EXCEEDS_THRESHOLD`	视频文件大小超过限制	压缩或更换视频，使文件大小符合接口要求。

Error 字段说明#

Error.Param#

Error.Type 类型索引#

Error 字段说明

Error.Param

Error.Type 类型索引