跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.foxapi.cc/llms.txt

Use this file to discover all available pages before exploring further.

​
HTTP 状态码

状态码描述常见原因
200成功请求处理成功
400请求格式错误JSON 格式错误、Content-Type 不正确
401未授权API Key 无效、过期或缺失
402余额不足账户余额不足，请充值后重试
404未找到任务 ID 不存在
422参数校验失败缺少必填字段、参数值不合法、模型不存在
429请求频率超限超出速率限制，请稍后重试
500服务器内部错误服务端未知错误，请稍后重试
503服务暂不可用当前模型无可用渠道或上游服务异常，请稍后重试

​
错误响应格式

所有错误响应遵循以下格式： 
{
  "error": {
    "message": "错误描述",
    "type": "error_type"
  }
}
任务失败时，任务查询响应中的 error 字段包含额外的 code 字段： 
{
  "error": {
    "code": "specific_error_code",
    "message": "错误描述",
    "type": "task_error"
  }
}

​
错误类型

错误类型对应状态码描述
invalid_request_error400, 422请求格式错误或参数校验失败
authentication_error401API Key 无效、过期或缺失
insufficient_quota402账户余额不足
not_found404请求的资源不存在
rate_limit_error429请求频率超限
server_error500服务器内部错误
service_unavailable_error422模型暂时不可用（无可用渠道）

​
提交阶段错误码

提交任务时，如果参数校验通过但渠道匹配失败，会返回 422 状态码，error.code 字段包含以下错误码：
错误码描述建议操作
unsupported_advanced_options请求中的高级参数当前无可用渠道支持参考响应中的 unsupported_advanced_options 字段（每项含参数名与默认值），移除这些参数后重试
param_constraints_unsatisfiable参数值超出当前可用渠道支持的范围检查参数值是否在文档标注的可选值范围内
no_compatible_channel该模型暂时无可用渠道稍后重试
invalid_file_type媒体文件的实际内容与期望类型不符检查文件是否损坏或扩展名与内容不一致

​
文件类型不匹配（invalid_file_type）

提交任务时，系统会对请求中的媒体文件 URL（image_url、audio_url、video_url 等）进行内容检测。如果文件的实际格式与字段期望的类型不一致（例如 audio_url 指向的文件实际是压缩包），会返回 422 状态码和 invalid_file_type 错误码。 响应中包含以下额外字段，便于前端定位问题：
字段描述
field触发校验失败的参数名（如 audio_url）
detected_type检测到的实际 MIME 类型（如 application/x-tar）
expected_type期望的媒体类别（image / audio / video）
示例响应： 
{
  "error": {
    "message": "The file '002543212992.mp3' is detected as tar 归档文件 (application/x-tar), not a valid audio file. Please verify the file content matches the expected format.",
    "type": "invalid_request_error",
    "code": "invalid_file_type",
    "field": "audio_url",
    "detected_type": "application/x-tar",
    "expected_type": "audio"
  }
}
文件类型检测基于文件头的 magic bytes，不依赖文件扩展名或 HTTP Content-Type header。如果文件本身格式正确但无法识别（如不常见的编码格式），系统会静默放行，不会阻断请求。

​
高级参数暂不支持（unsupported_advanced_options）

部分参数为高级参数，不是所有渠道都支持。当请求中包含的高级参数在当前模型的所有可用渠道上都不被支持时，会返回 422 状态码和 unsupported_advanced_options 错误码。 响应中包含以下结构化字段，便于程序解析：
字段描述
model触发该错误的模型 ID
unsupported_advanced_options不支持的高级参数列表，每一项包含 param（参数名）和 default_value（该参数在请求 Schema 中的默认值，移除参数后系统按此值处理）
示例响应： 
{
  "error": {
    "message": "The advanced options [enhance_prompt, seed] are not supported by any available channel for model 'veo-3.1'. Remove the unsupported options to proceed.",
    "type": "invalid_request_error",
    "code": "unsupported_advanced_options",
    "model": "veo-3.1",
    "unsupported_advanced_options": [
      {"param": "enhance_prompt", "default_value": false},
      {"param": "seed", "default_value": null}
    ]
  }
}
  • 高级参数在各模型的 API 文档中以 x-advanced 标记。移除不支持的高级参数不影响核心功能，生成结果仍然正常。
  • default_value 来自请求 Schema 的字段默认值（null 表示该参数本就可选、不传时系统不会附加任何值）。

​
任务相关错误码

查询任务状态时，状态为 failed 的任务会在 error.code 字段中包含以下错误码：
错误码描述建议操作
task_failed任务执行失败（通用）重新发起请求
content_policy_violation输入内容违反内容策略修改提示词后重试
invalid_image_url提供的图像/视频 URL 无法访问检查 URL 是否公开可访问
file_too_large上传的文件超出大小限制减小文件大小
unsupported_format不支持的文件格式使用支持的格式

​
速率限制

  • 速率限制按 API Key 应用
  • 被限速时返回 429 状态码，请等待后重试
  • 如需更高速率限制，请联系客服

​
最佳实践

  1. 始终检查 HTTP 状态码 再解析响应体
  2. 实现指数退避 对 429 和 5xx 错误进行重试
  3. 记录错误响应 用于调试和排查
  4. 合理轮询任务状态 建议间隔 3-5 秒，避免过于频繁
  5. 优雅处理异步任务 生成任务耗时因模型而异，请参考各模型文档中的预计时间