# Unified format

> Call supported models with a shared parameter vocabulary while passing model-specific options through unchanged.

## Native vs. unified

- **`format: "native"` (default)**: Pass the model maker's own parameter names as documented in `GET /v1/models/{id}` (`input_schema`).
- **`format: "unified"`**: Use shared names for high-frequency inputs (`prompt`, `images`, `aspect_ratio`, `resolution`, `duration`, etc.). Any extra native parameter not in the unified map is passed through as-is.

If a model has `unified.supported: false`, sending `format: "unified"` returns HTTP `422` (`unified_not_supported`).

Not every model takes every unified field. `unified.mapping` in `GET /v1/models/{id}` lists the fields a model accepts and the native parameter each one becomes (the model's page shows the same as a table). A unified field the model does not support returns HTTP `422` (`invalid_parameter`).

## Unified fields

| Unified name | Meaning |
| --- | --- |
| `prompt` / `negative_prompt` | Text prompt / negative prompt |
| `images` | Reference image URL or array of URLs |
| `videos` / `audios` | Reference video or audio URLs |
| `first_frame` / `last_frame` | Video start and end frame URLs |
| `aspect_ratio` | `"16:9"`, `"9:16"`, `"1:1"`, `"auto"`, etc. |
| `resolution` | `"480p"`, `"720p"`, `"1080p"`, `"2K"`, `"4K"` |
| `duration` | Video duration in whole seconds |
| `n` | Number of outputs |
| `seed` | Random seed |

## Example request

In the task response, `task.input` shows the normalized native parameters that were actually executed.

```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());
```

## Parameter renames & deprecations

When a model renames a parameter, Kerox keeps the previous parameter name working for at least **90 days**. During the transition period, responses include a `warnings` entry (`param_renamed`) and a `deprecation` response header.
