Schemas

Poll this with GET /generations/{id}/.

Media type of the job.

The model as you requested it.

Always processing — nothing is rendered yet.

Already debited. This is the final price, except for seedance25 edit/extend jobs where it is a hold that is partially refunded after delivery.

The model as you requested it.

processing until the provider returns. Terminal states are succeeded and failed; neither changes afterwards.

What was debited at submission. Never changes.

What has come back since: the full credits_charged once a failed generation is refunded, the undelivered seconds when a per-second video comes back at least 2 seconds short, or the unused part of a seedance25 edit/extend hold after settlement. credits_charged minus this is what the generation really cost.

Empty until succeeded. Item shape follows type:

• image and video — url and thumbnail. Video always returns exactly one item.
• music — two items, each with title, url, cover_image and duration.
• speech — one item with url.

Every URL is signed and expires 24 hours after it was minted.

Present only when status is failed.

Newest first. A generation whose record was removed is left out.

The page that was returned.

Whether a later page exists.

Signed URL of the rendered media.

Signed URL of a still preview.

Title the model chose, or the one you supplied in custom mode.

Signed URL of the mp3.

Signed URL of the generated cover art.

Track length in seconds.

Signed URL of the mp3.

Model id → capability object. Every entry carries name and pricing; the other keys describe the parameter surface and vary by model: aspect_ratios, durations, qualities, default_quality, model_levels, mode_model_levels, modes, defaults, sync_modes, output_formats, max_prompt_chars, max_input_images, image_input, video_input, audio_input, requires_video_input, requires_audio_input, has_audio and notes. The chatgpt-image-2.5-* models add levels, default_level and backgrounds, and their pricing adds held_credits_by_level (level → quality → aspect ratio) and held_credits_per_input_image; nano-banana-2-1 pricing adds credits_per_input_image and rounding. Music models add max_prompt_chars_simple_mode and max_style_chars; speech models add max_lines, min_characters, max_unique_voices, voices and languages.

Publicly reachable https:// image URLs. Hoosha media links are rejected with invalid_image_url; send those files through uploads. Repeat the field in multipart.

Upload ids from POST /uploads/. Each id is single-use and expires about 20 minutes after the upload. /images/ reads upload ids only from this field; an id sent as image1 is ignored.

Accepted as mode too; if both are sent, mode wins. Exceeding the model's input-image cap fails with too_many_images.

What to render, or how to edit the inputs. Over the model's max_prompt_chars fails with prompt_too_long.

Publicly reachable https:// image URLs. Hoosha media links are rejected with invalid_image_url; send those files through uploads. Repeat the field in multipart.

Upload ids from POST /uploads/. Each id is single-use and expires about 20 minutes after the upload. /images/ reads upload ids only from this field; an id sent as image1 is ignored.

Defaults to auto on chatgpt-image-2.0, the chatgpt-image-2.5-* models and nano-banana-2-1, and to 1:1 on chatgpt-image-1.5 and grok-imagine-2. Those models check the value: an unsupported ratio fails with invalid_aspect_ratio. The other models replace a ratio they cannot render instead of rejecting it: hoosha-v1 renders auto, nano-banana-2-pro and seedream4 render 1:1, and flux_kontext renders 16:9, which includes the 4:3 default. Stay within each model's aspect_ratios in GET /models/.

Quality-tiered models only (nano-banana-2-1, nano-banana-2-pro, chatgpt-image-2.0 and the chatgpt-image-2.5-* models) — it selects the price tier, and defaults to 1K on nano-banana-2-1. Ignored by every other model. Also accepted as resolution; quality wins if both are sent. Anything else fails with invalid_quality.

chatgpt-image-2.5-* models only; ignored by the other models. low and medium cost the table price. high, xhigh and max need a fixed aspect_ratio and 2K or 4K, hold the credits in the levels table and settle to the actual cost once the image is delivered. Anything else fails with invalid_level.

chatgpt-image-2.5-* models only, at every level; ignored by the other models. Anything else fails with invalid_background.

nano-banana-2-pro only; ignored by the other models. Anything else fails with invalid_output_format.

Accepted as mode too; if both are sent, mode wins. Exceeding the model's input-image cap fails with too_many_images.

What to render, or how to edit the inputs. Over the model's max_prompt_chars fails with prompt_too_long.

Publicly reachable https:// image URLs. Hoosha media links are rejected with invalid_image_url; send those files through uploads. Repeat the field in multipart.

Upload ids from POST /uploads/. Each id is single-use and expires about 20 minutes after the upload. /images/ reads upload ids only from this field; an id sent as image1 is ignored.

Defaults to auto on chatgpt-image-2.0, the chatgpt-image-2.5-* models and nano-banana-2-1, and to 1:1 on chatgpt-image-1.5 and grok-imagine-2. Those models check the value: an unsupported ratio fails with invalid_aspect_ratio. The other models replace a ratio they cannot render instead of rejecting it: hoosha-v1 renders auto, nano-banana-2-pro and seedream4 render 1:1, and flux_kontext renders 16:9, which includes the 4:3 default. Stay within each model's aspect_ratios in GET /models/.

Quality-tiered models only (nano-banana-2-1, nano-banana-2-pro, chatgpt-image-2.0 and the chatgpt-image-2.5-* models) — it selects the price tier, and defaults to 1K on nano-banana-2-1. Ignored by every other model. Also accepted as resolution; quality wins if both are sent. Anything else fails with invalid_quality.

chatgpt-image-2.5-* models only; ignored by the other models. low and medium cost the table price. high, xhigh and max need a fixed aspect_ratio and 2K or 4K, hold the credits in the levels table and settle to the actual cost once the image is delivered. Anything else fails with invalid_level.

