统一格式
在支持的模型上使用统一的高频参数名,同时透传模型特有的原厂参数。
原厂格式与统一格式
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 提示。