generation API unknown fields: Distinguish ignored keys from invalid known values

Debugging generation API unknown fields starts with identifying where a field appears. A top-level property, a schema property, and a property inside extra follow different paths. Valid JSON alone tells you nothing about whether the intended option reached the provider.

Follow the route’s explicit object

Both public generation routes construct a fresh parameters object from selected body properties. They do not spread the complete request body into the job service. An application field such as campaign_id at the top level is not automatically saved as a provider parameter or forwarded to the model.

The image route selects prompt, aspect ratio aliases, n, seed, image input aliases, negative prompt aliases, and extra. It does not select resolution. Sending resolution beside prompt therefore does not make the image adapter use that value. This matters when a client shares a generic image and video request type.

The video route does select resolution and duration aliases. The selected provider then decides which values are valid. For example, Kling’s resolution is the literal 1080p, while Seedance accepts 720p and 1080p. A known property with a wrong value is a schema error, which differs from an unselected top-level property.

Classify the symptom

If a request succeeds but a custom field has no visible effect, first inspect your serialized body and the route mapping. Do not immediately conclude that the model ignored an instruction. The value may never have entered the provider parameters.

If the response reports INVALID_PARAM, examine the field named by the first schema issue. The job service validates before creating the reserved job. Correct that field and avoid a blind retry of the same payload. A camel case name in the error can refer to a snake case property from your original HTTP request.

Properties inside extra have another behavior. The schema accepts a record with unknown values, and adapters forward those properties after their standard mapping. Such a property is not validated as a supported model capability. It may be rejected upstream or collide with a mapped field.

Make client mistakes visible

Define an endpoint-specific allowlist in your application and report unexpected top-level keys before serialization. For a form submission, distinguish fields used for your local record from fields intended for the HTTP request. A local review_owner property should remain with the task record, not become extra merely to avoid losing it.

Prepare an offline example that intentionally misspells aspect_ratio. Your application should reject the misspelling instead of allowing the gateway to use a default ratio. This turns a silent editorial error into an actionable validation message.

Acceptance criteria

Review a missing optional field, an unexpected top-level key, a known invalid enum, and an unapproved extra property. The client should explain all four outcomes without contacting a paid model. Keep the original request available for diagnosis.

Use input validation, default parameters, and extra parameter overrides as separate references when designing these checks.

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