Skip to main content
POST
Unified Tasks API
The /v1/tasks endpoint provides a unified interface for all AI generation models (video, image, audio).
This is the unified API for all AI generation models. Use this endpoint for all integrations.

Create Task

POST /v1/tasks Creates a new generation task for any supported model.

Request

Request Parameters

string
required
Model identifier in provider/model-name format. See Available Models below.
object
required
Model-specific input parameters. See Input Parameters for details.
string
Optional webhook URL. When provided, the API sends a POST request to this URL when the task completes or fails. See Webhooks & Callbacks for payload formats and details.
boolean
Optional. When set to true, the request is validated and the cost is calculated without actually creating a task or deducting from your balance. Useful for previewing the price of a request before committing.

Response

Dry Run

To check the cost of a request without creating a task or deducting from your balance, set dry_run to true:

Get Task Status

GET /v1/tasks/:task_id Retrieves the status and output of a task.

Request

Path Parameters

string
required
The unique task ID returned from the create task endpoint

Response (Processing)

Response (Completed)


List Tasks

GET /v1/tasks Lists your tasks, newest first, with pagination and filters.

Request

Query Parameters

integer
1-indexed page number. Default 1.
integer
Results per page: 10, 25, 50, or 100. Default 25. Other values fall back to 25.
string
Filter by task status: processing, completed, or failed.
string
Filter by exact model ID, e.g. google/veo-3.1-fast.
string
Comma-separated list of model categories: llm, video, image, audio. Example: category=video,image.
string
Comma-separated list of provider slugs (the part before / in the model ID), e.g. provider=elevenlabs,google.
integer
Unix timestamp in seconds. Only tasks created at or after this moment.
integer
Unix timestamp in seconds. Only tasks created at or before this moment. Must be greater than or equal to created_after when both are set.

Response

data is the array of tasks; pagination sits alongside it at the top level.

Task Fields

string
Unique task identifier.
string
Model ID the task ran on, e.g. google/veo-3.1-fast.
string
Model category: audio, image, video, or llm. null if the model is no longer in the catalog.
string
processing, completed, or failed.
number
Amount charged for the task in USD.
integer
Unix timestamp (seconds) when the task was created.
object
The stored request input, as submitted.
object
The task output (e.g. video_url, image_url, audio_url). null while processing.
string
The webhook URL provided at creation, or null.
array
Webhook delivery attempt log: each entry has sent_at (Unix epoch seconds), status, status_text. Up to 5 automatic attempts; manual redeliveries from the dashboard extend the log up to a shared cap of 10 total. null if no callback was configured.
string
Upstream failure text. Only present when status is failed.
object
Structured provider diagnostics when available on a failed task. For Grok image edits, this includes per-attempt quota checks, stream event summaries, upstream identifiers, failure classifications, and the complete upstream response stream. Treat this field as sensitive operational data.

Available Models

Video Generation

Image Generation

ByteDance SeeDream models (bytedance/seedream-5.0-lite, bytedance/seedream-4.5, bytedance/seedream-4.0) accept max_sequential_images (integer, default 1)—the maximum number of sequential images the model may generate. This is a ceiling, not a guarantee; the model decides how many to produce (1 up to that limit). Omit or set to 1 for a single image. Sequential images are billed per image.

Audio Generation


Model Parameters

All tasks support callback_url (outside the input object) for webhook notifications. See Webhooks & Callbacks for full payload formats and best practices.

Google Veo 3.1

Generate

Models: google/veo-3.1-fast, google/veo-3.1-quality, google/veo-3.1-lite, google/veo-3.1-lite-relaxed Veo supports text-to-video, first-frame, first-and-last-frame, and reference-to-video workflows. Frame mode and reference mode are mutually exclusive. Character items must be objects with image_urls, plus optional name and description. image_url and plain string character entries are not supported. Rejected combinations: end_image_url without start_image_url; frame fields with reference fields; reference_characters on google/veo-3.1-quality; any image or character reference with duration other than 8; more than 3 total expanded image URLs; empty character image_urls; character image_url; plain string character entries.

Extend

Model: google/veo-3.1-extend Extend a previously generated video. Aspect ratio is inherited from the source task.

Upscale

Model: google/veo-3.1-upscale Upscale a completed video to a higher resolution.

Google Gemini Omni Flash Video

Model: google/gemini-omni-flash-video Generate 4, 6, 8, or 10 second clips in text-to-video, start-frame, or reference-to-video mode. Start/end frame support is now available. For now, only start frame control (start_image_url) is available — end frame support is not yet available on Google’s end, but it’s coming in an upcoming Google update.

