Skip to Content

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 nameMeaning
prompt / negative_promptText prompt / negative prompt
imagesReference image URL or array of URLs
videos / audiosReference video or audio URLs
first_frame / last_frameVideo start and end frame URLs
aspect_ratio"16:9", "9:16", "1:1", "auto", etc.
resolution"480p", "720p", "1080p", "2K", "4K"
durationVideo duration in whole seconds
nNumber of outputs
seedRandom seed

Example request

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

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"
    }
  }'

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.