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_generation_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.

Models not listed ignore resolution. For video families (Seedance, Kling, P-Video, Gemini Omni) the resolution is part of the concrete variant model_id — pass the variant (e.g. seedance-2-fast-480p, 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 1.5 Pro – two modes (check generation_type before using images):

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

ByteDance Seedance 2 ships as two separate model families — seedance-2-fast (cheaper, faster) and seedance-2 (standard, higher quality). 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-720p-video-ref) — a bare family label returns a variant_required error listing the options. Resolutions are 480p or 720p (no 1080p). Duration is an integer 4–15 seconds. Supported aspect ratios: 1:1, 4:3, 3:4, 16:9, 9:16, 21:9, adaptive. Prompt max 2,500 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

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):

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, gemini-omni-video, p-video, kling-3-0-motion-control, kling-2-6-motion-control. Passing just the family label as model returns:

{
  "error": "variant_required",
  "family": "seedance-2-fast",
  "available_variants": [
    "seedance-2-fast-480p",
    "seedance-2-fast-720p",
    "seedance-2-fast-480p-video-ref",
    "seedance-2-fast-720p-video-ref"
  ],
  "hint": "Ask the user which variant they want — resolution, draft vs standard, or with/without reference video. Pull pricing from get_models."
}

No credits are deducted. Re-call generate_media with a concrete model_id from available_variants (or 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, Kling 2.5 image-to-video, 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, Seedance 1.5 Pro). 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 — no surcharge vs silent.

• 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.

#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.

#get_generation_status

Check the status of a media generation and get output URLs when done.

Parameters:

Response: Includes status (pending, queued, processing, completed, failed), progress, and when completed an outputs array with url, thumbnail_url, optimized_url, media_type, dimensions, etc.

#get_generation_estimate

Get a parameter-specific estimated processing time for a given model and options (no job is started). For a per-model estimated duration in one call, use get_models; each model includes estimated_time_seconds. Use get_generation_estimate when you need an estimate that depends on prompt length, duration, or other parameters.

Parameters:

Response: Estimated time (and optionally confidence/sample size) so you can set user expectations before calling generate_media.

#Model rules

• Text-to-image and text-to-video: Do not send source_media_urls (unless the model supports an optional reference image). Exception: seedance-1-5-pro in text-to-video mode accepts 0–1 optional images.
• 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. seedance-1-5-pro in image-to-video mode requires exactly 2 images (start + end frame). 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 — use sound only when supports_sound is true (Kling 2.6, Kling 3.0, Seedance 1.5 Pro). 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.