Media tools

Generate images and videos using 40+ AI models. Always call get_models first to see available models, costs, and whether a model needs an input image.

REST HTTP clients: the same limits are documented in one place in REST API model requirements (and returned per model from GET /v1/models).

#generate_media

Starts an image or video generation.

Parameters:

Example (text-to-image):

{
  "prompt": "A futuristic city at sunset with flying cars",
  "model": "nano-banana",
  "generation_type": "text-to-image",
  "aspect_ratio": "16:9",
  "quality": "pro"
}

Example (image-to-video, one input image required):

{
  "prompt": "Gentle motion and subtle movement",
  "model": "kling-2-6-image-to-video",
  "generation_type": "image-to-video",
  "source_media_urls": ["https://example.com/your-image.jpg"],
  "aspect_ratio": "16:9",
  "duration": "5s"
}

Response: Includes generation_id, status (e.g. pending), and often estimated_time_seconds and estimated_cost_credits. Poll with get_status until status is completed or failed.

Models that support duration:

For image-only models, duration is ignored.

Models that support negative_prompt:

All other models ignore negative_prompt.

Models that support quality (or equivalent):

For other models, quality is ignored.

<a id="resolution-tiers"></a>

Resolution tiers (the resolution parameter):

When to pick which tier (GPT Image 2):

• 1K — default. Use for social posts, thumbnails, concepting, in-app previews, anything ≤ 1024 × 1024. Cheapest; no aspect-ratio gotchas.
• 2K — use when the client needs a crisp web hero, newsletter cover, in-product illustration at retina density. Must pick a directional aspect (landscape or portrait).
• 4K — use for print, out-of-home, banners, or any case the user explicitly asks for the highest output size. Confirm the aspect with the user first; the pill 1:1 / auto won't work.

Flare vs Sunburst (GPT Image 2.5):

• gpt-image-2-5-flare is the fast lane. Default choice for exploration, prompt iteration and bulk generation.
• gpt-image-2-5-sunburst is the quality lane. Slower, cleaner detail and steadier typography. Use for final renders and 4K print.
• Both lanes take the same parameters, the same 16 reference images, the same 20,000 character prompt and the same 13 aspect ratios, and cost the same credits at every resolution tier.
• Neither lane supports 4:5. Use nano-banana-2 when a placement requires it.

Models not listed ignore resolution. For video families (Seedance, Kling, Veo, P-Video, FLUX 3, Gemini Omni) the resolution is part of the concrete variant model_id. Pass the variant (e.g. seedance-2-fast-480p, veo3-1-fast-text-to-video-1080p, p-video-1080p, gemini-omni-video-1080p-6s), not this param.

Prompt character limits:

Some models enforce a maximum prompt length. Exceeding it may return an error or truncation.

Others may have no documented limit or use server defaults.

Input file (image and video) limits:

For image-to-video and image-to-image, source_media_urls is a list of URLs. Most models accept images only (JPEG, PNG, WebP, typically 10 MB max per file). Some models also accept video inputs; when they do, format and size limits apply (e.g. MP4, max duration).

Use get_models to confirm input_media_types and capabilities for a given model. See Account tools for model list and pricing.

Kling 3.0 – elements (optional):

Elements let you reference images or videos in your prompt using @element_name. Pass kling_elements as an array of objects with name, description, and either element_input_urls (2–4 image URLs) or element_input_video_urls (1 video URL). Reference images for elements come from each element’s element_input_urls; main image_urls may be empty for text-to-video or hold optional start/end frames for image-to-video. Each element requires a title (name) and description. Image elements: JPG/PNG, min 300×300px, max 10MB each. Video elements: MP4/MOV, max 50MB.

Seedance 2 – two tiers, two modes, mixed references:

