Unified Tasks API - Unifically

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

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",
      "resolution": "1080p"
    },
    "callback_url": "https://your-server.com/webhook"
  }'

Request Parameters

model

string

required

Model identifier in provider/model-name format. See Available Models below.

input

object

required

Model-specific input parameters. See Input Parameters for details.

callback_url

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.

dry_run

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": "pending"
  }
}

Dry Run

To check the cost of a request without creating a task or deducting from your balance, set dry_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",
      "resolution": "1080p"
    },
    "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

task_id

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"
    }
  }
}

Available Models

Video Generation

Model	Description
`google/veo-3.1-fast`	Google Veo 3.1 Fast (720p, 1080p, 4k)
`google/veo-3.1-quality`	Google Veo 3.1 Quality (720p, 1080p, 4k)
`openai/sora-2`	OpenAI Sora 2 (5s, 10s, 15s, 20s)
`openai/sora-2-pro`	OpenAI Sora 2 Pro (10s, 15s, 20s, 25s)
`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
`higgsfield-ai/lite`	Higgsfield Lite
`higgsfield-ai/turbo`	Higgsfield Turbo
`higgsfield-ai/standard`	Higgsfield Standard
`higgsfield-ai/cinematic-studio-video`	Cinematic Studio Video
`kuaishou/kling-3.0-omni-video`	Kling v3.0 Omni Video
`kuaishou/kling-3.0-omni-video-edit`	Kling v3.0 Omni Video Edit
`kuaishou/kling-o1-video`	Kling O1 Video
`kuaishou/kling-2.6`	Kling v2.6
`kuaishou/kling-2.5`	Kling v2.5
`kuaishou/kling-2.1`	Kling v2.1
`kuaishou/kling-2.1-master`	Kling v2.1 Master
`kuaishou/kling-2.5-turbo-pro`	Kling v2.5 Turbo Pro
`kuaishou/kling-2.6-motion-control`	Kling v2.6 Motion Control
`kuaishou/kling-3.0-motion-control`	Kling v3.0 Motion Control
`topaz-labs/video-upscale`	Topaz Video Upscale

Image Generation

Model	Description
`google/nano-banana`	Nano Banana
`google/nano-banana-pro`	Nano Banana Pro
`openai/gpt-image-1`	GPT Image 1 (low, medium, high quality)
`openai/gpt-image-1.5`	GPT Image 1.5 (low, medium, high quality)
`higgsfield-ai/cinematic-studio-image`	Cinematic Studio Image
`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 v3.0 Omni Image
`topaz-labs/image-upscale`	Topaz Image Upscale
`topaz-labs/image-generative`	Topaz Image Generative

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
`higgsfield-ai/speak`	Speak (standard, high quality)
`higgsfield-ai/tts`	Text-to-Speech
`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

Models: google/veo-3.1-fast, google/veo-3.1-quality

Parameter	Type	Required	Description
`prompt`	string	Yes	Text description of the video
`aspect_ratio`	string	No	`16:9` or `9:16`
`start_image_url`	string	No	Starting frame image URL
`end_image_url`	string	No	Ending frame image URL
`resolution`	string	No	`720p` (default), `1080p`, `4k`
`seed`	integer	No	Seed for reproducibility

Pricing: Fast: 720p

0.30, 1080p

0.40, 4k

0.50 | Quality: 720p

0.60, 1080p

0.70, 4k

0.80

OpenAI Sora 2

Models: openai/sora-2, openai/sora-2-pro

Parameter	Type	Required	Description
`prompt`	string	Yes	Text description of the video
`duration`	integer	No	Sora 2: 5, 10, 15, 20s / Pro: 10, 15, 20, 25s
`aspect_ratio`	string	No	`16:9` or `9:16`
`image_url`	string	No	Reference image URL
`cameo_video_url`	string	No	Cameo character video (max 4 seconds)
`character_prompt`	string	No	Description of cameo character
`safety_instruction`	string	No	Safety guidance for content

Pricing: Sora 2: 10s

0.10, 15s

0.15, 25s 0.40$

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	`"512p"` (2.0 I2V only), `"768p"` (default), `"1080p"`
`prompt_optimization`	boolean	No	Let MiniMax optimize prompt

Pricing: minimax-2.0

0.17, minimax-2.3

0.17, minimax-2.3-fast $0.11

Higgsfield Video

Models: higgsfield-ai/lite, higgsfield-ai/turbo, higgsfield-ai/standard

Parameter	Type	Required	Description
`prompt`	string	Yes	Text description
`start_image_url`	string	Yes	Starting frame image URL
`motion_id`	string	Yes	Motion preset ID (UUID)
`end_image_url`	string	No	Ending frame image URL
`enhance_prompt`	boolean	No	Enhance prompt with AI
`seed`	integer	No	Seed for reproducibility

Pricing: Lite

0.15, Turbo

0.21, Standard $0.30

Higgsfield Cinematic Studio Video

Model: higgsfield-ai/cinematic-studio-video

Parameter	Type	Required	Description
`prompt`	string	No	Text description
`start_image_url`	string	Yes	Starting frame image URL
`end_image_url`	string	No	Ending frame (disables preset_id, sound, slow_motion)
`duration`	integer	No	`5` or `10` seconds
`aspect_ratio`	string	No	`1:1`, `3:4`, `2:3`, `9:16`, `3:2`, `4:3`, `16:9`, `21:9`
`preset_id`	string	No	Camera movement preset ID
`sound`	boolean	No	Enable AI-generated sound
`slow_motion`	boolean	No	Enable slow motion effect
`seed`	integer	No	0-999999 for reproducibility

Pricing: 5s+sound

0.16, 5s

0.10, 10s+sound

0.36, 10s

0.20

Kling v2.6

Model: kuaishou/kling-2.6

Parameter	Type	Required	Description
`prompt`	string	Yes*	*Required for text-to-video, optional for image-to-video
`start_image_url`	string	No	Start frame URL (enables image-to-video)
`end_image_url`	string	No	End frame URL
`duration`	integer	No	`5` or `10` seconds
`aspect_ratio`	string	No	`"16:9"`, `"9:16"`, `"1:1"`. Text-to-video only
`mode`	string	No	`"std"` or `"pro"`
`enable_audio`	boolean	No	Enable audio generation

Pricing:

0.032/s (5s:

0.16, 10s: $0.32)

Kling v2.5

Model: kuaishou/kling-2.5 Pro-only model with 1080p output. Supports end frame.

Parameter	Type	Required	Description
`prompt`	string	Yes*	*Required for text-to-video, optional for image-to-video
`start_image_url`	string	No	Start frame URL (enables image-to-video)
`end_image_url`	string	No	End frame URL
`duration`	integer	No	`5` or `10` seconds
`aspect_ratio`	string	No	`"16:9"`, `"9:16"`, `"1:1"`. Text-to-video only
`mode`	string	No	Pro only
`enable_audio`	boolean	No	Enable audio generation

Pricing: 5s

0.27, 10s

0.53

Kling v2.1

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

Parameter	Type	Required	Description
`prompt`	string	No	Text description (optional)
`start_image_url`	string	Yes	Starting image URL
`end_image_url`	string	No	End frame URL
`duration`	integer	No	`5` or `10` seconds
`mode`	string	No	`"std"` or `"pro"`
`enable_audio`	boolean	No	Enable audio generation

Pricing: Std (720p): 5s

0.13, 10s

0.27 | Pro (1080p): 5s

0.27, 10s

0.53

Kling v2.1 Master

Model: kuaishou/kling-2.1-master Pro-only model with 1080p output. No end image support.

Parameter	Type	Required	Description
`prompt`	string	Yes*	*Required for text-to-video, optional for image-to-video
`start_image_url`	string	No	Starting image URL (enables image-to-video)
`duration`	integer	No	`5` or `10` seconds
`aspect_ratio`	string	No	`"16:9"`, `"9:16"`, `"1:1"`. Text-to-video only
`mode`	string	No	Pro only
`enable_audio`	boolean	No	Enable audio generation

Pricing: 5s

0.40, 10s

0.80

Kling O1 Video (Omni)

Model: kuaishou/kling-o1-video

Parameter	Type	Required	Description
`prompt`	string	Yes	Text description
`mode`	string	No	`"std"` or `"pro"`
`duration`	integer	No	3–10 seconds
`aspect_ratio`	string	No	`"16:9"`, `"9:16"`, `"1:1"`
`count`	integer	No	1–4
`image_urls`	string[]	No	Up to 7 image URLs, ref as `@image_1` in prompt
`elements`	ElementInput[]	No	Up to 7, IMAGE only. Ref as `@element_1` in prompt
`start_image_url`	string	No	Start frame URL
`end_image_url`	string	No	End frame URL
`video_url`	string	No	Reference video URL, ref as `@video_1`
`video_mode`	string	No	`"reference"` or `"transform"`
`keep_audio`	boolean	No	Keep audio from reference video

Pricing:

0.048/s (5s:

0.24, 10s: $0.48)

Kling v3.0 Omni Video

Model: kuaishou/kling-3.0-omni-video Same as O1 Video with these differences: duration 3–15, aspect_ratio adds "auto", elements support IMAGE + VIDEO, multi_shot supported (2–6 shots, total 3–15s). Pricing: 5s 720p

0.14/

0.16 (sound off/on), 1080p

0.16/

0.20; 10s 720p

0.26/

0.30, 1080p

0.30/

0.40

Kling v3.0 Omni Video Edit

Model: kuaishou/kling-3.0-omni-video-edit

Parameter	Type	Required	Description
`video_url`	string	Yes	Video to reference or transform
`prompt`	string	Yes	Text description
`video_mode`	string	No	`"reference"` or `"transform"`
`keep_audio`	boolean	No	Keep original video audio
`mode`	string	No	`"std"` or `"pro"`
`aspect_ratio`	string	No	`"16:9"`, `"9:16"`, `"1:1"`
`image_urls`	string[]	No	Up to 4 reference image URLs
`elements`	ElementInput[]	No	Up to 4, IMAGE + VIDEO

Duration is locked to the input video length. Pricing: std (720p)

0.04/s, pro (1080p)

0.0533/s

Kling v2.6 Motion Control

Model: kuaishou/kling-2.6-motion-control

Parameter	Type	Required	Description
`image_url`	string	Yes	Image with person (auto-uploaded to Kling)
`video_url`	string	Yes	Motion reference video (auto-uploaded to Kling)
`prompt`	string	No	Text guidance
`keep_audio`	boolean	No	Preserve audio from motion video
`character_orientation`	string	No	`"video"` or `"image"`
`mode`	string	No	`"std"` or `"pro"`

Pricing: 720p

0.01/s, 1080p

0.0225/s

GPT Image

Models: openai/gpt-image-1, openai/gpt-image-1.5

Parameter	Type	Required	Description
`prompt`	string	Yes	Text description
`image_urls`	array	No	Reference images
`aspect_ratio`	string	No	`1:1`, `2:3`, `3:2`
`quality`	string	No	`low`, `medium`, `high`

Pricing: GPT Image 1: low

0.01, medium

0.02, high

0.04 | 1.5: low

0.02, medium

0.03, high

0.05

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`