chatgpt-image-2.5-* models only, at every level; ignored by the other models. Anything else fails with invalid_background.

nano-banana-2-pro only; ignored by the other models. Anything else fails with invalid_output_format.

First input image, sent as a file.

Second input image. Continue with image3, image4, … as the model allows.

Accepted as mode too; if both are sent, model wins. An unknown value fails with invalid_model.

Required for every model except kling-motion, lipsync and genjutsu. Over the model's max_prompt_chars the request is rejected.

Length in seconds, as a string, from the model's durations in GET /models/; anything else is rejected and an omitted value takes the model default. Send it as a string: a JSON number passes the check but the model then renders its default length. Ignored where the length comes from an input: kling-motion, lipsync, genjutsu, gemini-omni-video when video1 is sent, and seedance25 in seedance_mode: edit.

One of 480, 720, 1080, 4k, per model, from its qualities in GET /models/; anything else is rejected and an omitted value takes the model default. Send it as a string, as with duration. kling is 1080-only and lipsync takes only auto.

Per-model set from GET /models/. image makes the output follow the input image where supported (sent upstream as auto or adaptive). Anything outside the model's set is rejected; an omitted value takes the model default.

Selects the variant within a model family, and with it the price.

A value outside the model's set is rejected. Send it as a string: a JSON number such as 2.6 is not read and the default is used. lipsync at v2-pro needs a video input; v3 takes either one video or one image. genjutsu at lite takes a reference video of at most 15 s. seedance2 renders 1080 and 4k only at pro; asking for them at another level is rejected rather than quietly lowered.

veo3 only. Derived from the number of input images when omitted: none → text-to-video; one → first-frame-last-frame, with the image as the first frame; two or three → image-to-video, with the images as references. Send first-frame-last-frame explicitly to use two images as the first and last frame. image-to-video takes 1 to 3 images and first-frame-last-frame 1 or 2.

seedance2 and seedance25 only. Derived when omitted: no images → text-to-video; one image → image-to-video; two images → first-frame-last-frame on seedance2 but reference-to-video on seedance25; three or more images, or any video1/audio1 → reference-to-video.

reference-to-video is the multimodal scene and needs at least one image or video. Limits:

edit and extend are seedance25 only and need at least one input video. In edit the output follows the input footage, so duration, aspect ratio and mode come from it, and every input video must be at least 4 s; it holds twice the input seconds plus 3 s at the with-video rate. extend continues the footage and charges the input plus the requested duration. Both settle on delivery to the input plus the delivered seconds.

seedance2 and seedance25. The price is identical either way, so leaving it on never costs extra.

No longer has any effect. seedance2 text-to-video requests always ground the scene in a web lookup.

seedance25 only.

lipsync only. How a video and an audio of different lengths are matched: bounce plays the video back and forth, loop repeats it, cut_off trims the longer one, silence pads the audio with silence, and remap changes the video speed. The price follows the output length: the audio length, except the longer of the two with silence and the shorter with cut_off.

kling-motion. Which source sets the character's facing. image limits the reference video to 10 s.

kling-motion at model_level: 3.0 only. Which source provides the background.

Hosted input images, https:// only and not on Hoosha media hosts; they are handed to the provider as-is. They fill the lowest free image1…imageN slots: if you sent only image2, the first URL becomes image1. They count toward the model's image cap.

Input image: an upload id (/videos/ reads upload ids only from these positional fields, not from uploads), or a file part in multipart (png, jpg, jpeg, webp or gif, at most 10,000,000 bytes, not converted). Continue with image2, image3, …

How many images each model reads: seedance25 30, seedance2 9, genjutsu 8 (at least 1 required), grok-imagine 7, gemini-omni-video 7 (5 when video1 is sent), veo3 3, kling3 1, kling-motion exactly 1, lipsync 1 when no video1 is sent (ignored with one), runway and seedance only image1. On kling, image2 is the end frame. Only grok-imagine and genjutsu reject extra images with too_many_images; elsewhere images beyond the limit are dropped. For first-frame-last-frame, image1 is the first frame and image2 the last.

Reference video, as an upload id. Required by kling-motion (3–30 s), by genjutsu (5–30 s, 5–15 s on lite, at most 200 MB) and by lipsync at model_level: v2-pro; optional on v3, which falls back to image1. gemini-omni-video reads video1 only (at most 10 s and 100 MB). seedance25 reference scenes take up to video10 and seedance2 up to video3.

Reference audio, as an upload id. Required by lipsync, where its length (2–30 s, 2–15 s with an image) sets the bill and files over 10 MB are rejected. seedance25 reference scenes take up to audio10 and seedance2 up to audio3.

In simple mode, a description of the track (max 3,000 characters). In custom mode, the lyrics (max 5,000).

Optional. Anything outside the catalog fails with invalid_model.

false — describe the track in prompt and let the model handle the rest. true — prompt carries the lyrics and style and title take effect.

Genre and production direction. Custom mode only.

Custom mode only. Truncated to 79 UTF-16 units — an emoji costs two — and falls back to the prompt or style if omitted.

Render without vocals.

One line of dialogue. Inline tags such as [laughs] or [whispers] direct the delivery and are not spoken; a line left with no speakable text after tags and emoji are removed is rejected.

Voice id. Defaults to شایان (EkK5I93UQWFDigLMpZcX).

The lines, in order. At most 6 lines and 10 distinct voices, with a combined text length of 5–5,000 characters. That combined length is what you are billed on.

Optional. Anything outside the catalog fails with invalid_model.

0 creative, 0.5 natural, 1 stable. Accepted as a number or a string; anything other than these three values is rejected.

Empty string auto-detects. Otherwise one of the supported codes.