What changed in the API

This page is for people who already have a client. It lists what is new in release 3.7.0, which older names still work, and the changes that can alter the result of a request that you already send.

Two changes in behavior

  1. Image resolution and aspect_ratio now take effect. Before, the exchange dropped both fields. Now the exchange picks a pixel size that an offer declared, and it buys, prices and dispatches that size. The size can change the charge. If no declared size has the tier and the shape, the answer is 400 unsupported_parameter. If size disagrees with them, the answer is 400 conflicting_parameters. A client that sends only size does not change. See Image generation.
  2. A video job past the video job limit ends as expired. Before, it ended as failed. The limit is 10 minutes after dispatch by default. An expired job costs nothing, and the exchange sends the video.generation.expired callback. See Video generation.

A client that reads the status of a video must also handle two new values: cancelled and expired.

New in 3.7.0

A control works only when an offer declares it. If no offer did, the answer is 400 unsupported_parameter and param names the feature. See Errors.

Area New Page
Images resolution, aspect_ratio, seed, background, output_compression, stream with server-sent events Image generation
Chat image_config for images in a chat answer Image generation
Video aspect_ratio, resolution, seed, creativity, upscale_factor, previous_job_id, cancel, the states cancelled and expired, has_audio Video generation
Speech instructions, input as an array of turns, voice is optional Speech
Transcription diarize, keyterms, audio by https link Speech-to-text
Embeddings input_type Embeddings
References One input_references list with a role on every media endpoint Reference inputs
Rules Grouped exchange options, and cap_nanos Purchasing rules
Receipt *_nanos amounts, supplier_* amounts, new token names, usage.pricing Receipts
Model card modality, parameters descriptors, pricing, unit names Modalities

Older names that still work

The exchange reads the older name of a request field and maps it to the new name. Each response carries the older name next to the new one, with the same value. Send both with different values and the answer is 400 conflicting_parameters. New code should use the new names.

Older name New name
images, image, references on images; frame_images, input_reference on video; input_audio on transcription input_references
mime, mime_type, format on a reference media_type
mime_type on an image answer and its events media_type
Flat exchange fields, such as allowed_providers, ttft_ms, max_output_usd_per_mtok The groups candidates, rank, limits, privacy, cache and session
tokens_in, tokens_cached, tokens_cache_write, tokens_out in exchange.usage prompt_tokens, cached_tokens, cache_write_tokens, completion_tokens
max_tokens, min_input_rate, min_output_rate on a model card max_output_tokens, min_input_usd_per_mtok, min_output_usd_per_mtok
rate_per_image, rate_per_video_second and the other rate_* fields of an offer pricing, a list of prices

The flat exchange names are listed in Purchasing rules. cap_usd keeps its name. cap_nanos is the same cap as an integer of nano-USD. Send one of the two, or send both with the same value.

An older name that the endpoint did not read is still refused. For example, mask on POST /v1/images/edits gets 400, as before.

Check your client

  1. Read the status of a video with a switch that has a case for cancelled and expired.
  2. If you send resolution or aspect_ratio for an image, compare the size and the charge with your last results.
  3. Move the older names in the table to the new names when you next edit the code.
  4. Read the model card for parameters before you send a control. See Modalities.