Unified Tasks API
curl --request POST \
--url https://api.unifically.com/v1/tasks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "<string>",
"input": {},
"callback_url": "<string>",
"dry_run": true
}
'import requests
url = "https://api.unifically.com/v1/tasks"
payload = {
"model": "<string>",
"input": {},
"callback_url": "<string>",
"dry_run": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({model: '<string>', input: {}, callback_url: '<string>', dry_run: true})
};
fetch('https://api.unifically.com/v1/tasks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.unifically.com/v1/tasks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => '<string>',
'input' => [
],
'callback_url' => '<string>',
'dry_run' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.unifically.com/v1/tasks"
payload := strings.NewReader("{\n \"model\": \"<string>\",\n \"input\": {},\n \"callback_url\": \"<string>\",\n \"dry_run\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.unifically.com/v1/tasks")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"<string>\",\n \"input\": {},\n \"callback_url\": \"<string>\",\n \"dry_run\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.unifically.com/v1/tasks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"<string>\",\n \"input\": {},\n \"callback_url\": \"<string>\",\n \"dry_run\": true\n}"
response = http.request(request)
puts response.read_body{
"code": 200,
"success": true,
"data": {
"task_id": "abc123def456",
"status": "processing"
}
}
Getting Started
Unified Tasks API
Create and manage AI generation tasks with a unified interface. See supported inputs, parameters, pricing, response fields, and API examples.
POST
/
v1
/
tasks
Unified Tasks API
curl --request POST \
--url https://api.unifically.com/v1/tasks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "<string>",
"input": {},
"callback_url": "<string>",
"dry_run": true
}
'import requests
url = "https://api.unifically.com/v1/tasks"
payload = {
"model": "<string>",
"input": {},
"callback_url": "<string>",
"dry_run": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({model: '<string>', input: {}, callback_url: '<string>', dry_run: true})
};
fetch('https://api.unifically.com/v1/tasks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.unifically.com/v1/tasks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => '<string>',
'input' => [
],
'callback_url' => '<string>',
'dry_run' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.unifically.com/v1/tasks"
payload := strings.NewReader("{\n \"model\": \"<string>\",\n \"input\": {},\n \"callback_url\": \"<string>\",\n \"dry_run\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.unifically.com/v1/tasks")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"<string>\",\n \"input\": {},\n \"callback_url\": \"<string>\",\n \"dry_run\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.unifically.com/v1/tasks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"<string>\",\n \"input\": {},\n \"callback_url\": \"<string>\",\n \"dry_run\": true\n}"
response = http.request(request)
puts response.read_body{
"code": 200,
"success": true,
"data": {
"task_id": "abc123def456",
"status": "processing"
}
}
The
Character items must be objects with
Start/end frame support is now available. For now, only start frame control (
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:
The aspect ratio follows the input frame. These models do not accept
Text-to-video defaults to
Duration is locked to the input video length.
Both models support text-to-image and image editing. Providing
Results arrive as
Details: Exports, Prompt & Vocal Tools.
/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
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
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
{
"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, setdry_run to true:
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
}'
{
"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
curl https://api.unifically.com/v1/tasks/abc123def456 \
-H "Authorization: Bearer YOUR_API_KEY"
Path Parameters
string
required
The unique task ID returned from the create task endpoint
Response (Processing)
{
"code": 200,
"success": true,
"data": {
"task_id": "abc123def456",
"status": "processing"
}
}
Response (Completed)
{
"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
curl "https://api.unifically.com/v1/tasks?status=completed&category=video&page_size=50" \
-H "Authorization: Bearer YOUR_API_KEY"
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.
{
"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
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
| 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-h3 | MiniMax Hailuo 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-3.0-pro | Qwen Image 3.0 Pro (T2I + editing, up to 3 reference images) |
alibaba/qwen-image-3.0 | Qwen Image 3.0 (T2I + editing, up to 3 reference images) |
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 (speed; T2I + editing) |
xai/grok-imagine-2.0-image | Grok Imagine 2.0 Image (quality; 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/remaster | Remaster Clip |
suno-ai/mashup | Mashup Two Clips |
suno-ai/inspiration | Generate From Inspiration Clips |
suno-ai/sample | Generate From Sample |
suno-ai/infill | Replace Section |
suno-ai/crop | Crop / Remove Section |
suno-ai/fade | Fade In / Out |
suno-ai/speed | Adjust Speed |
suno-ai/reverse | Reverse Clip |
suno-ai/concat | Get Full Song |
suno-ai/cover-art | Cover Art |
suno-ai/video-gen | AI Video |
suno-ai/wav | WAV Export |
suno-ai/mp3 | MP3 / M4A Export |
suno-ai/video | Music Video Render |
suno-ai/enhance-prompt | Enhance Style Prompt |
suno-ai/vox | Extract Vocals |
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 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. |
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. |
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. |
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. |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | Video prompt, 1-2000 characters |
start_frame_url | string | Conditional | Start frame. Optional for 2.0 when end_frame_url is present; required for 2.3 and 2.3 Fast |
end_frame_url | string | No | End frame. MiniMax 2.0 only; can be used alone or with start_frame_url |
duration | integer | No | 6 (default) or 10. 1080p only supports 6 |
resolution | string | No | 2.0: "512p", "768p" (default), or "1080p". 2.3 models: "768p" (default) or "1080p" |
prompt_optimizer | boolean | No | MiniMax 2.0 only. Default true; set false to preserve the original prompt |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | Video prompt, 1-2000 characters. Use @Image1 through @Image12 for omni references |
image_urls | string[] | No | 1-12 omni-reference image URLs. Cannot be combined with frame fields |
start_frame_url | string | No | Start frame. Cannot be combined with image_urls |
end_frame_url | string | No | End frame. Requires start_frame_url; cannot be combined with image_urls |
aspect_ratio | string | No | "auto", "21:9", "16:9", "4:3", "1:1", "3:4", or "9:16" |
resolution | string | No | "768p" or "2K" (default) |
duration | integer | No | Any integer from 4 through 15. Default 5 |
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
| 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 |
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
Model:xai/grok-imagine-video
| Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | Video prompt. @ImageN addresses items in image_urls; @audio1 addresses the request-level voice |
aspect_ratio | string | No | "1:1" (default), "2:3", "3:2", "9:16", or "16:9" |
duration | integer | No | 1–30 seconds. Default 6 |
resolution | string | No | "480p", "720p", or "1080p". Default "720p" |
start_image_url | string | No | Start frame. Cannot be combined with image_urls or media references |
image_urls | string[] | No | 1–7 ordered image references. Cannot be combined with start_image_url |
character_id | string | No | Existing saved Grok character reference ID |
character | object | No | Transient character: 3 images, or 2 images plus preset voice |
prop | object | No | Transient prop with name and 1–3 images |
location | object | No | Transient location with name and 1–3 images |
voice | string | No | Case-insensitive Grok preset voice. Audio URLs are not supported |
audio | boolean | No | Generate audio. Default true; works with text-only video. false sends skipAudio: true |
video_preset | string | No | "custom" (default), "spicy", "fun", or "normal" |
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:
| 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 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | Text description or editing instruction |
aspect_ratio | string | No | 1:1 (default), 16:9, 9:16, 4:3, 3:4, 3:2, 2:3 |
resolution | string | No | 1K or 2K. Default: 2K |
image_urls | string[] | No | Omit for T2I. Provide 1-3 image URLs for editing or multi-image fusion |
negative_prompt | string | No | Content to avoid in the generated image |
prompt_extend | boolean | No | Smart prompt rewriting (default true) |
seed | integer | No | Seed for reproducibility |
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.
| 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∗∗(or0.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
Models:| Model | Mode |
|---|---|
xai/grok-imagine-image | Speed-focused Grok Imagine image model |
xai/grok-imagine-2.0-image | Quality-focused Grok Imagine 2.0 image model |
enable_pro has been removed. Choose the model explicitly: xai/grok-imagine-image for speed or xai/grok-imagine-2.0-image for quality.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.
| 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) |
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-hawk (v6), chirp-hawk-wild (v6 Wild), chirp-goose (v6 Mini) |
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 |
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
| Parameter | Type | Required | Description |
|---|---|---|---|
clip_id | string | Yes | Clip the artwork or video belongs to |
prompt | string | Yes | Description of the image or video |
quality | string | No | basic (default) or advanced |
aspect_ratio | string | No | Default 1:1 |
image_urls / image_ids | string[] | No | Cover art: up to 4 references, basic only |
duration | integer | No | Video: 5–10 seconds, default 10 |
clip_start_time | number | No | Video: song offset in seconds, default 0 |
start_image_url / end_image_url | string | No | Video: optional first / last frame |
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
| Parameter | Type | Required | Description |
|---|---|---|---|
clip_id | string | Yes* | Clip to export or process (not used by enhance-prompt) |
format | string | No | suno-ai/mp3: mp3 (default) or m4a |
prompt | string | Yes* | suno-ai/enhance-prompt: style description to enhance |
vocal_start_s / vocal_end_s | number | No / Yes* | suno-ai/vox: vocal region in seconds |
Rate Limit Error Response
{
"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
{
"success": false,
"code": 400,
"data": {
"message": "Description of the error",
"request_id": "abc123"
}
}
