Skip to Content

统一格式

在支持的模型上使用统一的高频参数名,同时透传模型特有的原厂参数。

原厂格式与统一格式

  • format: "native"(默认):使用模型厂商原厂参数名,完整定义见 GET /v1/models/{id} 的 input_schema。
  • format: "unified":对高频字段(prompt、images、aspect_ratio、resolution、duration 等)使用统一命名,未覆盖的模型特有字段会原样透传给原厂参数。

如果模型的 unified.supported 为 false,传入 format: "unified" 会返回 HTTP 422(unified_not_supported)。

不是每个模型都支持全部统一字段。GET /v1/models/{id} 的 unified.mapping 列出这个模型接受哪些统一字段、各自转换成哪个原厂参数(模型页上有同样内容的表格)。传了模型不支持的统一字段会返回 HTTP 422(invalid_parameter)。

统一字段一览

统一字段名含义
prompt / negative_prompt提示词 / 负向提示词
images参考图 URL 或 URL 数组
videos / audios参考视频、参考音频 URL 数组
first_frame / last_frame视频首帧、尾帧 URL
aspect_ratio画面比例,如 "16:9"、"9:16"、"1:1"、"auto"
resolution分辨率,如 "480p"、"720p"、"1080p"、"2K"、"4K"
duration视频时长(整数秒)
n生成数量
seed随机种子

请求示例

任务对象中的 task.input 会记录转换后实际执行的原厂参数。

curl -X POST https://api.kerox.ai/v1/tasks \
  -H "Authorization: Bearer $KEROX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedream-5.5",
    "format": "unified",
    "input": {
      "prompt": "minimalist studio product photo of a glass kettle on stone",
      "resolution": "2K",
      "aspect_ratio": "16:9"
    }
  }'

参数改名与弃用提示

当模型参数改名时,旧参数名至少继续兼容 90 天。过渡期内,接口响应会在 warnings 中返回 param_renamed,并在响应头里附带 deprecation 提示。