generation API snake case parameters: Trace alias precedence before serializing

A request that contains both naming styles can be valid JSON and still express two different intentions. The generation API snake case parameters contract resolves this conflict with nullish coalescing. For mapped aliases, the snake case value wins when it is neither null nor missing. This is a routing rule, not an instruction for the model.

Follow a conflicting value

Consider a video request with duration_sec equal to 5 and durationSec equal to 10. The route constructs durationSec from duration_sec ?? durationSec, so the provider receives 5. If duration_sec is null, the camel case value becomes the candidate. If duration_sec is zero, zero wins and then fails the selected video schema. Nullish coalescing does not test whether a value is valid or truthy.

The same pattern applies to aspect_ratio and aspectRatio, image_inputs and imageInputs, and negative_prompt and negativePrompt. The image endpoint performs those mappings but does not include durationSec or resolution in its constructed parameters. Do not assume that any property accepted by another endpoint is forwarded here.

Establish one client convention

Choose snake case at the public HTTP boundary and camel case inside your application. Reject a payload containing both spellings before sending it, even when their values appear equal. This makes request review easier and prevents later middleware from changing only one copy.

For example, a local request builder can first collect known fields, reject duplicate aliases, remove properties whose values are undefined, and then serialize. Keep null values visible until your own policy decides whether they mean omission or an input error. Silently deleting every falsy value would also delete a legitimate seed of zero.

Use a fixture with aspect_ratio set to an invalid empty string and aspectRatio set to a valid ratio. The empty string wins because it is not null. Expect schema validation to reject it rather than falling back to the valid alias. This single fixture catches the common assumption that precedence means choosing the first acceptable value.

Separate normalization from validation

The job service finds the provider and runs its schema after route normalization. A validation error can therefore report the camel case field name even when the original request used snake case. Preserve both the submitted body and your normalized expectation in development fixtures so that an error about aspectRatio remains understandable.

Normalization success does not establish upstream compatibility. The extra object is spread later by the provider and can override mapped upstream fields. Keep that separate from alias handling, and do not use extra to resolve an ambiguous request.

Acceptance evidence

A useful offline table includes missing aliases, one alias, two conflicting aliases, null on the preferred alias, and an invalid non-null preferred value. Record the expected candidate and the expected validation result separately. No paid generation is needed to review this contract.

Approve the builder when every fixture produces one unambiguous canonical property, preserves seed zero, and identifies the chosen endpoint. Review parameter validation, null handling, and extra overrides before reusing the builder across models.

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