> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unifically.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Unified Tasks API
> Create and manage AI generation tasks with a unified interface
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
```bash theme={null}
curl -X POST https://api.unifically.com/v1/tasks \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "google/veo-3.1-fast",
"input": {
"prompt": "A cat walking on the beach at sunset"
},
"callback_url": "https://your-server.com/webhook"
}'
```
### Request Parameters
Model identifier in `provider/model-name` format. See [Available Models](#available-models) below.
Model-specific input parameters. See [Input Parameters](#input-parameters) for details.
Optional webhook URL. When provided, the API sends a POST request to this URL when the task completes or fails. See [Webhooks & Callbacks](/api-reference/callbacks) for payload formats and details.
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
```json 200 theme={null}
{
"code": 200,
"success": true,
"data": {
"task_id": "abc123def456",
"status": "processing"
}
}
```
### Dry Run
To check the cost of a request without creating a task or deducting from your balance, set `dry_run` to `true`:
```bash theme={null}
curl -X POST https://api.unifically.com/v1/tasks \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "google/veo-3.1-fast",
"input": {
"prompt": "A cat walking on the beach at sunset"
},
"dry_run": true
}'
```
```json 200 theme={null}
{
"code": 200,
"success": true,
"data": {
"cost": 0.40
}
}
```
***
## Get Task Status
**GET** `/v1/tasks/:task_id`
Retrieves the status and output of a task.
### Request
```bash theme={null}
curl https://api.unifically.com/v1/tasks/abc123def456 \
-H "Authorization: Bearer YOUR_API_KEY"
```
### Path Parameters
The unique task ID returned from the create task endpoint
### Response (Processing)
```json 200 theme={null}
{
"code": 200,
"success": true,
"data": {
"task_id": "abc123def456",
"status": "processing"
}
}
```
### Response (Completed)
```json 200 theme={null}
{
"code": 200,
"success": true,
"data": {
"task_id": "abc123def456",
"status": "completed",
"output": {
"video_url": "https://cdn.unifically.com/outputs/abc123.mp4"
}
}
}
```
***
## List Tasks
**GET** `/v1/tasks`
Lists your tasks, newest first, with pagination and filters.
### Request
```bash theme={null}
curl "https://api.unifically.com/v1/tasks?status=completed&category=video&page_size=50" \
-H "Authorization: Bearer YOUR_API_KEY"
```
### Query Parameters
1-indexed page number. Default `1`.
Results per page: `10`, `25`, `50`, or `100`. Default `25`. Other values fall back to `25`.
Filter by task status: `processing`, `completed`, or `failed`.
Filter by exact model ID, e.g. `google/veo-3.1-fast`.
Comma-separated list of model categories: `llm`, `video`, `image`, `audio`. Example: `category=video,image`.
Comma-separated list of provider slugs (the part before `/` in the model ID), e.g. `provider=elevenlabs,google`.
Unix timestamp in seconds. Only tasks created at or after this moment.
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.
```json 200 theme={null}
{
"success": true,
"code": 200,
"data": [
{
"task_id": "abc123def456",
"model": "google/veo-3.1-fast",
"category": "video",
"status": "completed",
"cost": 0.40,
"created_at": 1752624000,
"input": {
"prompt": "A cat walking on the beach at sunset"
},
"output": {
"video_url": "https://cdn.unifically.com/outputs/abc123.mp4"
},
"callback_url": "https://your-server.com/webhook",
"callback_result": [
{
"sent_at": 1752624060,
"status": 200,
"status_text": "OK"
}
]
}
],
"pagination": {
"page": 1,
"page_size": 50,
"total": 137,
"total_pages": 3,
"has_next": true,
"has_previous": false
}
}
```
### Task Fields
Unique task identifier.
Model ID the task ran on, e.g. `google/veo-3.1-fast`.
Model category: `audio`, `image`, `video`, or `llm`. `null` if the model is no longer in the catalog.
`processing`, `completed`, or `failed`.
Amount charged for the task in USD.
Unix timestamp (seconds) when the task was created.
The stored request input, as submitted.
The task output (e.g. `video_url`, `image_url`, `audio_url`). `null` while processing.
The webhook URL provided at creation, or `null`.
Webhook delivery attempt log (up to 5 retries): each entry has `sent_at`, `status`, `status_text`. `null` if no callback was configured.
Upstream failure text. Only present when `status` is `failed`.
***
## Available Models
### Video Generation
| Model | Description |
| ------------------------------------- | ---------------------------------------- |
| `google/veo-3.1-fast` | Google Veo 3.1 Fast |
| `google/veo-3.1-quality` | Google Veo 3.1 Quality |
| `google/veo-3.1-lite` | Google Veo 3.1 Lite |
| `google/veo-3.1-lite-relaxed` | Google Veo 3.1 Lite Relaxed |
| `google/veo-3.1-extend` | Google Veo 3.1 Extend |
| `google/veo-3.1-upscale` | Google Veo 3.1 Upscale |
| `google/gemini-omni-flash-video` | Google Gemini Omni Flash Video |
| `google/gemini-omni-flash-video-edit` | Google Gemini Omni Flash Video Edit |
| `hailuo/minimax-2.0` | Minimax Hailuo 2.0 |
| `hailuo/minimax-2.3` | Minimax Hailuo 2.3 |
| `hailuo/minimax-2.3-fast` | Minimax Hailuo 2.3 Fast |
| `hailuo/minimax-3.0` | Minimax Hailuo 3.0 (H3) |
| `kuaishou/kling-3.0-omni-video` | Kling 3.0 Omni Video |
| `kuaishou/kling-3.0-omni-video-edit` | Kling 3.0 Omni Video Edit |
| `kuaishou/kling-o1-video` | Kling O1 Video |
| `kuaishou/kling-o1-video-edit` | Kling O1 Video Edit |
| `kuaishou/kling-3.0-video` | Kling 3.0 Video |
| `kuaishou/kling-3.0-turbo-video` | Kling 3.0 Turbo Video |
| `kuaishou/kling-2.6-video` | Kling 2.6 Video |
| `kuaishou/kling-2.5-turbo-video` | Kling 2.5 Turbo Video |
| `kuaishou/kling-2.1-video` | Kling 2.1 Video |
| `kuaishou/kling-2.1-master-video` | Kling 2.1 Master Video |
| `kuaishou/kling-2.6-motion-control` | Kling 2.6 Motion Control |
| `kuaishou/kling-3.0-motion-control` | Kling 3.0 Motion Control |
| `xai/grok-imagine-video` | Grok Imagine Video (speed-optimized 1.5) |
| `xai/grok-imagine-1.5-video` | Grok Imagine Video 1.5 |
| `xai/grok-imagine-video-extend` | Grok Imagine Video Extend |
| `xai/grok-imagine-upscale` | Grok Imagine Upscale |
| `topaz-labs/video-upscale` | Topaz Video Upscale |
### Image Generation
| Model | Description |
| ------------------------------- | ---------------------------------------------- |
| `google/nano-banana` | Nano Banana |
| `google/nano-banana-pro` | Nano Banana Pro |
| `google/nano-banana-2` | Nano Banana 2 |
| `google/nano-banana-2-lite` | Nano Banana 2 Lite (1K, wide aspect ratios) |
| `openai/gpt-image-2` | GPT Image 2 (1K/2K/4K, multiple aspect ratios) |
| `black-forest-labs/flux.2-pro` | Flux.2 Pro |
| `black-forest-labs/flux.2-flex` | Flux.2 Flex |
| `black-forest-labs/flux.2-max` | Flux.2 Max |
| `kuaishou/kling-o1-image` | Kling O1 Image |
| `kuaishou/kling-3.0-omni-image` | Kling 3.0 Omni Image |
| `kuaishou/kling-3.0-image` | Kling 3.0 Image |
| `kuaishou/kling-2.1-image` | Kling 2.1 Image |
| `topaz-labs/image-upscale` | Topaz Image Upscale |
| `topaz-labs/image-generative` | Topaz Image Generative |
| `alibaba/qwen-image-2.0-pro` | Qwen Image 2.0 Pro (T2I + editing) |
| `alibaba/qwen-image-2.0` | Qwen Image 2.0 (T2I + editing) |
| `alibaba/qwen-image-max` | Qwen Image Max (T2I + editing) |
| `alibaba/qwen-image-plus` | Qwen Image Plus (T2I + editing) |
| `alibaba/qwen-image` | Qwen Image (T2I + editing) |
| `alibaba/z-image-turbo` | Z-Image Turbo (T2I only) |
| `alibaba/wan-2.7-pro-image` | Wan 2.7 Pro Image (T2I + editing, up to 4K) |
| `alibaba/wan-2.7-image` | Wan 2.7 Image (T2I + editing) |
| `alibaba/wan-2.6-image` | Wan 2.6 Image (T2I + editing) |
| `alibaba/wan-2.5-image` | Wan 2.5 Image (T2I + editing) |
| `alibaba/wan-2.2-image` | Wan 2.2 Image (T2I only) |
| `alibaba/wan-2.2-flash-image` | Wan 2.2 Flash Image (T2I only) |
| `xai/grok-imagine-image` | Grok Imagine Image (T2I + editing) |
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 | Description |
| ----------------------------- | ------------------------------- |
| `suno-ai/music` | Suno Music Generation |
| `suno-ai/add-vocals` | Add Vocals to Track |
| `suno-ai/add-instrumental` | Add Instrumental |
| `suno-ai/extend` | Extend Audio |
| `suno-ai/cover` | Create Cover |
| `suno-ai/stems` | Extract Stems |
| `suno-ai/stems-all` | Extract All Stems |
| `suno-ai/lyrics` | Generate Lyrics |
| `suno-ai/wav` | WAV Export |
| `elevenlabs/text-to-speech` | ElevenLabs Text-to-Speech |
| `elevenlabs/text-to-dialogue` | ElevenLabs Multi-Voice Dialogue |
| `elevenlabs/sound-effect` | ElevenLabs Sound Effects |
| `elevenlabs/voice-isolation` | ElevenLabs Voice Isolation |
| `elevenlabs/speech-to-text` | ElevenLabs Speech-to-Text |
***
## Model Parameters
All tasks support `callback_url` (outside the `input` object) for webhook notifications. See [Webhooks & Callbacks](/api-reference/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.
| Mode | Fields | Availability |
| ------------------ | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Frame mode** | `start_image_url` \[+ `end_image_url`] | All models |
| **Reference mode** | `reference_image_urls`, `reference_characters` \[+ `voice`] | Image references are available on all modes. Character references are available on Fast, Lite, and Lite Relaxed only. |
| Parameter | Type | Required | Description |
| ---------------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt` | string | Yes | Text prompt for video generation. Use `@ImageN` or `@CharacterN` to point at specific references. |
| `aspect_ratio` | string | No | `"16:9"` (default) or `"9:16"` |
| `duration` | integer | No | `4`, `6`, or `8` seconds. Default `4`. Must be `8` when any image or character reference is set. |
| `seed` | integer | No | Reproducibility seed |
| `start_image_url` | string | No | Public image URL used as the first frame. Cannot be combined with `reference_image_urls` or `reference_characters`. |
| `end_image_url` | string | No | Public image URL used as the final frame. Requires `start_image_url`; cannot be used by itself. |
| `reference_image_urls` | string\[] | No | Image references for reference-to-video. Max 3 total expanded image URLs across `reference_image_urls` and character images. Cannot be combined with start/end frame fields. |
| `reference_characters` | array | No | Character references. Max 3 total expanded image URLs across images and character `image_urls`. Not available on Quality. |
| `voice` | string | No | Voice preset ID. Requires at least 1 image or character reference. See [voices endpoint](/api-reference/resources#get-google-veo-voices). |
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.
| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ----------------------------------------------------------- |
| `prompt` | string | Yes | Text prompt for the extended content |
| `task_id` | string | Yes | Task ID of a completed generation |
| `model` | string | Yes | One of: `lite`, `fast`, `quality`, `lite-relaxed` |
| `duration` | integer | No | Must be `8` (only supported value for extend). Default `8`. |
| `seed` | integer | No | Reproducibility seed |
#### Upscale
Model: `google/veo-3.1-upscale`
Upscale a completed video to a higher resolution.
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | --------------------------------- |
| `task_id` | string | Yes | Task ID of a completed generation |
| `resolution` | string | Yes | `"1080p"` or `"4k"` |
***
### 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.
| Parameter | Type | Required | Description |
| ---------------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt` | string | Yes | Main video prompt. Use `@ImageN` or `@CharacterN` to point at specific references. |
| `seed` | integer | No | Reproducibility seed. If omitted, one is generated automatically. |
| `aspect_ratio` | string | No | `"16:9"` (default) or `"9:16"` |
| `duration` | integer | No | `4`, `6`, `8`, or `10` seconds. Default `4`. |
| `start_image_url` | string | No | Public image URL used as the first frame. Cannot be combined with `reference_image_urls` or `reference_characters`. |
| `reference_image_urls` | string\[] | No | Public image reference URLs. Max 7 total expanded image + character image URLs. Cannot be combined with start/end frame fields. |
| `reference_characters` | array | No | Character references. Max 3 character items; expanded image URLs count toward the total 7 reference limit. |
| `voice` | string | No | Request-level voice preset ID. Requires at least one image or character reference. See [voices endpoint](/api-reference/resources#get-google-veo-voices). |
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`.
| Parameter | Type | Required | Description |
| ---------------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reference_video_urls` | string\[] | Yes | Public source video URL. Must contain exactly one URL. |
| `prompt` | string | Yes | Edit instruction. Use `@Video1` to refer to the source video and `@ImageN`/`@CharacterN` for extra references. |
| `reference_image_urls` | string\[] | No | Public image URLs used as edit references. |
| `reference_characters` | array | No | Character references for the edit. Max 3 character items. Supports per-character `voice` or `custom_voice`. See [voices endpoint](/api-reference/resources#get-google-veo-voices). |
| `seed` | integer | No | Reproducibility seed. If omitted, one is generated automatically. |
| `start_frame` | integer | No | First source frame index included in the edit range. Default `0`. |
| `end_frame` | integer | No | Last source frame index included in the edit range. Defaults to the detected final frame when available. |
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`
| Parameter | Type | Required | Description |
| --------------------- | ------- | -------- | ---------------------------------------------------------------------------- |
| `prompt` | string | Yes\* | Max 2000 chars. \*Required if no `start_image_url` |
| `start_image_url` | string | Yes\* | Image URL (auto-uploaded). \*Required if no `prompt` (required for 2.3-fast) |
| `end_image_url` | string | No | End frame image URL (minimax-2.0 only, 768p/1080p) |
| `duration` | integer | No | `6` or `10` seconds. 1080p only supports `6` |
| `resolution` | string | No | `"768p"` (default), `"1080p"` |
| `prompt_optimization` | boolean | No | Let MiniMax optimize prompt |
***
### Minimax Hailuo 3.0
Model: `hailuo/minimax-3.0`
MiniMax H3 generates 2K video with native audio in the same pass. Supports text-to-video, frame-guided generation (start and/or end frame), and reference-based generation (images, videos, or audio). Frame images and references are mutually exclusive.
| Parameter | Type | Required | Description |
| ---------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `prompt` | string | Yes | Text prompt, 2–2000 chars |
| `start_image_url` | string | No | First frame image (image-to-video / keyframe-guided) |
| `end_image_url` | string | No | Last frame image. Usable alone (last-frame-guided) or with `start_image_url` |
| `reference_image_urls` | string\[] | No | Subject reference images (multi-reference conditioning). Cannot be combined with frame images |
| `reference_video_urls` | string\[] | No | Reference videos for continuation / instruction-based editing. Cannot be combined with frame images |
| `reference_audio_urls` | string\[] | No | Reference audio for audio-video continuation. Cannot be combined with frame images |
| `aspect_ratio` | string | No | `"16:9"` (default), `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`, `"21:9"`. Ignored when a frame image is supplied (output follows the input frame) |
| `duration` | integer | No | `5`–`15` seconds. Default `5` |
| `seed` | integer | No | `0`–`4294967295`. Reproducibility seed |
Output is a single 2K tier — e.g. 2560×1440 at 16:9, 2944×1248 at 21:9. There is no `resolution` parameter.
Rejected combinations: any of `reference_image_urls` / `reference_video_urls` / `reference_audio_urls` together with `start_image_url` or `end_image_url`.
***
### Kling 3.0 Omni Video
Model: `kuaishou/kling-3.0-omni-video`
| Parameter | Type | Required | Description |
| ----------------- | --------- | ----------- | ----------------------------------------------------------------------------------------- |
| `video_mode` | string | No | `"elements"` (default), `"start_end_frame"`, `"transform"`, `"video_reference"` |
| `prompt` | string | Conditional | Text prompt. Mutually exclusive with `multi_shots` |
| `mode` | string | No | `"pro"` (default). `"std"` (720p) or `"pro"` (1080p) |
| `duration` | integer | No | 3–15 seconds (default 5) |
| `aspect_ratio` | string | No | `"16:9"` (default), `"9:16"`, `"1:1"`, `"auto"` (start\_end\_frame only) |
| `native_audio` | boolean | No | Generate AI audio (default false) |
| `keep_audio` | boolean | No | Preserve audio from source video (default true) |
| `image_urls` | string\[] | No | Up to 7 reference image URLs. Use `@Image1`, `@Image2` in prompt |
| `start_frame_url` | string | No | First frame image URL (start\_end\_frame mode) |
| `end_frame_url` | string | No | Last frame image URL (start\_end\_frame mode) |
| `video_url` | string | No | Source video URL (transform/video\_reference modes) |
| `multi_shots` | array | No | 2–6 shots, each `{ "prompt": string, "duration": int }`. Mutually exclusive with `prompt` |
| `elements` | array | No | Character/object elements (IMAGE + 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.
| Parameter | Type | Required | Description |
| ----------------- | --------- | -------- | ------------------------------------------------------------------------------- |
| `video_mode` | string | No | `"elements"` (default), `"start_end_frame"`, `"transform"`, `"video_reference"` |
| `prompt` | string | Yes | Text prompt |
| `mode` | string | No | `"pro"` (default). `"std"` (720p) or `"pro"` (1080p) |
| `duration` | integer | No | 3–10 seconds (default 5) |
| `aspect_ratio` | string | No | `"16:9"` (default), `"9:16"`, `"1:1"`, `"auto"` (start\_end\_frame only) |
| `keep_audio` | boolean | No | Preserve audio from source video (default true) |
| `image_urls` | string\[] | No | Up to 7 reference image URLs. Use `@Image1`, `@Image2` in prompt |
| `start_frame_url` | string | No | First frame image URL (start\_end\_frame mode) |
| `end_frame_url` | string | No | Last frame image URL (start\_end\_frame mode) |
| `video_url` | string | No | Source video URL (transform/video\_reference modes) |
***
### Kling 3.0 Omni Video Edit
Model: `kuaishou/kling-3.0-omni-video-edit`
| Parameter | Type | Required | Description |
| -------------- | --------- | -------- | ---------------------------------------------------------------- |
| `video_url` | string | Yes | Source video URL to edit |
| `prompt` | string | Yes | Text prompt describing the edit |
| `video_mode` | string | No | `"reference"` (default) or `"transform"` |
| `keep_audio` | boolean | No | Preserve original audio (default false) |
| `mode` | string | No | `"std"` (default) or `"pro"` |
| `aspect_ratio` | string | No | `"16:9"` (default), `"9:16"`, `"1:1"` |
| `image_urls` | string\[] | No | Up to 4 reference image URLs. Use `@Image1`, `@Image2` in prompt |
| `elements` | array | No | Up to 4 character/object elements |
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`.
| Parameter | Type | Required | Description |
| -------------- | --------- | -------- | ---------------------------------------------------------------- |
| `video_url` | string | Yes | Source video URL to edit |
| `prompt` | string | Yes | Text prompt describing the edit |
| `video_mode` | string | No | `"reference"` (default) or `"transform"` |
| `keep_audio` | boolean | No | Preserve original audio (default false) |
| `mode` | string | No | `"std"` (default) or `"pro"` |
| `aspect_ratio` | string | No | `"16:9"` (default), `"9:16"`, `"1:1"` |
| `image_urls` | string\[] | No | Up to 4 reference image URLs. Use `@Image1`, `@Image2` in prompt |
***
### Kling 3.0 Video
Model: `kuaishou/kling-3.0-video`
| Parameter | Type | Required | Description |
| ----------------- | ------- | ----------- | ----------------------------------------------------------------------------------------- |
| `prompt` | string | Conditional | Text prompt. Mutually exclusive with `multi_shots` |
| `mode` | string | No | `"pro"` (default). `"std"` (720p) or `"pro"` (1080p) |
| `duration` | integer | No | 3–15 seconds (default 5) |
| `aspect_ratio` | string | No | `"16:9"` (default), `"9:16"`, `"1:1"` |
| `native_audio` | boolean | No | Generate AI audio (default true) |
| `start_frame_url` | string | Yes | First frame image URL |
| `end_frame_url` | string | No | Last frame image URL |
| `elements` | array | No | Character/object elements |
| `multi_shots` | array | No | 2–6 shots, each `{ "prompt": string, "duration": int }`. Mutually exclusive with `prompt` |
***
### 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.
| Parameter | Type | Required | Description |
| ----------------- | ------- | -------- | ---------------------------------------------------- |
| `prompt` | string | Yes | Text prompt |
| `mode` | string | No | `"pro"` (default). `"std"` (720p) or `"pro"` (1080p) |
| `duration` | integer | No | 3–15 seconds (default 5) |
| `aspect_ratio` | string | No | `"16:9"` (default), `"9:16"`, `"1:1"` |
| `start_frame_url` | string | No | First frame image URL. Omit for text-to-video |
***
### Kling 2.6 Video
Model: `kuaishou/kling-2.6-video`
| Parameter | Type | Required | Description |
| ----------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| `prompt` | string | Yes | Text prompt |
| `mode` | string | No | `"pro"` (default). `"std"` (720p) or `"pro"` (1080p) |
| `duration` | integer | No | `5` or `10` seconds |
| `native_audio` | boolean | No | Enable AI audio generation (default false). Requires pro mode |
| `start_frame_url` | string | Yes | First frame image URL |
| `end_frame_url` | string | No | Last frame image URL (not available with native\_audio) |
| `voices` | array | No | Voice references (max 5, requires native\_audio). Each: `{ "voice_id": int }` or `{ "voice_url": string }` |
***
### Kling 2.5 Turbo Video
Model: `kuaishou/kling-2.5-turbo-video`
| Parameter | Type | Required | Description |
| ----------------- | ------- | -------- | ----------------------------------------------------------------------------------- |
| `prompt` | string | Yes | Text prompt |
| `mode` | string | No | `"pro"` (default). `"std"` (720p) or `"pro"` (1080p) |
| `duration` | integer | No | `5` or `10` seconds |
| `aspect_ratio` | string | No | `"16:9"` (default), `"9:16"`, `"1:1"`. Ignored when `start_frame_url` is set |
| `start_frame_url` | string | No | First frame image URL |
| `end_frame_url` | string | No | Last frame image URL |
| `sound_effects` | object | No | `{ "sound": string, "music": string, "asmr_mode": boolean }`. Omit to disable audio |
***
### Kling 2.1 Video
Model: `kuaishou/kling-2.1-video`
Image-to-video only.
| Parameter | Type | Required | Description |
| ----------------- | ------- | -------- | ----------------------------------------------------------------------------------- |
| `prompt` | string | Yes | Text prompt |
| `start_frame_url` | string | Yes | First frame image URL |
| `end_frame_url` | string | No | Last frame image URL |
| `duration` | integer | No | `5` or `10` seconds |
| `mode` | string | No | `"pro"` (default). `"std"` or `"pro"` |
| `sound_effects` | object | No | `{ "sound": string, "music": string, "asmr_mode": boolean }`. Omit to disable audio |
***
### Kling 2.1 Master Video
Model: `kuaishou/kling-2.1-master-video`
Pro-only. No end frame support.
| Parameter | Type | Required | Description |
| ----------------- | ------- | -------- | ----------------------------------------------------------------------------------- |
| `prompt` | string | Yes | Text prompt |
| `duration` | integer | No | `5` or `10` seconds |
| `start_frame_url` | string | No | First frame image URL (optional) |
| `sound_effects` | object | No | `{ "sound": string, "music": string, "asmr_mode": boolean }`. Omit to disable audio |
***
### Kling 3.0 Motion Control
Model: `kuaishou/kling-3.0-motion-control`
| Parameter | Type | Required | Description |
| ----------------------- | ------- | -------- | ----------------------------------------------- |
| `prompt` | string | Yes | Text prompt describing the motion |
| `image_url` | string | Yes | Character/subject image URL |
| `video_url` | string | Yes | Motion reference video URL |
| `mode` | string | No | `"std"` (default) or `"pro"` |
| `keep_audio` | boolean | No | Preserve audio from motion video (default true) |
| `character_orientation` | string | No | `"video"` (default) or `"image"` |
| `elements` | array | No | Additional character/object elements |
***
### Kling 2.6 Motion Control
Model: `kuaishou/kling-2.6-motion-control`
| Parameter | Type | Required | Description |
| ----------------------- | ------- | -------- | ----------------------------------------------- |
| `prompt` | string | Yes | Text prompt describing the motion |
| `image_url` | string | Yes | Character/subject image URL |
| `video_url` | string | Yes | Motion reference video URL |
| `mode` | string | No | `"std"` (default) or `"pro"` |
| `keep_audio` | boolean | No | Preserve audio from motion video (default true) |
| `character_orientation` | string | No | `"video"` (default) or `"image"` |
***
### 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:
| Mode | How to activate | Behaviour |
| ---------- | ---------------------- | ----------------------------------------------------------------------------------------- |
| **Preset** | Provide `video_preset` | The preset controls the video style; `prompt`, `extend_at`, `extend_duration` are ignored |
| **Custom** | Omit `video_preset` | You control timing and prompt; `prompt`, `extend_at`, `extend_duration` are required |
| Parameter | Type | Required | Description |
| ----------------- | ------ | -------- | --------------------------------------------------------------- |
| `task_id` | string | Yes | Task ID of a completed video generation |
| `video_preset` | string | No | `"spicy"` or `"normal"`. Enables preset mode |
| `prompt` | string | No | Text prompt to guide the extension. **Required in custom mode** |
| `extend_at` | float | No | Second to start the extension from. **Required in custom mode** |
| `extend_duration` | int | No | `6` or `10` seconds. **Required in custom mode** |
***
### GPT Image
Models: `openai/gpt-image-2`
| Parameter | Type | Required | Description |
| -------------- | ------ | -------- | ------------------------------------------- |
| `prompt` | string | Yes | Text description |
| `image_urls` | array | No | Reference image URLs for image editing mode |
| `aspect_ratio` | string | No | `1:1`, `3:2`, `2:3`, `16:9`. Default: `1:1` |
| `resolution` | string | No | `1K`, `2K`, `4K`. Default: `1K` |
***
### Nano Banana
Models: `google/nano-banana`, `google/nano-banana-pro`
| Parameter | Type | Required | Description |
| -------------- | ------ | -------- | ----------------------------------------------------------------------- |
| `prompt` | string | Yes | Text description |
| `aspect_ratio` | string | Yes | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
| `image_urls` | array | No | Reference images |
| `resolution` | string | No | Pro only: `1k`, `2k`, `4k` |
***
### Flux.2
Models: `black-forest-labs/flux.2-pro`, `black-forest-labs/flux.2-flex`, `black-forest-labs/flux.2-max`
| Parameter | Type | Required | Description |
| -------------- | ------- | -------- | ----------------------------------------------------------------------------------- |
| `prompt` | string | Yes | Text description |
| `image_urls` | array | No | Reference images (Pro/Max: 8, Flex: 10) |
| `aspect_ratio` | string | No | `auto`, `1:1`, `4:3`, `16:9`, `3:2`, `2:3`, `9:16`, `3:4` (Max also: `5:4`, `21:9`) |
| `quality` | string | No | `1K` or `2K` |
| `steps` | integer | No | Flex only: 1-50 (more = higher quality) |
| `cfg` | number | No | Flex only: 1.5-10 (higher = follows prompt more strictly) |
***
### 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.
| Parameter | Type | Required | Description |
| ----------------- | --------- | -------- | --------------------------------------------- |
| `prompt` | string | Yes | Text prompt (max 800 chars) |
| `aspect_ratio` | string | No | `1:1` (default), `16:9`, `9:16`, `4:3`, `3:4` |
| `image_urls` | string\[] | No | Omit for T2I. Provide image URLs for editing |
| `negative_prompt` | string | No | What to avoid (max 500 chars) |
| `prompt_extend` | boolean | No | Smart prompt rewriting (default true) |
| `seed` | integer | No | Seed for reproducibility |
***
### 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** / 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** / 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** / 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** (or $0.021 with prompt rewriting)
Lightweight fast T2I only. Chinese and English text rendering.
| Parameter | Type | Required | Description |
| --------------- | ------- | -------- | ----------------------------------------------------------- |
| `prompt` | string | Yes | Text prompt (max 800 chars) |
| `aspect_ratio` | string | No | `1:1` (default), `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9` |
| `prompt_extend` | boolean | No | Prompt rewriting (default false, doubles cost) |
| `seed` | integer | No | Seed for reproducibility |
***
### 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.
| Parameter | Type | Required | Description |
| --------------- | --------- | -------- | ------------------------------------------------------------------------------------------ |
| `prompt` | string | Yes | Text prompt (max 5000 chars) |
| `aspect_ratio` | string | No | `1:1` (default), `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`. Editing preserves input ratio |
| `image_urls` | string\[] | No | Omit for T2I. Up to 9 images for editing |
| `thinking_mode` | boolean | No | Better quality, slower (default true). T2I only |
| `seed` | integer | No | Seed for reproducibility |
***
### 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.
| Parameter | Type | Required | Description |
| ----------------- | --------- | -------- | ----------------------------------------------------------- |
| `prompt` | string | Yes | Text prompt (max 2000 chars) |
| `aspect_ratio` | string | No | `1:1` (default), `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9` |
| `image_urls` | string\[] | No | Omit for T2I. 1–4 images for editing/style transfer |
| `negative_prompt` | string | No | What to avoid (max 500 chars) |
| `prompt_extend` | boolean | No | Smart prompt rewriting (default true) |
| `seed` | integer | No | Seed for reproducibility |
***
### 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`.
| Parameter | Type | Required | Description |
| ----------------- | ------- | -------- | --------------------------------------------- |
| `prompt` | string | Yes | Text prompt (max 500 chars) |
| `aspect_ratio` | string | No | `1:1` (default), `3:4`, `4:3`, `9:16`, `16:9` |
| `negative_prompt` | string | No | What to avoid |
| `seed` | integer | No | Seed for reproducibility |
***
### 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
Model: `xai/grok-imagine-image` — Pro mode: **\$0.025/image**
Generate and edit images using xAI's Grok Imagine model. When `image_urls` is provided, the model runs in edit mode.
| Parameter | Type | Required | Description |
| ----------------- | --------- | -------- | ------------------------------------------------------- |
| `prompt` | string | Yes | Text description or edit instruction |
| `aspect_ratio` | string | No | `"1:1"` (default), `"2:3"`, `"3:2"`, `"9:16"`, `"16:9"` |
| `image_urls` | string\[] | No | 1–5 reference image URLs (triggers edit mode) |
| `enable_pro` | boolean | No | Enable pro mode for higher quality results |
| `upsample_prompt` | boolean | No | Let AI enhance your prompt for better results |
| `enable_nsfw` | boolean | No | Enable NSFW content generation |
***
### Suno Music
Model: `suno-ai/music`
| Parameter | Type | Required | Description |
| ------------------------ | ------- | -------- | ----------------------------------------------------------------------------------- |
| `mv` | string | Yes | Model version: `chirp-v3-5`, `chirp-v4`, `chirp-auk`, `chirp-bluejay`, `chirp-crow` |
| `custom` | boolean | Yes | `false` for simple mode, `true` for custom mode |
| `gpt_description_prompt` | string | No | Simple mode: song description with lyrics |
| `prompt` | string | No | Custom mode: detailed lyrics/prompt |
| `tags` | string | No | Custom mode: genre/style tags |
| `title` | string | No | Song title |
| `make_instrumental` | boolean | No | Generate instrumental only |
| `negative_tags` | string | No | Custom mode: styles to avoid |
| `persona_id` | string | No | Custom voice ID from Suno voice creation; music uses that voice for vocals |
***
### Suno Audio Operations
Models: `suno-ai/add-vocals`, `suno-ai/add-instrumental`, `suno-ai/extend`, `suno-ai/cover`
| Parameter | Type | Required | Description |
| ------------------------ | ------- | -------- | ---------------------------------------- |
| `mv` | string | Yes | Model version |
| `clip_id` | string | Yes\* | Existing clip ID |
| `audio_url` | string | Yes\* | Audio file URL (alternative to clip\_id) |
| `custom` | boolean | Yes | Simple or custom mode |
| `gpt_description_prompt` | string | No | Simple mode description |
| `prompt` | string | No | Custom mode prompt |
| `continue_at` | number | No | Extend: time in seconds to continue from |
| `start_s` | number | No | Start time for overlay |
| `end_s` | number | No | End time for overlay |
***
### Suno Stems
Models: `suno-ai/stems`, `suno-ai/stems-all`
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------- |
| `clip_id` | string | Yes | Clip ID to extract stems from |
| `title` | string | No | Title for extraction |
***
### Suno Lyrics
Model: `suno-ai/lyrics`
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------ |
| `prompt` | string | Yes | Description of lyrics to generate |
| `mv` | string | Yes | Lyrics model: `remi-v1` or `default` |
***
### Rate Limit Error Response
```json theme={null}
{
"success": false,
"code": 429,
"data": {
"message": "You have been ratelimited, this temporary restriction will be lifted in: 45 seconds"
}
}
```
***
## Error Responses
| Code | Description |
| ---- | ----------------------------------------- |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Invalid or missing API key |
| 402 | Payment Required - Insufficient balance |
| 404 | Not Found - Task or model not found |
| 429 | Too Many Requests - Rate limited |
| 500 | Internal Server Error |
### Error Response Format
```json theme={null}
{
"success": false,
"code": 400,
"data": {
"message": "Description of the error",
"request_id": "abc123"
}
}
```