generation API extra parameters: Protect the validated request from upstream overrides

The generation API extra parameters object is an escape hatch with a consequential ordering rule. In the current providers, extra is spread after standard upstream fields. A property inside extra can therefore replace the value produced from a validated standard parameter. Treat this as part of the request contract when designing your own application boundary.

Locate the override

The Flux adapter builds prompt, aspect_ratio, num_images, seed, negative_prompt, and optionally image_url, then spreads extra. An extra object containing num_images can replace the value derived from n. Seedance similarly constructs duration from durationSec before spreading extra. Kling maps duration to a string, and Veo uses duration_seconds; the upstream key differs even though the public parameter is shared.

This ordering does not mean those override values are supported by the upstream service. The provider schema validates extra as a record of unknown values. It does not validate every upstream option or prove that the resulting combination is accepted. An object passing local validation can still produce an upstream error.

Preserve accounting assumptions

Pricing runs on parsed standard parameters before provider submission. For images it uses n, and for videos it uses the selected duration and resolution rules. If extra changes the upstream amount of work, the standard pricing input no longer fully describes what was sent. Avoid presenting such a request as a verified price for the overridden work.

Build an allowlist in your application that excludes keys colliding with mapped fields. Keep the list specific to the selected provider, because duration and duration_seconds are different collision targets. Do not rely on a generic list containing only the public spellings.

An example policy is to allow a reviewed vendor option only after recording its upstream name, acceptable JSON type, reason, and compatibility evidence. Reject an unknown option locally with a clear explanation. This policy belongs to your application; the gateway does not currently enforce that custom allowlist.

Review a proposed exception

Suppose a developer wants to add an upstream option to a campaign request. Ask for the exact serialized extra object and compare it with the adapter’s constructed keys. If it contains prompt, num_images, image_url, or a duration field, route the change for explicit contract review rather than accepting it as harmless metadata.

Keep experiment labels, reviewer names, and campaign identifiers outside extra. Otherwise they are forwarded upstream despite having no generation purpose. Store them with the application task record linked to the eventual job identifier.

Offline acceptance

Create local fixtures for no extra, an allowed noncolliding option, a colliding option, and an unexpected nested value. Inspect the expected merged upstream payload without submitting it. Acceptance requires that ordinary users cannot override priced fields and that approved exceptions remain visible in the audit record.

Retain the standard request and reviewed extra separately so investigators can reconstruct both validation and mapping. Continue with unknown fields, pricing snapshots, and the Flux parameter reference when defining the exception policy.

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