ByteDance Seedance 2 ships as three separate model families: seedance-2-fast (cheaper, faster), seedance-2 (standard, higher quality), and seedance-2-mini (cheapest, ~50% under Fast, 480p/720p only). Each family exposes concrete variant model_ids per resolution and reference-video combo; pass the full variant (e.g. seedance-2-fast-480p, seedance-2-mini-720p, seedance-2-720p-video-ref). A bare family label returns a variant_required error listing the options. Standard covers 480p, 720p, 1080p and 4K (variant ids seedance-2-480p / -720p / -1080p / -4k, each also with a -video-ref form); Fast and Mini cover 480p and 720p only. Duration is an integer 4 to 15 seconds. Supported aspect ratios: 1:1, 4:3, 3:4, 16:9, 9:16, 21:9, adaptive. Prompt max 4,000 characters. Audio is a free toggle via generate_audio (defaults to true). Unlike Kling 3.0, there is no surcharge for audio.

Put every reference URL (images, videos, audio) into source_media_urls. The backend classifies each URL by file extension — .jpg / .png / .webp → image, .mp4 / .mov / .webm → video, .mp3 / .wav / .m4a → audio — and routes it to the correct bucket automatically.

Billing (two paths):

• Without a reference video: credits = output_seconds × base_credits_per_second
• With a reference video (upstream provider path): credits = (ref_video_seconds + output_seconds) × base_credits_per_second, where ref_video_seconds is the sum of all reference video durations (capped at 15s per request).

Live per-second rates (pulled from the ai_models_config catalog — always current):

MCP / REST API note: the backend cannot probe remote video durations from a URL, so reference-video requests from the MCP and REST API are billed the pessimistic worst case of 15s of reference video. The web UI probes each video locally and bills the exact sum. For cost-sensitive workflows with short reference videos, prefer the web UI.

Hard limits (enforced with 400 errors):

• More than 3 videos → too_many_videos
• More than 3 audios → too_many_audios
• More than 9 images → too_many_images
• Combined reference video duration > 15s → rejected
• Combined reference audio duration > 15s → rejected
• Any single reference video or audio file longer than 15s → rejected

<a id="seedance-2-5"></a>

Seedance 2.5: long single shots and heavy references:

Seedance 2.5 is the newest Seedance generation and a separate model from the Seedance 2.0 family above, with its own rules. Pick it for a long single-shot clip (up to 30 seconds in one generation, no stitching), for heavy multi-reference work, or when the user wants the most recent model. Pick a 2.0 tier when they need 4K or the lowest per-second rate.

• Variant ids: seedance-2-5-480p, seedance-2-5-720p, seedance-2-5-1080p, and the same three with -video-ref for requests carrying a reference video. A bare seedance-2-5 returns variant_required. No 4K on 2.5.
• Duration: integer 4 to 30 seconds. Aspect ratios: 1:1, 4:3, 3:4, 16:9, 9:16, 21:9, adaptive. Prompt: up to 10,000 characters.
• Text-to-video: up to 30 images, 10 videos and 10 audio clips, all optional. Put every URL in source_media_urls; each is classified by file extension. Refer to them in the prompt as @Image 1, @Video 1, @Audio 1, numbered by order within each kind.
• Image-to-video: 1 image (first frame) or 2 (first + last), plus up to 10 audio clips. The output always takes the first frame's aspect ratio, so aspect_ratio is ignored, and no other reference images or videos are accepted. Unlike Seedance 2.0, this is never silently rerouted to text-to-video. To lock a first frame and keep extra references, use text-to-video and name the frame in the prompt.
• Audio: on by default and free; sound: false costs the same and only drops the track.
• Billing: per second of output without a reference video. With a reference video the provider also counts input seconds, with a floor of two thirds of the output length, and because the MCP server cannot measure a remote clip it bills the worst case of 30 reference seconds. Always quote with estimate first.

Draft mode (preview first, pay for 1080p once the shot is right):

1. Render a draft with model: "seedance-2-5-480p" (or bare seedance-2-5) and quality: "draft". It is a 480p preview billed like a normal 480p render. quality: "draft" on a 720p or 1080p id is rejected.
2. When the draft is completed, call generate_media again with draft_generation_id: "<the draft's generation_id>". Prompt and model are ignored in that call: the final reuses the draft's prompt, references, duration and aspect ratio, renders at 1080p and bills on the seedance-2-5-1080p row (or -1080p-video-ref). A draft can be finalized for 7 days, and finalizing the same draft twice returns the existing final without a second charge.

<a id="flux-3"></a>

FLUX 3: video with synchronized audio:

FLUX 3 renders one clip with synchronized audio (ambient sound, speech, effects) from a single prompt. There is no mode parameter: the mode comes from what you put in source_media_urls (see the input limits table above).

• Model ids: pass the bare flux-3 and the row is picked for you from quality (720p default, 1080p, 720p-draft or draft) plus whether a video is attached. You can also pass a concrete id: flux-3-720p, flux-3-1080p, flux-3-720p-draft for text and image input, flux-3-v2v-720p, flux-3-v2v-1080p, flux-3-v2v-720p-draft for continuing a video. A request carrying a video always bills on a flux-3-v2v-* row, whatever id you passed.
• Continuation costs more. The -v2v- rows are separate, dearer rows. Read each rate from get_models or estimate, never assume.
• Duration: integer 5 to 20 seconds, required. Pass an explicit duration for storyboards too.
• Aspect ratios: auto (default), 21:9, 2:1, 16:9, 4:3, 1:1, 3:4, 9:16.
• Audio: on by default; sound: false costs the same and only drops the track.

<a id="kling-3-0-omni"></a>

Kling 3.0 Omni: Transform, Frames and References:

Kling 3.0 Omni is one model with three lanes, and the variant id picks the lane. There is no text-to-video: every lane needs media in source_media_urls. Storyboards and Kling 3.0 elements are not available here.

All lanes bill per second at their own rates, and Frames is cheaper than Transform. Read the exact rate from get_models or estimate.

<a id="kling-4-0"></a>

Kling 4.0:

Kling 4.0 is one model for text-to-video and reference-to-video. Send no media for a clip from the prompt alone, or attach up to 10 reference images and up to 5 reference videos (3 to 30 seconds each, 30 seconds combined) in any mix. Output runs 3 to 30 seconds at 720p or 1080p, with aspect_ratio set to auto, 16:9, 9:16, 1:1 or 21:9. Left unset, it is auto when references are attached and 16:9 when they are not.

Point at your files in the prompt with @image_1, @image_2 and @video_1, @video_2, numbered in the order you send them. A mention that does not match an attached file (for example @image_3 with two images) is rejected before any credits are taken. You can also pass named elements (a subject described by 2 or more images, or by one video) and up to 3 voices (5 to 30 second samples), and mention each in the prompt as @name; only the ones the prompt mentions are sent. A video element is video input: it moves the job onto the -video row and its seconds count with the reference videos. Image elements and voices add no cost.

Inputs: pass images and videos in source_media_urls, or split them across reference_image_urls and reference_video_urls. Videos must be MP4 or MOV and must be uploaded to Kubeez first (get_upload_url on MCP, POST /v1/upload/media on REST). A video linked from another site is refused with clip_not_uploaded before any credits are taken, because each video is billed on the length Kubeez measures. Keep the videos' own audio with keep_original_sound: true. A bare kling-4-0 returns variant_required; pass one of the four ids below.

The -video rows have a lower per-second rate because the clip length is billed as well. Example: 10s out with a 5s video bills 20 seconds; with a 15s video it bills 25. Several videos are added together.

Audio: without a reference video the clip always comes with generated sound. With one, the soundtrack is generated unless you ask to keep the original audio of your videos.

<a id="omnihuman-2-0"></a>

OmniHuman 2.0:

OmniHuman 2.0 makes a portrait talk or sing. Send one image of a person and one audio file (speech or a song), and you get a lip-synced video of that person, 720p, exactly as long as the audio. There is no duration, resolution or aspect ratio to set. The prompt is optional (up to 300 characters) and steers the scene, the person's movement and the camera.

The audio must be MP3 or WAV, under 15 MB and 4 to 300 seconds long, and it must be uploaded to Kubeez first (get_upload_url on MCP, POST /v1/upload/media on REST). Kubeez measures the audio itself and bills on that length: whole seconds, rounded up, with a small allowance so a file that reads 5.02 seconds is billed as 5. If the audio cannot be measured at that moment, the request is refused before any credits are taken; try again in a minute.

<a id="veo-3-1"></a>

Veo 3.1 model ids:

Veo 3.1 has no single family id: veo3-1, veo3-1-fast and veo3-1-lite on their own are not callable, so always pass a full id. The id is built from three parts:

Examples: veo3-1-text-to-video, veo3-1-fast-first-and-last-frames-1080p, veo3-1-lite-reference-to-video-4k. Every clip is a fixed 8 seconds with audio included, in 16:9 or 9:16. Each tier, mode and resolution is its own priced row in get_models. To continue a finished clip, use generation_type: "extend" with source_task_id and extend_model (lite, fast or quality).

Gemini Omni Video — Google's multi-modal video model:

Gemini Omni Video produces video output with built-in audio (29 named voices) and accepts multi-modal inputs (text, image references, an optional single video reference). The model ships as 15 concrete variants — pick the one that matches your target resolution and duration. 720p and 1080p are priced identically; 4K is a separate price tier.

Variant ids (pass to generate_media as model):

Video-ref variants take their output duration from the trimmed source clip (first 10s used; no trim parameters exposed). Duration variants accept 1–7 image references; video-ref variants accept 1 source clip (consumes 2 slots) + up to 5 image references.

Pricing is flat-per-task. Live rates (720p and 1080p share each row — Google bills them identically):

#Gemini Omni 1.1 Flash

gemini-omni-flash-* is the 1.1 release of the same family, with its own edge function and its own pricing rows. It reads the same image, video and character references and uses the same 29-voice catalog. What it adds:

• a 360p tier. Unlike 1.0, every resolution has its own row here, so 360p is both the fastest render and the cheapest, and 1080p costs more than 720p
• a first and last frame mode: pass the opening still in source_media_urls and the closing still as last_frame_url. This mode is exclusive — it cannot be combined with extra reference images, a reference video or character_ids, and passing them together returns variant_mismatch.

Variant ids (pass to generate_media as model):

Parameters specific to Gemini Omni:

Source media (source_media_urls): 7 reference slots total. A single video reference consumes 2 slots; each character_id consumes 1 slot; images fill the rest. Maximum 1 video per request; passing a video URL requires a -video-ref variant (a duration variant + video returns variant_mismatch). The driving clip window defaults to the first 10 seconds; override with video_trim_start_s / video_trim_end_s. Audio file URLs are not accepted (returns unsupported_audio_url); use voice_id instead.

Companion tools (use these alongside Gemini Omni generations):

Example request (1080p, 6s, vertical, reusing a saved character + chosen voice):

{
  "model": "gemini-omni-video-1080p-6s",
  "prompt": "A barista pulls a perfect espresso shot, narrates the process",
  "aspect_ratio": "9:16",
  "voice_id": "kore",
  "character_ids": ["char_4f2a9b7c"],
  "source_media_urls": ["https://media.kubeez.com/cafe-shot.jpg"]
}

Family-name disambiguation:

Some model families expose multiple concrete variants per resolution / quality / reference-video combo: seedance-2, seedance-2-fast, seedance-2-mini, seedance-2-5, gemini-omni-video, gemini-omni-flash, kling-3-0-omni, kling-3-0-turbo, kling-3-0-motion-control, kling-2-6-motion-control, wan-2-7, wan-3-0, wan-3-0-prime, grok-imagine-video-1-5-preview. Passing just the family label as model returns the error below. Two families are exceptions and accept their bare id: p-video and flux-3 pick the row from quality (and, for FLUX 3, from whether a video is attached), and bare seedance-2-5 with quality: "draft" maps to seedance-2-5-480p. Veo 3.1 has no family label at all, see Veo 3.1 model ids.

{
  "error": "variant_required",
  "family": "seedance-2-fast",
  "available_variants": [
    "seedance-2-fast-480p",
    "seedance-2-fast-720p"
  ],
  "recommended_variant": "seedance-2-fast-720p",
  "hint": "Adopt recommended_variant and continue: the cost (and thus the resolution/price trade-off) is confirmed on the plan card, so a separate variant question is usually unnecessary. Ask only when the user signalled they care about price/quality. available_variants is already filtered to the input modality (the -video-ref variants appear only when a reference video is attached)."
}

