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.

Response

{
  "code": 200,
  "success": true,
  "data": {
    "task_id": "abc123def456",
    "status": "pending"
  }
}

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`	Minimax Hailuo
`hailuo/minimax-fast`	Minimax Hailuo Fast
`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-2.6`	Kling v2.6
`kuaishou/kling-2.5-turbo`	Kling v2.5 Turbo
`kuaishou/kling-2.5-turbo-pro`	Kling v2.5 Turbo Pro
`kuaishou/kling-2.1-std`	Kling v2.1 Standard
`kuaishou/kling-2.1-pro`	Kling v2.1 Pro
`kuaishou/kling-2.1-master`	Kling v2.1 Master
`kuaishou/kling-o1-generate`	Kling O1 Generate
`kuaishou/kling-o1-edit`	Kling O1 Edit
`kuaishou/kling-2.6-motion-control`	Kling v2.6 Motion Control
`topaz/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
`topaz/image-upscale`	Topaz Image Upscale
`topaz/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
`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/audio-isolation`	ElevenLabs Audio Isolation
`elevenlabs/speech-to-text`	ElevenLabs Speech-to-Text

Model Parameters

All tasks support callback_url (outside the input object) for webhook notifications. When provided, a POST request is sent to your URL with status, task_id, and data (containing video_url, image_url, or audio_url) on completion, or error_message on failure.

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: 5s

0.05, 10s

0.10, 15s

0.15, 20s

0.20 | Pro: 10s

0.40, 15s

0.60, 20s

0.80, 25s

1.00

Minimax Hailuo

Models: hailuo/minimax, hailuo/minimax-fast, hailuo/minimax-2.3, hailuo/minimax-2.3-fast

Parameter	Type	Required	Description
`prompt`	string	Yes	Text description
`start_image_url`	string	Yes	Starting frame image URL
`end_image_url`	string	No	Ending frame (minimax/minimax-fast only)
`motion_id`	string	No	Motion preset ID
`duration`	integer	No	`6` or `10` seconds
`resolution`	string	No	`512`, `768`, `1080`
`enhance_prompt`	boolean	No	Enhance prompt with AI
`seed`	integer	No	Seed for reproducibility

Pricing: minimax/minimax-fast

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	Text description
`image_url`	string	No	Reference image to animate
`aspect_ratio`	string	No	`1:1`, `16:9`, `9:16`
`duration`	integer	No	Duration in seconds (default 5)
`motion_id`	string	No	Motion preset ID
`negative_prompt`	string	No	What to avoid
`enhance_prompt`	boolean	No	Enhance prompt (default true)
`sound`	boolean	No	Generate audio (default true)

Pricing:

0.032/s (5s:

0.16, 10s: $0.32)

Kling v2.5 Turbo

Models: kuaishou/kling-2.5-turbo, kuaishou/kling-2.5-turbo-pro

Parameter	Type	Required	Description
`prompt`	string	Yes	Text description
`start_image_url`	string	Yes	Starting image URL
`end_image_url`	string	No	Ending image (1080p only)
`duration`	integer	No	`5` or `10` seconds
`resolution`	string	No	`720p` (std) or `1080p` (pro)
`motion_id`	string	No	Motion preset ID
`enhance_prompt`	boolean	No	Enhance prompt
`seed`	integer	No	Seed for reproducibility

Pricing: Turbo: 5s

0.11, 10s

0.21 | Turbo Pro: 5s

0.16, 10s

0.32

Kling v2.1

Models: kuaishou/kling-2.1-std, kuaishou/kling-2.1-pro, kuaishou/kling-2.1-master

Parameter	Type	Required	Description
`prompt`	string	Yes	Text description
`start_image_url`	string	Yes	Starting image URL
`end_image_url`	string	No	Ending image (pro/master only)
`duration`	integer	No	`5` or `10` seconds
`resolution`	string	No	`720p` (std) or `1080p` (pro/master)
`motion_id`	string	No	Motion preset ID
`enhance_prompt`	boolean	No	Enhance prompt
`seed`	integer	No	Seed for reproducibility

Pricing: Std: 5s

0.13, 10s

0.27 | Pro: 5s

0.27, 10s

0.53 | Master: 5s

0.40, 10s

0.80

Kling O1 (Omni)

Models: kuaishou/kling-o1-generate, kuaishou/kling-o1-edit Generate Mode 1 - Reference Images:

Parameter	Type	Required	Description
`prompt`	string	Yes	Text description
`image_urls`	array	Yes	1-7 reference images
`aspect_ratio`	string	Yes	`1:1`, `9:16`, `16:9`
`duration`	integer	Yes	3-10 seconds
`resolution`	string	No	`720p` or `1080p`

Generate Mode 2 - Start/End Frame:

Parameter	Type	Required	Description
`prompt`	string	Yes	Text description
`start_image_url`	string	Yes	Starting frame
`end_image_url`	string	No	Ending frame
`aspect_ratio`	string	Yes	`1:1`, `9:16`, `16:9`
`duration`	integer	Yes	`5` or `10` seconds only
`resolution`	string	No	`720p` or `1080p`

Edit Mode (kling-o1-edit):

Parameter	Type	Required	Description
`prompt`	string	Yes	Edit/transformation description
`video_url`	string	Yes	Source video (3-10 seconds)
`image_urls`	array	No	Reference images (max 4)
`aspect_ratio`	string	Yes	`1:1`, `9:16`, `16:9`
`duration`	integer	Yes	3-10 seconds
`resolution`	string	No	`720p` or `1080p`

Pricing:

0.048/s (5s:

0.24, 10s: $0.48)

Kling v2.6 Motion Control

Model: kuaishou/kling-2.6-motion-control

Parameter	Type	Required	Description
`prompt`	string	Yes	Text description
`video_url`	string	Yes	Reference video (3-30 seconds)
`image_url`	string	Yes	Reference image (head/shoulders/torso visible)
`character_orientation`	string	Yes	`video` (max 30s output) or `image` (max 10s output)
`resolution`	string	No	`720p` or `1080p`
`seed`	integer	No	Seed for reproducibility

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

​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 Turbo

​Kling v2.1

​Kling O1 (Omni)

​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

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 Turbo

Kling v2.1

Kling O1 (Omni)

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