Pricing: Nano Banana

0.03 | Pro

0.06

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)

Pricing: Pro: 1K

0.02, 2K

0.03 | Flex: 1K

0.04, 2K

0.06 | Max: 1K

0.05, 2K

0.07

Higgsfield Cinematic Studio Image

Model: higgsfield-ai/cinematic-studio-image

Parameter	Type	Required	Description
`prompt`	string	Yes	Text description
`resolution`	string	No	`1k`, `2k`, `4k` (default: 2k)
`image_urls`	array	No	Reference images (max 4)
`camera_model_id`	string	No	Camera model setting ID
`camera_lens_id`	string	No	Lens type setting ID
`camera_aperture_id`	string	No	Aperture setting ID
`camera_focal_length_id`	string	No	Focal length setting ID

Pricing: 1k/2k

0.03, 4k

0.06

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

Pricing: $0.06 per generation

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

Pricing: $0.06 per operation

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

Pricing: stems

0.05, stems-all

0.20

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`

Pricing: $0.012 per generation

Higgsfield TTS

Model: higgsfield-ai/tts

Parameter	Type	Required	Description
`voice_id`	string	Yes	Voice ID
`prompt`	string	Yes	Text to convert to speech
`sound_id`	string	No	Background sound ID
`similarity_boost`	integer	No	0-100 (default 90)
`style`	integer	No	0-100 (default 60)
`speed`	number	No	0-1.2 (default 1.1)
`stability`	integer	No	0-100 (default 30)

Pricing: $0.05 per generation

Higgsfield Speak

Model: higgsfield-ai/speak

Parameter	Type	Required	Description
`image_url`	string	Yes	Person/avatar image URL
`audio_url`	string	Yes*	Audio file URL
`audio_task_id`	string	Yes*	TTS task ID (alternative to audio_url)
`prompt`	string	Yes	Text description for video
`quality`	string	No	`standard` or `high`
`enhance_prompt`	boolean	No	Enhance prompt (default true)
`seed`	integer	No	Seed for reproducibility

Pricing: standard

0.25, high

0.35

Rate Limiting

Endpoint Type	Limit	Ban Duration
Generation (POST)	10 req/sec	60 seconds
Polling (GET)	10 req/sec	60 seconds

Rate Limit Headers

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1706356800
Retry-After: 45  (only when banned)

Rate Limit Error Response

{
  "success": false,
  "code": 429,
  "data": {
    "message": "You have been ratelimited, this temporary restriction will be lifted in: 45 seconds",
    "code": "rate_limit_exceeded"
  }
}

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",
    "code": "error_code",
    "request_id": "abc123"
  }
}

API Reference

​Create Task

​Request

​Request Parameters

​Response

​Dry Run

​Get Task Status

​Request

​Path Parameters

​Response (Processing)

​Response (Completed)

​Available Models

​Video Generation

​Image Generation

​Audio Generation

​Model Parameters

​Google Veo 3.1

​OpenAI Sora 2

​Minimax Hailuo

​Higgsfield Video

​Higgsfield Cinematic Studio Video

​Kling v2.6

​Kling v2.5

​Kling v2.1

​Kling v2.1 Master

​Kling O1 Video (Omni)

​Kling v3.0 Omni Video

​Kling v3.0 Omni Video Edit

​Kling v2.6 Motion Control

​GPT Image

​Nano Banana

​Flux.2

​Higgsfield Cinematic Studio Image

​Suno Music

​Suno Audio Operations

​Suno Stems

​Suno Lyrics

​Higgsfield TTS

​Higgsfield Speak

​Rate Limiting

​Rate Limit Headers

​Rate Limit Error Response

​Error Responses

​Error Response Format

Create Task

Request

Request Parameters

Response

Dry Run

Get Task Status

Request

Path Parameters

Response (Processing)

Response (Completed)

Available Models

Video Generation

Image Generation

Audio Generation

Model Parameters

Google Veo 3.1

OpenAI Sora 2

Minimax Hailuo

Higgsfield Video

Higgsfield Cinematic Studio Video

Kling v2.6

Kling v2.5

Kling v2.1

Kling v2.1 Master

Kling O1 Video (Omni)

Kling v3.0 Omni Video

Kling v3.0 Omni Video Edit

Kling v2.6 Motion Control

GPT Image

Nano Banana

Flux.2

Higgsfield Cinematic Studio Image

Suno Music

Suno Audio Operations

Suno Stems

Suno Lyrics

Higgsfield TTS

Higgsfield Speak

Rate Limiting

Rate Limit Headers

Rate Limit Error Response

Error Responses

Error Response Format