No credits are deducted. available_variants is filtered to your input modality and recommended_variant names the default to use. Best practice: skip the round-trip by passing a concrete model_id (e.g. seedance-2-fast-720p) on the first call instead of the bare family. Re-call generate_media with the concrete id from recommended_variant / available_variants (or any id from get_models).

Video audio (two different concepts):

1. capabilities.video_audio in get_models — how to know if the output has sound:
   • included: The model’s output normally includes an audio track without using a sound parameter (e.g. Veo, Wan, Grok, Motion Control, Gemini Omni Video — the latter exposes a voice_id parameter to pick from 29 built-in voices).
   • toggle_via_sound_param — Generated audio is turned on/off with sound: true / false (Kling 2.6, Kling 3.0). Pricing may differ for audio vs silent. Kling 3.0 routes sound: true to dedicated -audio rows in the catalog — you keep using kling-3-0-std / kling-3-0-pro as the model id and just toggle sound, the server picks the right priced row. Live rates:

Motion Control per-second rates (Kling 3.0 and Kling 2.6):

(Motion-control rates are shown as one block since the two families share the same pricing shape: 720p and 1080p variants.) Seedance 2 also exposes a sound toggle (via its own generate_audio flag, default true) but audio is free, with no surcharge vs silent. Seedance 2.5 and FLUX 3 toggle through sound too, also free. Kling 3.0 Omni Frames and References price audio through their -audio ids.

• always_on_flat_rate: audio is always produced and the price does not change with it (kling-3-0-4k). The sound param is accepted but has no effect on cost.
• silent — No generated audio (Seedance 1.0 / v1-pro-fast-i2v only).

2. supports_sound — only means the API accepts a sound toggle for that model. It does not mean other models are silent; most video models use video_audio: included instead.

Image-only models ignore sound.

#Upscale

Re-renders one existing image at a higher resolution with sharper detail, keeping its composition, colours and content. Call generate_media with upscale-1k, upscale-2k or upscale-4k and the image in source_media_urls. prompt is required by the schema but ignored, and so are aspect_ratio and negative_prompt. The output is a PNG.

• Input: exactly one public .jpg / .jpeg / .png / .webp URL. An earlier generation output URL works directly; for a local file call get_upload_url(model_id="upscale-2k") first.
• Tier: pick it with the model id, or pass model: "upscale" with resolution: "1K", "2K" or "4K".
• Billing: flat per image, one price per tier. Call estimate for the exact price and confirm with the user first.
• Where: MCP only for now. The REST API does not run upscale yet.

To change what is in the image rather than its resolution, use an image-to-image model.

#REST API: URLs for local or browser files

If you use the HTTP API (POST /v1/generate/media) and your inputs are files on disk or selected in the browser—not already public URLs—upload each file first with POST /v1/upload/media. Pass the returned urls values as source_media_urls.

<a id="trim_video"></a>

#trim_video

Cut a window out of any publicly-accessible video URL and host the trimmed clip. Kubeez handles the trim server-side and returns a public url you can pass straight into generate_media as a source_media_urls value.

When to use this tool:

• The user's source video is longer than a model's reference-clip limit and you want the result to be deterministic instead of relying on provider-side trim hints.
• You want to use a specific window of a longer asset (e.g. "use seconds 5–12 of this take, not the first 10").
• You're chaining multiple generations and want a single canonical trimmed URL to reuse across calls.

Per-model reference-clip caps (skip the trim when the source already fits):

Parameters:

Returns: { url, size_bytes, duration_s, start_s, end_s, elapsed_s }. The url is a Kubeez-hosted public link pointing at the media-inputs Supabase storage bucket, safe to use as a source_media_urls value. Trimmed clips live alongside user-uploaded inputs and share the same weekly auto-cleanup — treat them as ephemeral, not as a permanent asset.

Typical workflow (Gemini Omni Video with a long user source):

1. get_upload_url(model_id="gemini-omni-video-1080p-video-ref")
       → presigned upload page
2. (user uploads their 25s clip via the link)
3. get_upload_session(token) → { media_urls: ["https://.../source.mp4"] }
4. trim_video(source_url=media_urls[0], start_s=5, end_s=15)
       → { url: "https://.../trims/<uuid>.mp4", duration_s: 10 }
