generation API model list: Use discovery without inventing a full schema

The generation API model list is useful for discovering registered adapters and rendering basic choices. It is not a complete machine-readable schema for every request constraint. Build the interface around that distinction so a discovered model does not become a promise about unverified options.

Read the response narrowly

GET /api/v1/models returns a data array. Each entry contains id, modality, display_name, upstream, and fields. The fields value comes from the adapter’s optional playgroundFields method, with an empty array as the fallback.

The current registry contains nano-banana, flux-pro, ideogram-v3, seedance-2.0-fast, kling-2.0-standard, and veo3. Use the exact id when submitting. A display name is for presentation and is not the identifier expected by provider lookup.

The route accepts a modality query from its recognized set. A recognized modality with no registered providers can produce an empty list. An unrecognized modality is treated as no filter in the current implementation, rather than producing a validation error. Your client should validate its own filter choice before using the result.

Recognize metadata limits

Playground fields describe controls such as prompt, duration, aspect ratio, resolution, or image count. They do not expose every schema property. An absent seed control does not mean the provider rejects seed, and a control description is not a full representation of all cross-field or literal constraints.

The response also does not include a complete pricing function. Do not infer a quote from display order, a label, or an apparent model family. Cost depends on the parsed request and the selected adapter’s pricing implementation.

Likewise, the presence of audio, music, speech, or 3d in the recognized filter set does not mean those modalities currently have registered generation adapters. Discover actual returned entries instead of manufacturing choices from the query vocabulary.

Build a resilient selector

Cache discovery for a bounded application purpose and store the timestamp alongside any diagnostic snapshot. On submission, preserve the exact chosen model in the task record. If a previously saved model disappears from discovery, stop and request an explicit replacement rather than silently substituting another model.

Use the form metadata to assist editing, then validate against the selected model’s contract in your application. Show an actionable unknown-model response if the gateway rejects a stale identifier. Preserve the draft so the user can make a considered replacement.

Acceptance review

Check the unfiltered list, image filter, video filter, an empty supported modality, and an unrecognized filter using existing fixtures or local inspection. Confirm that your UI uses ids, handles empty arrays, and does not treat incomplete controls as exhaustive schemas.

Review default parameters, numeric constraints, and unknown request fields before letting a generated form construct production submissions.

Continue with models and parameters

• Flux API key: two paths, and what changes after you have one
• Flux API parameters: every accepted value and what it costs
• Flux aspect ratio options: what it accepts and what it rejects
• Browse all models and parameters guides