# 统一格式

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

## 原厂格式与统一格式

- **`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` 会记录转换后实际执行的原厂参数。

```bash
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"
    }
  }'
```
```python
import os
import requests

resp = requests.post(
    "https://api.kerox.ai/v1/tasks",
    headers={
        "Authorization": f"Bearer {os.environ['KEROX_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "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",
        },
    },
    timeout=30,
)
print(resp.json())
```
```javascript
const res = await fetch('https://api.kerox.ai/v1/tasks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KEROX_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    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',
    },
  }),
});
console.log(await res.json());
```

## 参数改名与弃用提示

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