Models

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.

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

{
  "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:

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.

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.
`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.
`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.

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.

{
  "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).
`Sunset`	When the model stops accepting requests, as an HTTP date (RFC 8594).

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

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.

Get started

Generate

Conventions

Model IDs

List models

Read the request schema

The generation request

Quote a generation

Deprecated models

​Model IDs

​List models

​Read the request schema

​The generation request

​Quote a generation

​Deprecated models

Model IDs

List models

Read the request schema

The generation request

Quote a generation

Deprecated models