错误说明

功能概览

本页用于说明 错误说明 的核心能力、调用入口和接入要点，帮助开发者快速判断适用场景并完成集成。

适用场景

• 产品原型验证：快速接入模型能力，验证内容生成、理解或编辑流程。
• 生产业务接入：用于批量任务、自动化工作流和多模型组合调用。
• 能力迁移适配：适合从原有模型或 SDK 平滑切换到亿速云AI统一接口。

接入建议

• 优先确认模型名称、请求路径和响应字段，再接入具体业务流程。
• 对异步任务、媒体生成和长耗时请求，建议在业务侧加入重试与状态轮询。
• 上线前建议准备日志追踪、错误兜底和内容安全校验，便于稳定运行。

通用错误格式

HTTP 接口错误统一返回 OpenAI 风格对象：

{
  "error": {
    "message": "The service failed to process the request. Please try again.",
    "type": "server_error",
    "param": null,
    "code": "service_error"
  }
}

字段说明：

通用错误

示例：

{
  "error": {
    "message": "Invalid API token",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

模型和接口错误

模型不存在示例：

{
  "error": {
    "message": "Model 'unknown-model' does not exist or is not available",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

模型暂不可用示例：

{
  "error": {
    "message": "The requested model is temporarily unavailable. Please try again later.",
    "type": "server_error",
    "param": "model",
    "code": "service_unavailable"
  }
}

图片生成错误

适用于：

POST /v1/chat/completions
POST /v1/images/generations
POST /v1/images/edits

未生成图片示例：

{
  "error": {
    "message": "We couldn't generate an image for this request. Please revise the prompt or reference image and try again.",
    "type": "invalid_request_error",
    "param": null,
    "code": "content_not_returned"
  }
}

疑似内容规范命中示例：

{
  "error": {
    "message": "We couldn't generate an image because the request may violate our content guidelines. Please revise the prompt or reference image and try again.",
    "type": "invalid_request_error",
    "param": null,
    "code": "content_policy_violation"
  }
}

处理失败示例：

{
  "error": {
    "message": "The service failed to process the request. Please try again.",
    "type": "server_error",
    "param": null,
    "code": "service_error"
  }
}

请求超时示例：

{
  "error": {
    "message": "The request timed out. Please try again.",
    "type": "server_error",
    "param": null,
    "code": "request_timeout"
  }
}

Images Generations 参数错误

适用于：

POST /v1/images/generations

response_format 错误示例：

{
  "error": {
    "message": "Unsupported response_format: xxx",
    "type": "invalid_request_error",
    "param": "response_format",
    "code": "invalid_response_format"
  }
}

Images Edits 参数错误

适用于：

POST /v1/images/edits

图片数量超过限制示例：

{
  "error": {
    "message": "images supports at most 6 items",
    "type": "invalid_request_error",
    "param": "images",
    "code": "invalid_image_input"
  }
}

Videos 错误

适用于：

POST /v1/videos
GET /v1/videos/{video_id}
GET /v1/videos/{video_id}/content

视频异步任务失败后，GET /v1/videos/{video_id} 的 error 对象也使用公开错误码和公开文案：

{
  "id": "video_req_xxx",
  "object": "video",
  "created_at": 1730000000,
  "status": "failed",
  "model": "grok-imagine-video",
  "error": {
    "code": "service_error",
    "message": "The service failed to process the request. Please try again."
  }
}

视频请求疑似内容规范命中示例：

{
  "id": "video_req_xxx",
  "object": "video",
  "created_at": 1730000000,
  "status": "failed",
  "model": "grok-imagine-video",
  "error": {
    "code": "content_policy_violation",
    "message": "We couldn't generate a video because the request may violate our content guidelines. Please revise the prompt or reference image and try again."
  }
}

视频未生成内容示例：

{
  "id": "video_req_xxx",
  "object": "video",
  "created_at": 1730000000,
  "status": "failed",
  "model": "grok-imagine-video",
  "error": {
    "code": "content_not_returned",
    "message": "We couldn't generate a video for this request. Please revise the prompt or reference image and try again."
  }
}

内部完整原因仍保留在后台请求记录和 raw_response_json 中，不会返回给普通 API 用户。