5. generate_media(
       model="gemini-omni-video-1080p-video-ref",
       prompt="...",
       source_media_urls=[<trimmed url>]
   )

Standalone trim (source URL already public — no upload step needed):

trim_video(source_url="https://media.kubeez.com/<asset>.mp4", start_s=0, end_s=8)
       → { url, duration_s: 8 }
generate_media(model="kling-3-0-motion-control-1080p", source_media_urls=[<image>, <trimmed url>], ...)

Errors:

Example request:

{
  "source_url": "https://media.kubeez.com/u123/uploads/long-take.mp4",
  "start_s": 5.2,
  "end_s": 14.7
}

Example response:

{
  "url": "https://<project>.supabase.co/storage/v1/object/public/media-inputs/u123/trims/abc.mp4",
  "size_bytes": 1245678,
  "duration_s": 9.5,
  "start_s": 5.2,
  "end_s": 14.7,
  "elapsed_s": 1.83
}

Frame accuracy: -c copy snaps the actual start to the nearest preceding keyframe (≤ 1 GOP shift, typically ≤ 1s). This matches the web UI's native MP4 stream-copy behavior. For frame-accurate cuts, re-encode the source first — the tradeoff is a slower, lossy operation we deliberately avoid here.

Don't keep the output: the URL points at the media-inputs bucket which is cleared weekly. If you need the trimmed clip to outlive the next generation, use manage_library(kind="asset", action="add", ...) to copy it into the user's permanent Asset Library.

#remove_background

Cut the subject out of an image. The output is a PNG with a real transparent background (alpha), which is why you never prompt an image model for a "transparent background" — image models bake a white or checkerboard fill into the pixels instead. Takes no prompt: it is an operation on an existing image, not a generate_media model.

Billed flat per image. Call estimate with model: "remove-background" for the exact price and confirm with the user first.

Parameters:

Response: { generation_id, status: "pending" }. Poll get_status until completed; the output URL is the cutout PNG.

#regenerate

Re-run a past media generation with optional overrides. The original row's prompt, model, aspect ratio, source_media_urls and duration are reused unless you override them. Media only — music, separation and dialogue have to call their original tool again.

Cost is identical to a fresh generate_media, so confirm with the user before calling, especially for per-duration video models.

Parameters:

#get_status

Poll any job by id — media generation, music generation, or audio separation. The server auto-dispatches on the id, so one tool covers all three.

Parameters:

Response: kind (what the id resolved to), status (pending, queued, processing, completed, failed), progress, and depending on kind an outputs array (url, thumbnail_url, optimized_url, media_type, dimensions), a songs array, or vocals_url + instrumental_url. error_message on failure.

#estimate

Preview both the credit cost and the processing time of a generation without deducting anything. No job is started. Mandatory for every per-duration model: quote the number to the user and wait for a go-ahead, because a completed generation cannot be refunded.

Parameters:

Response: credits (estimated_credits, mode, rate_per_second, explanation, pessimistic) and time (estimated_seconds, source). When credits.pessimistic is true the real billed amount may be lower — have the user re-upload through get_upload_url so duration gets probed, then estimate again.

#Model rules

• Text-to-image and text-to-video: Do not send source_media_urls (unless the model supports an optional reference image).
• Image-to-video and image-to-image: Send image (and when supported, video) URL(s) in source_media_urls. Most models need images only; some (e.g. Kling 2.6 Motion Control) require 1 image + 1 video. Respect each model’s input limits above.
• Video audio: Use capabilities.video_audio from get_models. included: audio is part of typical output without a sound parameter (e.g. Veo, Wan, Grok). toggle_via_sound_param: sound defaults to true; pass false only when the user asks for a silent clip (Kling 2.6, Kling 3.0, Seedance 2.5, FLUX 3, Kling 3.0 Omni). always_on_flat_rate: audio always on at one price (kling-3-0-4k). silent: no generated audio (Seedance 1.0 only). Do not infer “no audio” from supports_sound: false alone.
• Use get_models to see which models support which generation types, input_media_types (e.g. image, video), and required input counts.

See Limitations for rate limits and credits. For a single table of API defaults (prompt max, inputs, duration, flags), see REST API model requirements.