Models in the API - ZeroGen Docs

Every run 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. To compare model families and what each is good at, see Models.

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, keyframes-to-video, reference-to-video, audio-to-video, video-to-video, reference-video-to-video, extend-video, motion-control, lip-sync, clean-plate, render-to-real, hdr, or text-to-speech. An ID stays the same across a vendor’s builds while its request schema stays the same. Each run 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`, `video`, or `speech`	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/runs 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 run 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. For a speech model, the script to read aloud.
`voice`	Speech models only, and required for them. The voice to read the prompt in, from the voices the model’s request schema lists.
`inputs`	Up to 50 inputs. Each has a `role` and either `asset`, a Library asset ID, or `url`, an `https` URL. A `keyframe` input also has `timeSeconds`. 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 add the outputs to. 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.

A speech model takes prompt and voice, and no inputs or output. Input roles are source, reference, face-reference, start-frame, end-frame, keyframe, and mask. Send face-reference for an image or video that shows a real person, on models whose schema lists that role. A keyframe pins its image to timeSeconds: seconds from the start of the video, on a whole frame at the role’s frameRate, and at most output.durationSeconds. Each keyframe needs timeSeconds, and no other role takes it. The role’s limit in x-roles counts start frames, end frames, and keyframes together.

Quote a run

POST /v1/runs/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 runs: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.

Warnings and drafts

Each output in a run can carry two more fields:

warnings lists what the provider ignored, such as an unused reference. Each warning has a code and a message. Outputs without warnings leave it out.
draft appears on a succeeded 480p draft output. Models that make drafts, such as Seedance 2.5, list a parameter titled 480p Draft in their request schema. draft.upscalable says whether the draft can be upscaled now, and draft.expiresAt is when upscaling closes. draft.upscale and draft.finalAssetId report an upscale started in ZeroGen.

You can upscale a draft only in ZeroGen, not through the API. For details, see Draft, then upscale.

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

​Model IDs

​List models

​Read the request schema

​The run request

​Quote a run

​Warnings and drafts

​Deprecated models