Google Gemini Omni Flash Video Edit

Model: google/gemini-omni-flash-video-edit Edit an existing uploaded video. Provide exactly one source video URL in reference_video_urls. Limits: one video reference, up to 3 character references, up to 7 total video + image + character references, uploaded source video up to 1 GB and up to 30 seconds. Rejected combinations: task_id; missing, empty, or multiple reference_video_urls; end_frame lower than start_frame; more than 7 total references; empty character image_urls; character image_url; plain string character entries.

Minimax Hailuo

Models: hailuo/minimax-2.0, hailuo/minimax-2.3, hailuo/minimax-2.3-fast All three are image-to-video models. MiniMax 2.0 accepts a start frame, an end frame, or both. MiniMax 2.3 and 2.3 Fast require a start frame and do not support an end frame. The aspect ratio follows the input frame. These models do not accept aspect_ratio. MiniMax 2.3 and 2.3 Fast also do not accept prompt_optimizer.

MiniMax Hailuo H3

Model: hailuo/minimax-h3 MiniMax H3 supports text-to-video, start/end-frame control, and omni-reference generation with 1-12 images. Text-to-video defaults to 16:9 and does not accept auto. Frame mode requires aspect_ratio to be omitted because Hailuo follows the input frame. Omni-reference mode defaults to auto and also accepts fixed ratios. MiniMax H3 does not accept reference videos, reference audio, seed, or prompt_optimizer.

Kling 3.0 Omni Video

Model: kuaishou/kling-3.0-omni-video

Kling O1 Video

Model: kuaishou/kling-o1-video Same parameters as Omni 3.0 but does not support multi_shots or native_audio. Max duration 10s.

Kling 3.0 Omni Video Edit

Model: kuaishou/kling-3.0-omni-video-edit Duration is locked to the input video length.

Kling O1 Video Edit

Model: kuaishou/kling-o1-video-edit Same parameters as Omni 3.0 video edit but does not support elements.

Kling 3.0 Video

Model: kuaishou/kling-3.0-video

Kling 3.0 Turbo Video

Model: kuaishou/kling-3.0-turbo-video Faster variant of Kling 3.0. Text-to-video or optional start-frame image-to-video only. No native audio, multi-shot, end frame, or 4K.

Kling 2.6 Video

Model: kuaishou/kling-2.6-video

Kling 2.5 Turbo Video

Model: kuaishou/kling-2.5-turbo-video

Kling 2.1 Video

Model: kuaishou/kling-2.1-video Image-to-video only.

Kling 2.1 Master Video

Model: kuaishou/kling-2.1-master-video Pro-only. No end frame support.

Kling 3.0 Motion Control

Model: kuaishou/kling-3.0-motion-control

Kling 2.6 Motion Control

Model: kuaishou/kling-2.6-motion-control

Grok Imagine Video

Model: xai/grok-imagine-video audio: true works with text-to-video and visual-reference requests. A preset voice requires a visual input and cannot be combined with audio: false. Transient media references are deleted automatically after success or failure; a supplied character_id is retained.

Grok Imagine Video Extend

Model: xai/grok-imagine-video-extend Extend a previously generated video via HTTP streaming. Only accepts task IDs from xai/grok-imagine-video (the speed-optimized 1.5 build) — xai/grok-imagine-1.5-video task IDs are not supported. Two mutually exclusive modes:

GPT Image

Models: openai/gpt-image-2

Nano Banana

Models: google/nano-banana, google/nano-banana-pro

Flux.2

Models: black-forest-labs/flux.2-pro, black-forest-labs/flux.2-flex, black-forest-labs/flux.2-max

Qwen Image 3.0 Pro

Model: alibaba/qwen-image-3.0-pro Highest-quality Qwen Image 3.0 model for complex layouts, accurate text rendering, photorealistic detail, and image editing. Automatically switches between text-to-image and editing based on whether image_urls is provided. resolution and aspect_ratio are independent: resolution selects the pixel tier and aspect ratio selects the output shape. The 1K tier ranges from 768 to 1344 pixels per side for non-square outputs; the 2K tier ranges from 1536 to 2688 pixels per side. Qwen Image 3.0 Pro output pricing varies by resolution, and input/reference images are billed separately.

Qwen Image 3.0

