> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zerogen.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Models

> Find a model, read the request schema it accepts, and handle deprecations.

Every generation names one model doing one operation. Use the models endpoints
to find the models your organization can run and the exact request each one
accepts.

## Model IDs

A model ID has three segments, `{vendor}/{model}/{operation}`, such as
`openai/gpt-image-2/generate` or `kling/o3-pro/reference-to-video`:

* **Vendor** is the company that makes the model, not the provider that ZeroGen
  routes it through, so a change of provider doesn't change the ID.
* **Model** names the model.
* **Operation** names what the model does. A model that does several things has
  one ID for each.

The operation is one of the following: `generate`, `edit`, `inpaint`, `remix`,
`outpaint`, `text-to-vector`, `text-to-video`, `image-to-video`,
`first-last-frame-to-video`, `reference-to-video`, `audio-to-video`,
`video-to-video`, `reference-video-to-video`, `extend-video`, `motion-control`,
`clean-plate`, `render-to-real`, or `hdr`.

An ID stays the same across a vendor's builds while its request schema stays
the same. Each generation reports the build that ran as `modelVersion`, or
`null` when the provider doesn't name one. A price change keeps the ID. An ID
changes only when the request schema changes or the vendor ships a materially
different model, and ZeroGen never reuses an ID for another model.

## List models

`GET /v1/models` lists the models your organization can run. It needs the
`models:read` scope.

```bash theme={null}
curl "https://api.zerogen.com/v1/models?capability=video&operation=image-to-video" \
  -H "Authorization: Bearer $ZEROGEN_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "id": "minimax/h3-max/image-to-video",
      "name": "MiniMax H3 Max (image-to-video)",
      "capability": "video",
      "operation": "image-to-video",
      "status": "active",
      "sunsetAt": null
    }
  ],
  "nextCursor": null
}
```

The list takes the following optional filters, plus `limit` and `cursor` as
described in [Pagination](https://docs.zerogen.com/pagination.md):

| Parameter | Values | Lists |
| - | - | - |
| `capability` | `image` or `video` | Models of that capability. |
| `operation` | An operation from the list above | Models doing that operation. |
| `q` | Text | Models whose ID or name matches, including the maker and related operations. |
| `frames` | `start` or `start-end` | Video models that accept at least these frames. |
| `audio` | `true` | Video models that can generate audio. |
| `referenceKind` | `image`, `video`, or `audio` | Models that accept references of that kind. |

## Read the request schema

`GET /v1/models/{vendor}/{model}/{operation}` returns one model with
`requestSchema`: the JSON Schema (draft 2020-12) that a `POST /v1/generations`
body for this model must match. It needs the `models:read` scope.

The schema covers the whole request body, including `projectId`, `folderId`
and `naming`, which work the same for every model.

```bash theme={null}
curl https://api.zerogen.com/v1/models/openai/gpt-image-2/generate \
  -H "Authorization: Bearer $ZEROGEN_API_KEY"
```

The schema reflects your organization: it leaves out optional controls that
your organization's billing doesn't price. It adds the following extensions to
JSON Schema:

| Extension | Description |
| - | - |
| `x-roles` | Under `inputs`. Each input role the model takes, with the media types it accepts, its limits, and `urlAccept`, the media types a URL input can be. |
| `x-prompt-references` | Present when the prompt can refer to inputs by tokens such as `@image1`. |

## The generation request

Every model shares one request shape. The model's request schema states which
fields and values it accepts, and ZeroGen rejects unknown fields.

| Field | Description |
| - | - |
| `model` | Required. The model ID. |
| `prompt` | The prompt, up to 20,000 characters. |
| `inputs` | Up to 50 inputs. Each has a `role` and either `asset`, a Library asset ID, or `url`, an `https` URL. For details, see [Uploads and URL inputs](https://docs.zerogen.com/uploads.md). |
| `output` | Output settings: `count` (1 to 4), `size`, `quality`, `background`, `format` (`png`, `jpeg`, or `webp`), `aspectRatio`, `resolution`, `durationSeconds`, and `includeAudio`. |
| `parameters` | Model-specific parameters that the model's schema lists. |
| `maxCostMicroUsd` | Refuse to start when the quote is higher than this amount. For details, see [Billing](https://docs.zerogen.com/billing.md). |
| `projectId` | The project the outputs are saved in. Defaults to your organization's default project. |
| `folderId` | A folder in that project to file the outputs in. Omit it, or send `null`, to leave them unfiled. |
| `naming` | Name the outputs with one of the project's naming presets: `presetId`, and `values` for the preset's fields by field ID. Fields you leave out take the preset's defaults. |
| `test` | Test keys only. Rehearses outcomes. For details, see [Test keys](https://docs.zerogen.com/test-keys.md). |

Input roles are `source`, `reference`, `face-reference`, `start-frame`,
`end-frame`, and `mask`. Send `face-reference` for an image or video that shows
a real person, on models whose schema lists that role.

## Quote a generation

`POST /v1/generations/quote` takes the same body as a create and runs the same
validation and pricing at your organization's rates. It starts nothing and
holds nothing. It needs the `generations:create` scope.

```json theme={null}
{
  "model": "openai/gpt-image-2/generate",
  "billing": {
    "mode": "platform",
    "quotedMicroUsd": 42000
  }
}
```

`quotedMicroUsd` is the amount that a create with the same body would hold. A
quote imports its URL inputs into your Library, as a create does.

## Deprecated models

ZeroGen marks a model `deprecated` before retiring it. A deprecated model keeps
working until its `sunsetAt` time. After that, requests that name it fail with
`400 model_unavailable`. A model that anyone used in the 90 days before its
retirement is deprecated at least 90 days ahead.

Responses that name a deprecated model carry two headers:

| Header | Description |
| - | - |
| `Deprecation` | When the model was deprecated, as `@` and Unix seconds ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)). |
| `Sunset` | When the model stops accepting requests, as an HTTP date ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)). |

ZeroGen sends them on the model's detail, and on creating, reading, quoting, or
cancelling a generation with that model:

```http theme={null}
Deprecation: @1792540800
Sunset: Mon, 21 Feb 2028 00:00:00 GMT
```

To migrate, list models with the same `operation`, read the replacement's
request schema, and update your requests before the sunset.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.