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, Sora, P-Video) the resolution is part of the concrete variant model_id — pass the variant (e.g. seedance-2-fast-480p, p-video-1080p), 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

Family-name disambiguation:

Some model families expose multiple concrete variants per resolution / quality / reference-video combo: seedance-2, seedance-2-fast, 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, Sora, Wan, Grok, Kling 2.5 image-to-video, Motion Control).
   • 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.

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