Model: alibaba/qwen-image-3.0 Balanced Qwen Image 3.0 model for high-quality everyday generation, reliable text rendering, and image editing. Supports the same parameters and 1K/2K resolution tiers as Qwen Image 3.0 Pro.

Qwen Image 2.0 Pro

Model: alibaba/qwen-image-2.0-pro$0.0525/image Best quality. Text rendering, realistic textures. Automatically switches between T2I and editing based on whether image_urls is provided.

Qwen Image 2.0

Model: alibaba/qwen-image-2.0$0.0245/image Faster version of 2.0 Pro. Same capabilities and parameters.

Qwen Image Max

Model: alibaba/qwen-image-max — T2I 0.0525/image/Edit0.0525/image** / Edit **0.0525/image Highest realism, fewest AI artifacts. Editing uses a specialized edit model under the hood (industrial design, geometric reasoning, character consistency). Same parameters as Qwen Image 2.0 Pro.

Qwen Image Plus

Model: alibaba/qwen-image-plus — T2I 0.021/image/Edit0.021/image** / Edit **0.021/image Diverse artistic styles, fast. Editing uses a specialized edit model under the hood. Same parameters as Qwen Image 2.0 Pro.

Qwen Image

Model: alibaba/qwen-image — T2I 0.0245/image/Edit0.0245/image** / Edit **0.0315/image Older base model. Editing uses a specialized edit model under the hood. Same parameters as Qwen Image 2.0 Pro.

Z-Image Turbo

Model: alibaba/z-image-turbo — **0.0105/image(or0.0105/image** (or 0.021 with prompt rewriting) Lightweight fast T2I only. Chinese and English text rendering.

Wan 2.7 Pro Image

Model: alibaba/wan-2.7-pro-image$0.0525/image Highest quality. Thinking mode for T2I. Supports editing with up to 9 images. Up to 4K resolution for T2I.

Wan 2.7 Image

Model: alibaba/wan-2.7-image$0.021/image Faster variant of 2.7 Pro. Same capabilities, max 2K resolution. Same parameters as Wan 2.7 Pro Image.

Wan 2.6 Image

Model: alibaba/wan-2.6-image$0.021/image Automatically selects T2I or editing mode based on image_urls. Supports style transfer with 1–4 reference images.

Wan 2.5 Image

Model: alibaba/wan-2.5-image$0.021/image Automatically selects T2I or editing mode based on image_urls. Supports 1–3 reference images. Same parameters as Wan 2.6 Image.

Wan 2.2 Image

Model: alibaba/wan-2.2-image$0.035/image T2I only. Does not accept image_urls.

Wan 2.2 Flash Image

Model: alibaba/wan-2.2-flash-image$0.0175/image Fast T2I only. Cheapest Wan image model. Same parameters as Wan 2.2 Image.

Grok Imagine Image

Models:
enable_pro has been removed. Choose the model explicitly: xai/grok-imagine-image for speed or xai/grok-imagine-2.0-image for quality.
Both models support text-to-image and image editing. Providing image_urls activates edit mode on the model you selected; it does not switch from the speed model to the quality model. Text generation and edit requests each produce exactly one output image. The generation count is fixed internally and is not user-configurable.

Suno Music

Model: suno-ai/music

Suno Audio Operations

Models: suno-ai/add-vocals, suno-ai/add-instrumental, suno-ai/extend, suno-ai/cover

Suno Stems

Models: suno-ai/stems, suno-ai/stems-all

Suno Lyrics

Model: suno-ai/lyrics

Suno Remix & Edits

Models: suno-ai/remaster, suno-ai/mashup, suno-ai/inspiration, suno-ai/sample, suno-ai/infill, suno-ai/crop, suno-ai/fade, suno-ai/speed, suno-ai/reverse, suno-ai/concat All take a clip_id (mashup and inspiration take clip_ids). Generation models also take mv, tags, prompt, title, make_instrumental, and negative_tags. Range-based edits take seconds: start_s / end_s (infill, crop, sample), fade_in_s / fade_out_s (fade), speed_multiplier with keep_pitch (speed). Full tables: Remaster, Mashup, Inspiration & Sample, Editing.

Suno Visuals

Models: suno-ai/cover-art, suno-ai/video-gen Results arrive as images or videos arrays. Details: Cover Art, AI Video.

Suno Exports & Tools

Models: suno-ai/wav, suno-ai/mp3, suno-ai/video, suno-ai/enhance-prompt, suno-ai/vox Details: Exports, Prompt & Vocal Tools.

Rate Limit Error Response


Error Responses

Error Response Format