# Unifically — Complete Documentation

================================================================================
Introduction
================================================================================

<img
  className="block dark:hidden"
  src="https://unifically.com/static/logo.png"
  alt="Unifically Logo"
/>
<img
  className="hidden dark:block"
  src="https://unifically.com/static/logo.png"
  alt="Unifically Logo"
/>

## Welcome to Unifically

Unifically provides a **unified API** for accessing multiple AI models including:

- **Image Generation** - GPT Image, Nano Banana (Gemini 2.5 Flash), Flux.2
- **Video Generation** - Higgsfield, Veo 3.1, Kling 3.0/2.6/2.1, Minimax Hailuo 2.0
- **Audio Generation** - Suno API for music and voice, Higgsfield TTS

## For LLMs & AI Agents

Unifically publishes machine-readable docs that any LLM or coding agent can ingest directly:

- **`llms.txt`** — concise index of every page, ideal for in-context routing
- **`llms-full.txt`** — the entire documentation site as a single plain-text file

<CardGroup cols={2}>
  <Card
    title="llms.txt"
    icon="file-lines"
    href="/llms.txt"
  >
    Compact link index of the docs for LLM context
  </Card>
  <Card
    title="llms-full.txt"
    icon="file-lines"
    href="/llms-full.txt"
  >
    Full documentation as a single plain-text file
  </Card>
</CardGroup>

## Getting Started

<CardGroup cols={2}>
  <Card
    title="Get Your API Key"
    icon="key"
    href="https://unifically.com"
  >
    Sign up and get your API key to start using Unifically
  </Card>
  <Card
    title="Unified Tasks API"
    icon="code"
    href="/api-reference/v1-tasks"
  >
    Create and manage AI generation tasks with a unified interface
  </Card>
  <Card
    title="Image Models"
    icon="image"
    href="/models/image/openai/gpt-image-1"
  >
    GPT Image, Nano Banana, Flux.2, and more
  </Card>
  <Card
    title="Video Models"
    icon="video"
    href="/models/video/google/veo-3.1"
  >
    Veo 3.1, Kling, Higgsfield, and more
  </Card>
</CardGroup>

## Features

<AccordionGroup>
  <Accordion icon="layer-group" title="Unified Interface">
    One API endpoint (`/v1/tasks`) for all models - video, image, and audio generation
  </Accordion>

  <Accordion icon="key" title="Unified Authentication">
    One API key for all models - no need to manage multiple accounts
  </Accordion>

  <Accordion icon="bolt" title="Fast & Reliable">
    High-performance infrastructure with 99.9% uptime
  </Accordion>

  <Accordion icon="dollar-sign" title="Pay As You Go">
    No subscriptions - only pay for what you use
  </Accordion>

  <Accordion icon="code" title="Developer Friendly">
    Clean REST API with comprehensive documentation and examples
  </Accordion>
</AccordionGroup>

## Quick Start

```bash
# Create a task
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/veo-3.1-fast",
    "input": {
      "prompt": "A cat walking on the beach at sunset"
    }
  }'

# Check status
curl https://api.unifically.com/v1/tasks/{task_id} \
  -H "Authorization: Bearer YOUR_API_KEY"
```

<Note>
  Replace `YOUR_API_KEY` with your actual API key from [unifically.com](https://unifically.com)
</Note>

## Support

Need help? Check out the documentation sections or contact our support team at contact@unifically.com

================================================================================
Authentication
================================================================================

## API Key Authentication

All Unifically API endpoints require authentication using a Bearer token.

<Steps>
  <Step title="Get Your API Key">
    Sign up at [unifically.com](https://unifically.com) to get your API key
  </Step>
  <Step title="Add to Request Headers">
    Include your API key in the Authorization header of every request
  </Step>
</Steps>

## Authentication Header

```bash
Authorization: Bearer YOUR_API_KEY
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use Environment Variables">
    Never hardcode your API key. Always store it securely in environment variables or secrets management systems.
    
    ```bash
    export UNIFICALLY_API_KEY="your_api_key_here"
    ```
  </Accordion>

  <Accordion title="Keep Keys Secret">
    - Never commit API keys to version control
    - Don't share keys in public forums or documentation
    - Rotate keys regularly
    - Use separate keys for development and production
  </Accordion>

  <Accordion title="Handle Errors Gracefully">
    Always check for authentication errors and handle them appropriately in your application.
  </Accordion>
</AccordionGroup>

<Warning>
  If your API key is compromised, regenerate it immediately from your dashboard.
</Warning>

================================================================================
Unified Tasks API
================================================================================

The `/v1/tasks` endpoint provides a unified interface for all AI generation models (video, image, audio).

<Info>
  This is the unified API for all AI generation models. Use this endpoint for all integrations.
</Info>

## Create Task

**POST** `/v1/tasks`

Creates a new generation task for any supported model.

### Request

```bash
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

<ParamField body="model" type="string" required>
  Model identifier in `provider/model-name` format. See [Available Models](#available-models) below.
</ParamField>

<ParamField body="input" type="object" required>
  Model-specific input parameters. See [Input Parameters](#input-parameters) for details.
</ParamField>

<ParamField body="callback_url" type="string">
  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.
</ParamField>

<ParamField body="dry_run" type="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.
</ParamField>

### Response

<ResponseExample>
```json 200
{
  "code": 200,
  "success": true,
  "data": {
    "task_id": "abc123def456",
    "status": "pending"
  }
}
```
</ResponseExample>

### Dry Run

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

```bash
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
  }'
```

<ResponseExample>
```json 200
{
  "code": 200,
  "success": true,
  "data": {
    "cost": 0.40
  }
}
```
</ResponseExample>

---

## Get Task Status

**GET** `/v1/tasks/:task_id`

Retrieves the status and output of a task.

### Request

```bash
curl https://api.unifically.com/v1/tasks/abc123def456 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Path Parameters

<ParamField path="task_id" type="string" required>
  The unique task ID returned from the create task endpoint
</ParamField>

### Response (Processing)

<ResponseExample>
```json 200
{
  "code": 200,
  "success": true,
  "data": {
    "task_id": "abc123def456",
    "status": "processing"
  }
}
```
</ResponseExample>

### Response (Completed)

<ResponseExample>
```json 200
{
  "code": 200,
  "success": true,
  "data": {
    "task_id": "abc123def456",
    "status": "completed",
    "output": {
      "video_url": "https://cdn.unifically.com/outputs/abc123.mp4"
    }
  }
}
```
</ResponseExample>

---

## Available Models

### Video Generation

| Model | Description |
|-------|-------------|
| `google/veo-3.1-fast` | Google Veo 3.1 Fast |
| `google/veo-3.1-fast-relaxed` | Google Veo 3.1 Fast Relaxed |
| `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 |
| `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-3.5` | Cinematic Studio Video v3.5 |
| `higgsfield-ai/cinematic-studio-video-3.0` | Cinematic Studio Video v3.0 |
| `higgsfield-ai/cinematic-studio-video-2.5` | Cinematic Studio Video v2.5 |
| `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-o1-video-edit` | Kling O1 Video Edit |
| `kuaishou/kling-3.0-video` | Kling v3.0 Video |
| `kuaishou/kling-2.6-video` | Kling v2.6 Video |
| `kuaishou/kling-2.5-turbo-video` | Kling v2.5 Turbo Video |
| `kuaishou/kling-2.1-video` | Kling v2.1 Video |
| `kuaishou/kling-2.1-master-video` | Kling v2.1 Master Video |
| `kuaishou/kling-2.6-motion-control` | Kling v2.6 Motion Control |
| `kuaishou/kling-3.0-motion-control` | Kling v3.0 Motion Control |
| `xai/grok-imagine-video-extend` | Grok Imagine Video Extend |
| `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 (medium, high quality) |
| `openai/gpt-image-1.5` | GPT Image 1.5 (medium, high quality) |
| `openai/gpt-image-2` | GPT Image 2 (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 |
| `kuaishou/kling-3.0-image` | Kling v3.0 Image |
| `kuaishou/kling-2.1-image` | Kling v2.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) |

### 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/text-to-speech` | 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

<Tip>
  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.
</Tip>

### Google Veo 3.1

#### Generate

Models: `google/veo-3.1-fast`, `google/veo-3.1-fast-relaxed`, `google/veo-3.1-quality`, `google/veo-3.1-lite`, `google/veo-3.1-lite-relaxed`

There are two mutually exclusive image modes — the API rejects requests that mix them:

| Mode | Fields | Availability |
|------|--------|--------------|
| **Frame mode** | `start_image_url` [+ `end_image_url`] | All models |
| **Reference mode** | `reference_image_urls` [+ `voice`] | Fast model only |

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text prompt for video generation |
| `aspect_ratio` | string | No | `"16:9"` (default) or `"9:16"` |
| `seed` | integer | No | Reproducibility seed |
| `start_image_url` | string | No | Start frame image URL. **Cannot be combined with `reference_image_urls`** |
| `end_image_url` | string | No | End frame image URL. Requires `start_image_url`. **Cannot be combined with `reference_image_urls`** |
| `reference_image_urls` | string[] | No | 1–3 reference image URLs. **Fast model only. Cannot be combined with `start_image_url`/`end_image_url`** |
| `voice` | string | No | Voice preset ID. Requires at least 1 reference image. **Fast model only**. See [voices endpoint](/api-reference/resources#get-google-veo-voices) |

#### 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`, `fast-relaxed` |
| `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"` |

---

### 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 |

---

### Higgsfield Video

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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the desired video motion/action |
| `start_image_url` | string | Yes | Starting frame image URL |
| `end_image_url` | string | No | Ending frame image URL (for guided transitions) |
| `enhance_prompt` | boolean | No | Let AI enhance your prompt for better results (default false) |
| `seed` | integer | No | 0-999999 for reproducibility |
| `motion_id` | string | No | Motion preset ID (UUID) |

---

### Higgsfield Cinematic Studio Video v2.5

Model: `higgsfield-ai/cinematic-studio-video-2.5`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Conditional | Required for `single` and `multi_shot_auto` shot modes. Supports image refs `<<<image_1>>>` etc. |
| `shot_mode` | string | No | `single` (default), `multi_shot_auto`, `multi_shot_manual` |
| `multi_shots` | object[] | Conditional | Required for `multi_shot_manual`. Each: `prompt`, `duration`, optional `camera_movement_id` |
| `image_urls` | string[] | No | Reference image URLs (max 3) |
| `start_image_url` | string | No | Starting frame image URL |
| `end_image_url` | string | No | Ending frame URL. Forces `generate_audio` to `false` |
| `duration` | integer | No | 3-12 seconds (default 5) |
| `aspect_ratio` | string | No | `1:1`, `3:4`, `2:3`, `9:16`, `3:2`, `4:3`, `16:9`, `21:9` |
| `resolution` | string | No | `720p` (default) or `1080p` |
| `genre` | string | No | `auto`, `action`, `horror`, `comedy`, `western`, `suspense`, `intimate`, `spectacle` |
| `camera_movement_id` | string | No | Camera movement preset ID |
| `generate_audio` | boolean | No | Enable AI sound effects (default false) |
| `seed` | integer | No | 0-999999 for reproducibility |

---

### Higgsfield Cinematic Studio Video v3.0

Model: `higgsfield-ai/cinematic-studio-video-3.0`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Conditional | Required when `shot_mode` is `single` or `multi_shot_auto` |
| `shot_mode` | string | No | `single` (default), `multi_shot_auto`, `multi_shot_manual` |
| `multi_shots` | object[] | Conditional | Required when `shot_mode='multi_shot_manual'`. Each item carries its own `prompt`, `duration`, `camera_motion_id`, and `speedramp` (`ramp_up`, `flash_in`, `flash_out`, `hero_moment`) |
| `image_urls` | string[] | No | Up to 3 reference image URLs |
| `start_image_url` | string | No | Optional first-frame image |
| `end_image_url` | string | No | Optional last-frame image |
| `duration` | integer | No | Total video duration in seconds (4-15) |
| `aspect_ratio` | string | No | `auto` (default), `1:1`, `3:4`, `9:16`, `4:3`, `16:9`, `21:9` |
| `resolution` | string | No | `480p`, `720p`, `1080p` |
| `genre` | string | No | `general` (default), `action`, `horror`, `comedy`, `noir`, `epic` |
| `camera_motion_id` | string | No | Top-level camera movement preset id (sent as `preset_id`) |
| `generate_audio` | boolean | No | Generate accompanying audio |
| `seed` | integer | No | Random seed; auto-generated if omitted |

---

### Higgsfield Cinematic Studio Video v3.5

Model: `higgsfield-ai/cinematic-studio-video-3.5`

Single-shot only. Provide either a free-form `style_prompt` (which fully overrides the structured style fields) **or** the structured trio `color_palette` / `lighting` / `camera_moveset_style`.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | **Yes** | Required text prompt |
| `image_urls` | string[] | No | Up to 3 reference image URLs |
| `start_image_url` | string | No | Optional first-frame image |
| `end_image_url` | string | No | Optional last-frame image |
| `duration` | integer | No | Video duration in seconds (4-15) |
| `aspect_ratio` | string | No | `auto` (default), `1:1`, `3:4`, `9:16`, `4:3`, `16:9`, `21:9` |
| `resolution` | string | No | `480p`, `720p`, `1080p` |
| `genre` | string | No | `general` (default), `action`, `horror`, `comedy`, `noir`, `epic`, `drama` |
| `generate_audio` | boolean | No | Generate accompanying audio |
| `seed` | integer | No | Random seed; auto-generated if omitted |
| `style_prompt` | string | No | Free-form style description. **Fully overrides** `color_palette`, `lighting`, and `camera_moveset_style` when provided |
| `color_palette` | string | No | Color grading preset (sent as `color_grading`). Values: `auto`, `naturalistic_clean`, `bleached_warm`, `hyper_neon`, `teal_orange_epic`, `sodium_decay`, `cold_steel`, `bleach_bypass`, `classic_bw` |
| `lighting` | string | No | Lighting scheme (sent as `light_scheme`). Values: `auto`, `soft_cross`, `contre_jour`, `overhead_fall`, `window`, `practicals`, `silhouette` |
| `camera_moveset_style` | string | No | Camera moveset style (sent as `camera_style`). Values: `auto`, `classic_static`, `silent_machine`, `one_take`, `epic_scale`, … |
| `camera_motion_id` | string | No | Camera movement preset id (sent as `preset_id`) |
| `camera_model_id` | string | No | Camera body preset id (from `GET /higgsfield/camera-settings`) |
| `camera_lens_id` | string | No | Camera lens preset id |
| `camera_focal_length_id` | string | No | Camera focal length preset id |
| `camera_aperture_id` | string | No | Camera aperture preset id |

---

### Kling v3.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 v3.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 v3.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 v2.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 v2.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 v2.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 v2.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 v3.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 v2.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. 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-1`, `openai/gpt-image-1.5`, `openai/gpt-image-2`

| 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 | `medium`, `high` |

---

### 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) |

---

### Higgsfield Cinematic Studio Image

Model: `higgsfield-ai/cinematic-studio-image`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description |
| `image_urls` | string[] | No | Reference image URLs (max 4) |
| `aspect_ratio` | string | No | `1:1`, `3:4`, `2:3`, `9:16`, `3:2`, `4:3`, `16:9`, `21:9` (default: 16:9) |
| `resolution` | string | No | `1k`, `2k`, `4k` (default: 1k) |
| `seed` | integer | No | 0-999999 for reproducibility |
| `camera_model_id` | string | No | Camera body ID |
| `camera_lens_id` | string | No | Lens ID |
| `camera_aperture_id` | string | No | Aperture ID |
| `camera_focal_length_id` | string | No | Focal length ID |

---

### 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 |

---

### 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` |

---

### Higgsfield TTS

Model: `higgsfield-ai/text-to-speech`

| 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) |

---

### Rate Limit Error Response

```json
{
  "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
{
  "success": false,
  "code": 400,
  "data": {
    "message": "Description of the error",
    "request_id": "abc123"
  }
}
```

================================================================================
Webhooks & Callbacks
================================================================================

When creating tasks, you can provide a `callback_url` to receive webhook notifications when the task completes or fails. This avoids polling and lets you integrate with your backend asynchronously.

## Enabling Callbacks

Pass `callback_url` at the top level of your request (outside the `input` object):

```bash
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"
  }'
```

<ParamField body="callback_url" type="string">
  Optional webhook URL. When provided, the API sends a POST request to this URL when the task completes or fails.
</ParamField>

## Webhook Payload Format

The API sends a POST request to your `callback_url` with a JSON body. The payload structure depends on whether the task succeeded or failed.

### Success Payload

When the task completes successfully:

```json
{
  "task_id": "abc123def456",
  "status": "completed",
  "data": {
    "video_url": "https://cdn.unifically.com/outputs/abc123.mp4"
  }
}
```

The `data` object contains the output URL(s) based on the task type:

| Task Type | Output Field | Description |
|-----------|--------------|-------------|
| Video | `video_url` | URL to the generated video |
| Image | `image_url` | URL to the generated image |
| Audio | `audio_url` | URL to the generated audio |

Some models may return additional fields. For example, multi-output models might include `image_urls` or `audio_urls` as arrays.

### Failure Payload

When the task fails:

```json
{
  "task_id": "abc123def456",
  "status": "failed",
  "error_message": "Description of what went wrong"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `task_id` | string | The task ID |
| `status` | string | `"failed"` |
| `error_message` | string | Human-readable error description |

## Request Details

- **Method:** POST
- **Content-Type:** `application/json`
- **Body:** JSON payload as shown above

## Best Practices

1. **Respond quickly** — Return a 2xx status code within a few seconds to acknowledge receipt. Process the payload asynchronously if needed.
2. **Verify webhook origin** — Use HTTPS and consider validating requests (e.g., via a shared secret or signature if supported in the future).
3. **Handle duplicates** — The same webhook may be delivered more than once; use `task_id` to deduplicate.
4. **Validate URLs** — Ensure your callback URL is publicly accessible and accepts POST requests.

## Example Handler

```javascript
// Express.js example
app.post('/webhook', (req, res) => {
  const { task_id, status, data, error_message } = req.body;

  // Acknowledge immediately
  res.status(200).send('OK');

  if (status === 'completed') {
    const url = data.video_url || data.image_url || data.audio_url;
    console.log(`Task ${task_id} completed: ${url}`);
    // Process the completed task...
  } else if (status === 'failed') {
    console.error(`Task ${task_id} failed: ${error_message}`);
    // Handle the failure...
  }
});
```

================================================================================
Resources
================================================================================

The `/v1/resources` endpoint provides access to provider-specific resources such as motion presets, voices, and sounds that can be used with various models.

## Quick Reference

| Endpoint | Provider | Resource |
|----------|----------|----------|
| `GET /v1/resources/higgsfield-ai/motions` | Higgsfield | Motions |
| `GET /v1/resources/higgsfield-ai/voices` | Higgsfield | TTS voices |
| `GET /v1/resources/higgsfield-ai/sounds` | Higgsfield | Sound effects |
| `GET /v1/resources/higgsfield-ai/camera-movements` | Cinematic Studio | Camera movements |
| `GET /v1/resources/higgsfield-ai/camera-settings` | Cinematic Studio | Camera settings |
| `GET /v1/resources/kuaishou/kling/voices` | Kling | Kling voice presets |
| `GET /v1/resources/google/voices/veo-3.1` | Google | Veo 3.1 voice presets |
| `GET /v1/resources/elevenlabs/voices` | ElevenLabs | Voices |
| `GET /v1/resources/suno-ai/voice/verification-phrase` | Suno | Voice verification phrase |

---

## Examples

### Get Higgsfield Motions

```bash
curl https://api.unifically.com/v1/resources/higgsfield-ai/motions \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json
{
  "code": 200,
  "success": true,
  "data": [
    {
      "id": "d2389a9a-91c2-4276-bc9c-c9e35e8fb85a",
      "name": "Gentle Sway",
      "preview_url": "https://example.com/preview.mp4"
    }
  ]
}
```

### Get Higgsfield TTS Voices

```bash
curl https://api.unifically.com/v1/resources/higgsfield-ai/voices \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json
{
  "code": 200,
  "success": true,
  "data": [
    {
      "id": "1YxkwUwGY4H3slvZUBRhXW",
      "name": "Sarah",
      "category": "emotions",
      "preview_url": "https://example.com/preview.mp3"
    }
  ]
}
```

### Get Higgsfield Sound Effects

```bash
curl https://api.unifically.com/v1/resources/higgsfield-ai/sounds \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json
{
  "code": 200,
  "success": true,
  "data": [
    {
      "id": "DwUP9LmFKqHsvvWQkjLE6",
      "name": "Coffee Shop Ambience",
      "preview_url": "https://example.com/preview.mp3"
    }
  ]
}
```

### Get Cinematic Studio Camera Movements

```bash
curl https://api.unifically.com/v1/resources/higgsfield-ai/camera-movements \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Get Cinematic Studio Camera Settings

```bash
curl https://api.unifically.com/v1/resources/higgsfield-ai/camera-settings \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Get Kling Voices

Returns available voice presets for use with Kling video models that support `voice_id` (e.g. v2.6, v3.0, v3.0 Omni).

```bash
curl https://api.unifically.com/v1/resources/kuaishou/kling/voices \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json
{
  "code": 200,
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Male Voice 1"
    },
    {
      "id": 2,
      "name": "Female Voice 1"
    }
  ]
}
```

### Get Google Veo Voices

Returns available voice presets for use with Veo 3.1 reference mode (`voice` parameter). Requires at least 1 reference image in the task input.

```bash
curl https://api.unifically.com/v1/resources/google/voices/veo-3.1 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json
{
  "code": 200,
  "success": true,
  "data": [
    {
      "id": "achernar",
      "name": "Achernar",
      "description": "Female, soft, high pitch",
      "sample": "https://gstatic.com/aistudio/voices/samples/Achernar.wav"
    },
    {
      "id": "achird",
      "name": "Achird",
      "description": "Male, friendly, mid pitch",
      "sample": "https://gstatic.com/aistudio/voices/samples/Achird.wav"
    },
    {
      "id": "algenib",
      "name": "Algenib",
      "description": "Male, gravelly, low pitch",
      "sample": "https://gstatic.com/aistudio/voices/samples/Algenib.wav"
    }
  ]
}
```

### Get ElevenLabs Voices

```bash
curl https://api.unifically.com/v1/resources/elevenlabs/voices \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json
{
  "code": 200,
  "success": true,
  "data": {
    "voices": [
      {
        "voice_id": "21m00Tcm4TlvDq8ikWAM",
        "name": "Rachel",
        "category": "premade",
        "labels": {
          "accent": "american",
          "age": "young",
          "gender": "female"
        },
        "preview_url": "https://storage.googleapis.com/..."
      }
    ]
  }
}
```

### Get Suno Voice Verification Phrase

Generates a verification phrase for Suno voice creation.

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `language` | string | No | Language code for the phrase. Available: `zh`, `en`, `es`, `fr`, `pt`, `de`, `ja`, `ko`, `hi`, `ru` |

```bash
curl https://api.unifically.com/v1/resources/suno-ai/voice/verification-phrase?language=ru \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json
{
  "success": true,
  "code": 200,
  "data": {
    "phrase_id": "ea748c01-6257-45ff-a037-c8657ff5c09d",
    "phrase_text": "Sing a cheerful melody with your clear voice today"
  }
}
```

---

## Using Resources

Use the `id` value from the response as the corresponding parameter when creating a task:

| Resource Type | Use As Parameter |
|---------------|------------------|
| Motions | `motion_id` |
| Voices (Higgsfield/ElevenLabs) | `voice_id` or `voice` |
| Voices (Kling) | `voice_id` in elements or voices array |
| Voices (Google Veo) | `voice` |
| Sounds | `sound_id` |
| Camera Movements | `preset_id` |
| Camera Settings | `camera_model_id`, `camera_lens_id`, `camera_aperture_id`, `camera_focal_length_id` |
| Voice Verification Phrase | `phrase_id` |

================================================================================
Error Handling
================================================================================

## Response Structure

All Unifically API responses follow a consistent structure:

### Success Response

```json
{
  "success": true,
  "code": 200,
  "data": {
    // Response data
  }
}
```

### Error Response

```json
{
  "success": false,
  "code": 400,
  "data": {
    "message": "Error message"
  }
}
```

<Note>
Empty arrays and objects are omitted from responses when not needed.
</Note>

## HTTP Status Codes

| Code | Meaning | Description |
|------|---------|-------------|
| `200` | Success | Task successfully submitted |
| `400` | Bad Request | Task generation failed |
| `401` | Unauthorized | Invalid or missing API key |
| `422` | Validation Error | Invalid request parameters |
| `429` | Too Many Requests | Rate limit exceeded |
| `500` | Internal Server Error | Server error occurred |

## Error Response Format

When an error occurs, the API returns a simplified structure:

```json
{
  "success": false,
  "code": 400,
  "data": {
    "message": "Error message"
  }
}
```

### Response Fields

<ResponseField name="success" type="boolean">
  Indicates whether the request was successful (`true`) or failed (`false`)
</ResponseField>

<ResponseField name="code" type="integer">
  HTTP status code (200, 400, 401, 422, 429, 500)
</ResponseField>

<ResponseField name="data" type="object">
  Response data or error details
  
  <ResponseField name="message" type="string">
    Human-readable error message (on error)
  </ResponseField>
</ResponseField>

## Example Error Responses

<AccordionGroup>
  <Accordion title="Authentication Failed (401)">
    ```json
    {
      "success": false,
      "code": 401,
      "data": {
        "message": "Invalid API key provided"
      }
    }
    ```
    
    **Solution**: Verify your API key is correct and properly formatted in the Authorization header:
    
    ```bash
    Authorization: Bearer YOUR_ACTUAL_API_KEY
    ```
  </Accordion>

  <Accordion title="Rate Limit Exceeded (429)">
    ```json
    {
      "success": false,
      "code": 429,
      "data": {
        "message": "Rate limit exceeded. Please try again later"
      }
    }
    ```
    
    **Solution**: Implement exponential backoff and respect rate limits
  </Accordion>

  <Accordion title="Validation Error (422)">
    ```json
    {
      "success": false,
      "code": 422,
      "data": {
        "message": "Missing required parameter: prompt"
      }
    }
    ```
    
    **Solution**: Check the API documentation for required parameters and valid values
  </Accordion>

  <Accordion title="Generation Failed (400)">
    ```json
    {
      "success": false,
      "code": 400,
      "data": {
        "message": "Task generation failed"
      }
    }
    ```
    
    **Solution**: Review your request parameters and try again
  </Accordion>

  <Accordion title="Server Error (500)">
    ```json
    {
      "success": false,
      "code": 500,
      "data": {
        "message": "Internal server error occurred"
      }
    }
    ```
    
    **Solution**: Retry the request after a brief delay. Contact support if the issue persists
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Always Check Success Field" icon="check">
    Check the `success` field in every response to determine success or failure
  </Card>
  <Card title="Implement Retry Logic" icon="rotate">
    Retry failed requests with exponential backoff for 429 and 500 errors
  </Card>
  <Card title="Log Errors" icon="file-lines">
    Log all error responses including the error message for debugging
  </Card>
  <Card title="Handle Rate Limits" icon="gauge">
    Implement rate limit handling to avoid 429 errors
  </Card>
</CardGroup>

<Tip>
  Always parse the `error.message` field to provide helpful feedback to your users
</Tip>

<Warning>
  Never expose your API key in client-side code or public repositories
</Warning>

================================================================================
Account Information
================================================================================

Retrieve detailed information about your account, including balance, email, timestamps, and restrictions.

## Request

```bash
curl --location 'https://api.unifically.com/account' \
--header 'Authorization: Bearer YOUR_API_KEY'
```

## Response

### Success Response

```json
{
    "success": true,
    "code": 200,
    "data": {
        "user_id": 12345,
        "balance_usd": 100.50,
        "email": "user@example.com",
        "created_at": 123,
        "updated_at": 123,
    }
}
```

## Response Fields

<ResponseField name="success" type="boolean">
  Indicates whether the request was successful (`true`) or failed (`false`)
</ResponseField>

<ResponseField name="code" type="integer">
  HTTP status code (200 for success)
</ResponseField>

<ResponseField name="data" type="object">
  Account information
  
  <ResponseField name="user_id" type="integer">
    Unique user identifier
  </ResponseField>
  
  <ResponseField name="balance_usd" type="decimal">
    Current account balance in USD
  </ResponseField>
  
  <ResponseField name="email" type="string">
    Account email address
  </ResponseField>
  
  <ResponseField name="created_at" type="integer">
    Unix timestamp of account creation
  </ResponseField>
  
  <ResponseField name="updated_at" type="integer">
   Unix timestamp of last account update
  </ResponseField>
  
</ResponseField>

## Authentication

All requests require a valid API key in the Authorization header:

```
Authorization: Bearer YOUR_API_KEY
```

<Info>
Get your API key from the [Unifically Dashboard](https://unifically.com/dashboard).
</Info>

================================================================================
Storage Overview
================================================================================

Unifically provides flexible file storage with three upload methods to suit different use cases.

## Available Upload Methods

<CardGroup cols={3}>
  <Card title="Direct File Upload" icon="file-arrow-up" href="/api-reference/storage/direct-upload">
    Upload files directly from your local system using multipart/form-data
  </Card>
  <Card title="Base64 Upload" icon="binary" href="/api-reference/storage/base64-upload">
    Upload files as base64-encoded strings in JSON format
  </Card>
  <Card title="URL Upload" icon="link" href="/api-reference/storage/url-upload">
    Upload files by providing a publicly accessible URL
  </Card>
</CardGroup>

## Response Format

All upload methods return a consistent response format:

### Success Response

**Status Code:** `200 OK`

```json
{
  "success": true,
  "file_url": "https://files.storagecdn.online/image/2b847255-e028-4cf7-a2aa-c638f3e15cbc.webp"
}
```

### Error Response

**Status Code:** `400 Bad Request`

```json
{
  "success": false,
  "message": "Error message here"
}
```

## Authentication

All storage endpoints require a valid API key in the Authorization header:

```
Authorization: Bearer YOUR_API_KEY
```

Get your API key from the [Unifically Dashboard](https://unifically.com/dashboard).

================================================================================
Direct File Upload
================================================================================

Upload a file directly from your local system using multipart/form-data.

## Request

```bash
curl --location --request PUT 'https://files.storagecdn.online/upload' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--form 'file=@"/path/to/your/file.png"'
```

## Parameters

<ParamField path="file" type="File" required>
  The file to upload. Use `@` prefix followed by the file path
</ParamField>

## Example

```bash
curl --location --request PUT 'https://files.storagecdn.online/upload' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--form 'file=@"/Users/john/Documents/image.png"'
```

## Response

### Success Response

**Status Code:** `200 OK`

```json
{
  "success": true,
  "file_url": "https://files.storagecdn.online/image/2b847255-e028-4cf7-a2aa-c638f3e15cbc.webp"
}
```

<ResponseField name="success" type="boolean">
  Whether the upload was successful
</ResponseField>

<ResponseField name="file_url" type="string">
  URL to access the uploaded file
</ResponseField>

## Use Cases

- Uploading files from local file system
- Direct file uploads from applications
- Best for: Command-line uploads, server-to-server transfers

================================================================================
Base64 Upload
================================================================================

Upload a file as a base64-encoded string in JSON format. Base64 string can be either raw or data string.

## Request

```bash
curl --location --request PUT 'https://files.storagecdn.online/upload' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
}'
```

## Request Body

```json
{
  "base64": "YOUR_BASE64_ENCODED_FILE_STRING"
}
```

## Parameters

<ParamField body="base64" type="String" required>
  Base64-encoded file content
</ParamField>

## Example

```bash
curl --location --request PUT 'https://files.storagecdn.online/upload' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
}'
```

## Response

### Success Response

**Status Code:** `200 OK`

```json
{
  "success": true,
  "file_url": "https://files.storagecdn.online/image/2b847255-e028-4cf7-a2aa-c638f3e15cbc.webp"
}
```

<ResponseField name="success" type="boolean">
  Whether the upload was successful
</ResponseField>

<ResponseField name="file_url" type="string">
  URL to access the uploaded file
</ResponseField>

## Use Cases

- Uploading files from web applications
- When file is already in base64 format
- Best for: Browser-based uploads, embedded images, API integrations

## Notes

- Ensure your file is properly base64-encoded before sending
- Base64 encoding increases file size by approximately 33%
- Maximum file size may be limited by your API plan

================================================================================
URL Upload
================================================================================

Upload a file by providing a publicly accessible URL. The server will fetch and store the file.

## Request

```bash
curl --location --request PUT 'https://files.storagecdn.online/upload' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "file_url": "https://example.com/path/to/file.png"
}'
```

## Request Body

```json
{
  "file_url": "https://example.com/path/to/file.png"
}
```

## Parameters

<ParamField body="file_url" type="String (URL)" required>
  Publicly accessible URL of the file to upload
</ParamField>

## Example

```bash
curl --location --request PUT 'https://files.storagecdn.online/upload' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "file_url": "https://file.com/images/sample.png"
}'
```

## Response

### Success Response

**Status Code:** `200 OK`

```json
{
  "success": true,
  "file_url": "https://files.storagecdn.online/image/2b847255-e028-4cf7-a2aa-c638f3e15cbc.webp"
}
```

<ResponseField name="success" type="boolean">
  Whether the upload was successful
</ResponseField>

<ResponseField name="file_url" type="string">
  URL to access the uploaded file
</ResponseField>

## Use Cases

- Importing files from external sources
- Migrating files from other storage services
- Best for: Bulk imports, file migrations, webhook integrations

## Requirements

- The URL must be publicly accessible (no authentication required)
- The file must be directly downloadable
- HTTPS URLs are recommended

================================================================================
GPT Image 1
================================================================================

Generate high-quality images using GPT Image 1.

## Model

```
openai/gpt-image-1
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image to generate |
| `image_urls` | array | No | Reference images for context |
| `aspect_ratio` | string | No | `1:1`, `2:3`, `3:2` |
| `quality` | string | No | `medium`, `high` |

## Example Request

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "openai/gpt-image-1",
    "input": {
      "prompt": "A futuristic city at sunset",
      "aspect_ratio": "16:9",
      "quality": "high"
    }
  }'
```

## With Reference Images

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "openai/gpt-image-1",
    "input": {
      "prompt": "Make them hug",
      "image_urls": [
        "https://example.com/image1.png",
        "https://example.com/image2.png"
      ]
    }
  }'
```

## Response

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

================================================================================
GPT Image 1.5
================================================================================

Generate high-quality images using GPT Image 1.5 with improved capabilities.

## Model

```
openai/gpt-image-1.5
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image to generate |
| `image_urls` | array | No | Reference images for context |
| `aspect_ratio` | string | No | `1:1`, `2:3`, `3:2` |
| `quality` | string | No | `medium`, `high` |

## Example Request

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "openai/gpt-image-1.5",
    "input": {
      "prompt": "A serene mountain landscape",
      "aspect_ratio": "16:9",
      "quality": "high"
    }
  }'
```

## Response

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

================================================================================
GPT Image 2
================================================================================

Generate high-quality images using GPT Image 2 with improved capabilities.

## Model

```
openai/gpt-image-2
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image to generate |
| `image_urls` | array | No | Reference images for context |
| `aspect_ratio` | string | No | `1:1`, `2:3`, `3:2` |
| `quality` | string | No | `medium`, `high` |

## Example Request

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "openai/gpt-image-2",
    "input": {
      "prompt": "A serene mountain landscape",
      "aspect_ratio": "16:9",
      "quality": "high"
    }
  }'
```

## Response

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

================================================================================
Nano Banana
================================================================================

Generate images quickly using Nano Banana powered by Gemini 2.5 Flash.

## Model

```
google/nano-banana
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image |
| `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 |

## Example Request

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "google/nano-banana",
    "input": {
      "prompt": "A futuristic city skyline at sunset with flying cars",
      "aspect_ratio": "16:9"
    }
  }'
```

## With Reference Images

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "google/nano-banana",
    "input": {
      "prompt": "Transform this into anime style",
      "aspect_ratio": "1:1",
      "image_urls": ["https://example.com/reference.jpg"]
    }
  }'
```

## Response

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

================================================================================
Nano Banana Pro
================================================================================

Generate high-quality images using Nano Banana Pro powered by Gemini 3.

## Model

```
google/nano-banana-pro
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image |
| `aspect_ratio` | string | Yes | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
| `resolution` | string | No | `1k`, `2k`, `4k` |
| `image_urls` | array | No | Reference images |

## Example Request

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "google/nano-banana-pro",
    "input": {
      "prompt": "A photorealistic portrait in golden hour lighting",
      "aspect_ratio": "3:4",
      "resolution": "4k"
    }
  }'
```

## Response

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

================================================================================
Nano Banana 2
================================================================================

Generate high-quality images using Nano Banana 2, the latest generation of the Nano Banana Pro model.

## Model

```
google/nano-banana-2
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image |
| `aspect_ratio` | string | Yes | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
| `resolution` | string | No | `1k`, `2k`, `4k` |
| `image_urls` | array | No | Reference images |

## Example Request

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "google/nano-banana-2",
    "input": {
      "prompt": "A photorealistic portrait in golden hour lighting",
      "aspect_ratio": "3:4",
      "resolution": "4k"
    }
  }'
```

## Response

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

================================================================================
Flux.2 Pro
================================================================================

Generate high-quality images using Flux.2 Pro with balanced quality and speed.

## Model

```
black-forest-labs/flux.2-pro
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | Yes | - | Text description of the image |
| `aspect_ratio` | string | No | `"16:9"` | `"21:9"`, `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`, `"9:21"` |
| `resolution` | string | No | `"1mp"` | `"0.6mp"`, `"1mp"`, `"2mp"`, `"4mp"` |
| `image_urls` | string[] | No | `null` | Reference image URLs |

## Example Request

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "black-forest-labs/flux.2-pro",
    "input": {
      "prompt": "A photorealistic portrait of a woman in golden hour light",
      "aspect_ratio": "9:16",
      "resolution": "2mp"
    }
  }'
```

## With Reference Images

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "black-forest-labs/flux.2-pro",
    "input": {
      "prompt": "A portrait in this style",
      "image_urls": ["https://example.com/ref1.jpg", "https://example.com/ref2.jpg"],
      "resolution": "2mp"
    }
  }'
```

## Response

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

================================================================================
Flux.2 Flex
================================================================================

Generate images using Flux.2 Flex with advanced controls for guidance, steps, and reproducibility.

## Model

```
black-forest-labs/flux.2-flex
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | Yes | - | Text description of the image |
| `aspect_ratio` | string | No | `"16:9"` | `"21:9"`, `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`, `"9:21"` |
| `resolution` | string | No | `"1mp"` | `"0.6mp"`, `"1mp"`, `"2mp"`, `"4mp"` |
| `image_urls` | string[] | No | `null` | Reference image URLs |
| `guidance` | float | No | - | Guidance scale (e.g. `1.5`) |
| `steps` | integer | No | - | Number of generation steps |
| `seed` | integer | No | random | Seed for reproducibility |
| `prompt_upsampling` | boolean | No | `true` | Auto-enhance prompt for more creative output |

## Example Request

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "black-forest-labs/flux.2-flex",
    "input": {
      "prompt": "A cyberpunk city at night with neon reflections",
      "aspect_ratio": "21:9",
      "resolution": "2mp",
      "guidance": 1.5,
      "steps": 30,
      "seed": 124242,
      "prompt_upsampling": false
    }
  }'
```

## Response

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

================================================================================
Flux.2 Max
================================================================================

Generate the highest quality images using Flux.2 Max.

## Model

```
black-forest-labs/flux.2-max
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | Yes | - | Text description of the image |
| `aspect_ratio` | string | No | `"16:9"` | `"21:9"`, `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`, `"9:21"` |
| `resolution` | string | No | `"1mp"` | `"0.6mp"`, `"1mp"`, `"2mp"`, `"4mp"` |
| `image_urls` | string[] | No | `null` | Reference image URLs |

## Example Request

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "black-forest-labs/flux.2-max",
    "input": {
      "prompt": "A beautiful sunset over mountains",
      "aspect_ratio": "21:9",
      "resolution": "2mp"
    }
  }'
```

## With Reference Images

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "black-forest-labs/flux.2-max",
    "input": {
      "prompt": "Make him dance",
      "image_urls": ["https://example.com/photo.jpg"],
      "aspect_ratio": "9:16",
      "resolution": "2mp"
    }
  }'
```

## Response

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

================================================================================
Flux.2 Klein 9B
================================================================================

Generate images using the lightweight Flux.2 Klein 9B model for fast results.

## Model

```
black-forest-labs/flux.2-klein-9b
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | Yes | - | Text description of the image |
| `aspect_ratio` | string | No | `"16:9"` | `"21:9"`, `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`, `"9:21"` |
| `resolution` | string | No | `"1mp"` | `"0.6mp"`, `"1mp"`, `"2mp"`, `"4mp"` |
| `image_urls` | string[] | No | `null` | Reference image URLs |
| `seed` | integer | No | random | Seed for reproducibility |

<Note>Klein models do not support `guidance`, `steps`, or `prompt_upsampling`.</Note>

## Example Request

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "black-forest-labs/flux.2-klein-9b",
    "input": {
      "prompt": "A minimalist line drawing of a mountain landscape",
      "aspect_ratio": "16:9",
      "resolution": "1mp",
      "seed": 42
    }
  }'
```

## Response

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

================================================================================
Flux.2 Klein 4B
================================================================================

Generate images using the smallest and fastest Flux.2 Klein 4B model.

## Model

```
black-forest-labs/flux.2-klein-4b
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | Yes | - | Text description of the image |
| `aspect_ratio` | string | No | `"16:9"` | `"21:9"`, `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`, `"9:21"` |
| `resolution` | string | No | `"1mp"` | `"0.6mp"`, `"1mp"`, `"2mp"`, `"4mp"` |
| `image_urls` | string[] | No | `null` | Reference image URLs |
| `seed` | integer | No | random | Seed for reproducibility |

<Note>Klein models do not support `guidance`, `steps`, or `prompt_upsampling`.</Note>

## Example Request

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "black-forest-labs/flux.2-klein-4b",
    "input": {
      "prompt": "A simple icon of a coffee cup",
      "aspect_ratio": "1:1"
    }
  }'
```

## Response

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

================================================================================
Cinematic Studio Image
================================================================================

Generate cinematic images with professional camera models, lenses, apertures, and focal lengths.

## Model

```
higgsfield-ai/cinematic-studio-image
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image |
| `image_urls` | string[] | No | Reference image URLs (max 4) |
| `aspect_ratio` | string | No | `1:1`, `3:4`, `2:3`, `9:16`, `3:2`, `4:3`, `16:9`, `21:9`. Default: `16:9` |
| `resolution` | string | No | `1k`, `2k`, `4k` (default: `1k`). Scales the output dimensions of the chosen aspect ratio |
| `seed` | integer | No | 0-999999 for reproducibility |
| `camera_model_id` | string | No | Camera body ID from [Resources API](/api-reference/resources#higgsfield-ai) |
| `camera_lens_id` | string | No | Lens ID. Affects perspective and distortion |
| `camera_aperture_id` | string | No | Aperture ID. Controls depth of field |
| `camera_focal_length_id` | string | No | Focal length ID. Controls field of view |

## Example Request

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "higgsfield-ai/cinematic-studio-image",
    "input": {
      "prompt": "A serene mountain landscape at golden hour",
      "resolution": "4k",
      "aspect_ratio": "21:9"
    }
  }'
```

## With Camera Settings

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "higgsfield-ai/cinematic-studio-image",
    "input": {
      "prompt": "Portrait of a person in natural lighting",
      "aspect_ratio": "3:4",
      "resolution": "4k",
      "image_urls": ["https://example.com/reference.jpg"],
      "camera_model_id": "camera-model-uuid",
      "camera_lens_id": "camera-lens-uuid",
      "camera_aperture_id": "camera-aperture-uuid",
      "camera_focal_length_id": "camera-focal-length-uuid"
    }
  }'
```

## Response

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

================================================================================
Kling Omni Image
================================================================================

Generate high-quality AI images using Kling Omni Image models with support for up to 10 reference images.

## Models

| Model | Resolution | Aspect Ratio |
|-------|------------|--------------|
| `kuaishou/kling-o1-image` | `1k`, `2k` | No `4k` |
| `kuaishou/kling-3.0-omni-image` | `1k`, `2k`, `4k` | Adds `auto` (default) |

---

## Parameters

### O1 Image (`kuaishou/kling-o1-image`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | Yes | - | Text description. Use `@Image1`, `@Image2` to reference inputs |
| `resolution` | string | No | `"1k"` | `"1k"`, `"2k"` |
| `aspect_ratio` | string | No | `"auto"` | `"auto"`, `"1:1"`, `"16:9"`, `"9:16"`, `"4:3"`, `"3:4"`, `"3:2"`, `"2:3"`, `"21:9"` |
| `image_urls` | string[] | No | - | Reference image URLs (max 10). Use `@Image1`, `@Image2` in prompt |

### v3.0 Omni Image (`kuaishou/kling-3.0-omni-image`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | Yes | - | Text description. Use `@Image1`, `@Image2` to reference inputs |
| `resolution` | string | No | `"1k"` | `"1k"`, `"2k"`, `"4k"` |
| `aspect_ratio` | string | No | `"auto"` | `"auto"`, `"1:1"`, `"16:9"`, `"9:16"`, `"4:3"`, `"3:4"`, `"3:2"`, `"2:3"`, `"21:9"` |
| `image_urls` | string[] | No | - | Reference image URLs (max 10). Use `@Image1`, `@Image2` in prompt |

## Example - Text-to-Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-o1-image",
    "input": {
      "prompt": "A serene mountain landscape at sunset, photorealistic",
      "aspect_ratio": "16:9",
      "resolution": "2k"
    }
  }'
```

## Example - With Reference Images

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-3.0-omni-image",
    "input": {
      "prompt": "Transform @Image1 into a watercolor painting style",
      "image_urls": ["https://example.com/reference.jpg"],
      "aspect_ratio": "auto",
      "resolution": "2k"
    }
  }'
```

## Response

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

================================================================================
Kling v3.0 Image
================================================================================

Generate high-quality AI images using Kling v3.0 Image with support for batch generation of up to 4 images and up to 10 reference images.

## Model

```
kuaishou/kling-3.0-image
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | Yes | - | Text description. Use `@Image1`, `@Image2` to reference inputs |
| `resolution` | string | No | `"2k"` | `"1k"` or `"2k"` |
| `aspect_ratio` | string | No | `"auto"` | `"auto"`, `"1:1"`, `"16:9"`, `"9:16"`, `"4:3"`, `"3:4"`, `"3:2"`, `"2:3"`, `"21:9"` |
| `count` | integer | No | `1` | Number of images to generate (1–4) |
| `image_urls` | string[] | No | - | Reference image URLs (max 10). Use `@Image1`, `@Image2` in prompt |

## Example - Text-to-Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-3.0-image",
    "input": {
      "prompt": "A serene mountain landscape at sunset, photorealistic",
      "aspect_ratio": "16:9",
      "resolution": "2k",
      "count": 4
    }
  }'
```

## Example - With Reference Images

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-3.0-image",
    "input": {
      "prompt": "Transform @Image1 into a watercolor painting style",
      "image_urls": ["https://example.com/reference.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "2k"
    }
  }'
```

## Response

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

================================================================================
Kling v2.1 Image
================================================================================

Generate high-quality AI images using Kling v2.1 Image with 4 reference modes for flexible image generation.

## Model

```
kuaishou/kling-2.1-image
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | Yes | - | Text description of the image to generate |
| `reference_mode` | string | No | `"restyle"` | Reference strategy: `"restyle"`, `"portrait"`, `"character"`, or `"elements"` |
| `image_url` | string | Conditional | - | Source image URL. Required for restyle, portrait, and character modes |
| `aspect_ratio` | string | No | `"1:1"` | `"21:9"`, `"16:9"`, `"3:2"`, `"4:3"`, `"1:1"`, `"3:4"`, `"2:3"`, `"9:16"` |
| `fidelity` | float | No | `0.5` | How closely to follow the reference image (0.0–1.0) |
| `human_fidelity` | float | No | `0.65` | Face similarity preservation strength (0.0–1.0, portrait mode only) |
| `elements` | string[] | Conditional | - | Element image/video URLs (2–4 required for elements mode) |
| `scene_url` | string | No | - | Background scene image URL (elements mode only) |
| `style_url` | string | No | - | Style reference image URL (elements mode only) |

## Mode Requirements

- **`restyle`** — requires `image_url`. Uses `fidelity` to control reference adherence
- **`portrait`** — requires `image_url`. Uses `fidelity` and `human_fidelity` for face control
- **`character`** — requires `image_url`. Uses `fidelity` only
- **`elements`** — requires 2–4 `elements` URLs. Optionally accepts `scene_url` and `style_url`

## Example - Restyle Mode

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-2.1-image",
    "input": {
      "prompt": "Transform into an oil painting with vivid colors",
      "reference_mode": "restyle",
      "image_url": "https://example.com/photo.jpg",
      "fidelity": 0.7,
      "aspect_ratio": "16:9"
    }
  }'
```

## Example - Portrait Mode

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-2.1-image",
    "input": {
      "prompt": "Professional headshot in a modern office setting",
      "reference_mode": "portrait",
      "image_url": "https://example.com/face.jpg",
      "fidelity": 0.5,
      "human_fidelity": 0.8,
      "aspect_ratio": "1:1"
    }
  }'
```

## Example - Elements Mode

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-2.1-image",
    "input": {
      "prompt": "Two characters standing in a futuristic city",
      "reference_mode": "elements",
      "elements": [
        "https://example.com/character1.jpg",
        "https://example.com/character2.jpg"
      ],
      "scene_url": "https://example.com/city-bg.jpg",
      "style_url": "https://example.com/cyberpunk-style.jpg",
      "aspect_ratio": "16:9"
    }
  }'
```

## Response

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

================================================================================
SeeDream 5.0 Lite
================================================================================

Generate images using ByteDance SeeDream 5.0 Lite with support for up to 6 reference images, resolutions up to 4K, and 8 aspect ratios.

## Model

```
bytedance/seedream-5.0-lite
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | **Yes** | — | Text description of the image to generate |
| `image_urls` | string[] | No | `null` | Reference image URLs for image-to-image mode (max 6) |
| `aspect_ratio` | string | No | `"1:1"` | `1:1`, `3:4`, `4:3`, `9:16`, `16:9`, `2:3`, `3:2`, `21:9` |
| `resolution` | string | No | `"2k"` | `1k`, `2k`, or `4k` |
| `seed` | integer | No | random | Seed for reproducibility |

## Example - Text-to-Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedream-5.0-lite",
    "input": {
      "prompt": "A cyberpunk city at sunset, neon lights reflecting on wet streets",
      "aspect_ratio": "16:9",
      "resolution": "2k"
    }
  }'
```

## Example - Image-to-Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedream-5.0-lite",
    "input": {
      "prompt": "Place the animal inside the vintage car",
      "image_urls": [
        "https://example.com/animal.jpg",
        "https://example.com/car.jpg"
      ]
    }
  }'
```

Each generation returns **4 images**.

## Response

```json
{
  "success": true,
  "code": 200,
  "data": {
    "task_id": "9d489f02-316f-4386-8188-dc19540d56f5",
    "status": "completed",
    "output": {
      "image_urls": [
        "https://files.storagecdn.online/image/92116e95-8dd4-4cbb-b53f-ee643e1045d8.jpg",
        "https://files.storagecdn.online/image/42eaa39a-a305-4d5d-a542-a6579dc5514d.jpg",
        "https://files.storagecdn.online/image/974167b1-4a7a-4258-ab01-dd46064ae036.jpg",
        "https://files.storagecdn.online/image/aa7765bd-ce24-46a6-8be9-cc9e281f7e87.jpg"
      ]
    }
  }
}
```

================================================================================
SeeDream 4.6
================================================================================

Generate images using ByteDance SeeDream 4.6 with support for up to 6 reference images, resolutions up to 4K, and 8 aspect ratios.

## Model

```
bytedance/seedream-4.6
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | **Yes** | — | Text description of the image to generate |
| `image_urls` | string[] | No | `null` | Reference image URLs for image-to-image mode (max 6) |
| `aspect_ratio` | string | No | `"1:1"` | `1:1`, `3:4`, `4:3`, `9:16`, `16:9`, `2:3`, `3:2`, `21:9` |
| `resolution` | string | No | `"2k"` | `1k`, `2k`, or `4k` |
| `seed` | integer | No | random | Seed for reproducibility |

## Example - Text-to-Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedream-4.6",
    "input": {
      "prompt": "A serene Japanese garden with cherry blossoms and a stone bridge",
      "aspect_ratio": "4:3",
      "resolution": "4k"
    }
  }'
```

## Example - Image-to-Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedream-4.6",
    "input": {
      "prompt": "Transform the scene into a watercolor painting style",
      "image_urls": ["https://example.com/photo.jpg"],
      "resolution": "2k"
    }
  }'
```

Each generation returns **4 images**.

## Response

```json
{
  "success": true,
  "code": 200,
  "data": {
    "task_id": "9d489f02-316f-4386-8188-dc19540d56f5",
    "status": "completed",
    "output": {
      "image_urls": [
        "https://files.storagecdn.online/image/92116e95-8dd4-4cbb-b53f-ee643e1045d8.jpg",
        "https://files.storagecdn.online/image/42eaa39a-a305-4d5d-a542-a6579dc5514d.jpg",
        "https://files.storagecdn.online/image/974167b1-4a7a-4258-ab01-dd46064ae036.jpg",
        "https://files.storagecdn.online/image/aa7765bd-ce24-46a6-8be9-cc9e281f7e87.jpg"
      ]
    }
  }
}
```

================================================================================
SeeDream 4.5
================================================================================

Generate images using ByteDance SeeDream 4.5 with support for up to 6 reference images, resolutions up to 4K, and 8 aspect ratios.

## Model

```
bytedance/seedream-4.5
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | **Yes** | — | Text description of the image to generate |
| `image_urls` | string[] | No | `null` | Reference image URLs for image-to-image mode (max 6) |
| `aspect_ratio` | string | No | `"1:1"` | `1:1`, `3:4`, `4:3`, `9:16`, `16:9`, `2:3`, `3:2`, `21:9` |
| `resolution` | string | No | `"2k"` | `1k`, `2k`, or `4k` |
| `seed` | integer | No | random | Seed for reproducibility |

## Example - Text-to-Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedream-4.5",
    "input": {
      "prompt": "A magical forest with glowing mushrooms and fireflies",
      "resolution": "4k",
      "aspect_ratio": "1:1"
    }
  }'
```

## Example - Image-to-Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedream-4.5",
    "input": {
      "prompt": "Transform into a fantasy art style with vibrant colors",
      "image_urls": ["https://example.com/reference.jpg"],
      "resolution": "4k",
      "aspect_ratio": "16:9"
    }
  }'
```

Each generation returns **4 images**.

## Response

```json
{
  "success": true,
  "code": 200,
  "data": {
    "task_id": "9d489f02-316f-4386-8188-dc19540d56f5",
    "status": "completed",
    "output": {
      "image_urls": [
        "https://files.storagecdn.online/image/92116e95-8dd4-4cbb-b53f-ee643e1045d8.jpg",
        "https://files.storagecdn.online/image/42eaa39a-a305-4d5d-a542-a6579dc5514d.jpg",
        "https://files.storagecdn.online/image/974167b1-4a7a-4258-ab01-dd46064ae036.jpg",
        "https://files.storagecdn.online/image/aa7765bd-ce24-46a6-8be9-cc9e281f7e87.jpg"
      ]
    }
  }
}
```

================================================================================
SeeDream 4.1
================================================================================

Generate images using ByteDance SeeDream 4.1 with support for up to 6 reference images, resolutions up to 4K, and 8 aspect ratios.

## Model

```
bytedance/seedream-4.1
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | **Yes** | — | Text description of the image to generate |
| `image_urls` | string[] | No | `null` | Reference image URLs for image-to-image mode (max 6) |
| `aspect_ratio` | string | No | `"1:1"` | `1:1`, `3:4`, `4:3`, `9:16`, `16:9`, `2:3`, `3:2`, `21:9` |
| `resolution` | string | No | `"2k"` | `1k`, `2k`, or `4k` |
| `seed` | integer | No | random | Seed for reproducibility |

## Example - Text-to-Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedream-4.1",
    "input": {
      "prompt": "An astronaut floating above Earth with the Milky Way in the background",
      "aspect_ratio": "16:9",
      "resolution": "2k"
    }
  }'
```

## Example - Image-to-Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedream-4.1",
    "input": {
      "prompt": "Add dramatic lighting and cinematic atmosphere",
      "image_urls": ["https://example.com/reference.jpg"],
      "aspect_ratio": "16:9",
      "resolution": "2k"
    }
  }'
```

Each generation returns **4 images**.

## Response

```json
{
  "success": true,
  "code": 200,
  "data": {
    "task_id": "9d489f02-316f-4386-8188-dc19540d56f5",
    "status": "completed",
    "output": {
      "image_urls": [
        "https://files.storagecdn.online/image/92116e95-8dd4-4cbb-b53f-ee643e1045d8.jpg",
        "https://files.storagecdn.online/image/42eaa39a-a305-4d5d-a542-a6579dc5514d.jpg",
        "https://files.storagecdn.online/image/974167b1-4a7a-4258-ab01-dd46064ae036.jpg",
        "https://files.storagecdn.online/image/aa7765bd-ce24-46a6-8be9-cc9e281f7e87.jpg"
      ]
    }
  }
}
```

================================================================================
SeeDream 4.0
================================================================================

Generate images using ByteDance SeeDream 4.0 with support for up to 6 reference images, resolutions up to 4K, and 8 aspect ratios.

## Model

```
bytedance/seedream-4.0
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | **Yes** | — | Text description of the image to generate |
| `image_urls` | string[] | No | `null` | Reference image URLs for image-to-image mode (max 6) |
| `aspect_ratio` | string | No | `"1:1"` | `1:1`, `3:4`, `4:3`, `9:16`, `16:9`, `2:3`, `3:2`, `21:9` |
| `resolution` | string | No | `"2k"` | `1k`, `2k`, or `4k` |
| `seed` | integer | No | random | Seed for reproducibility |

## Example - Text-to-Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedream-4.0",
    "input": {
      "prompt": "A futuristic cityscape at night with neon lights",
      "aspect_ratio": "16:9",
      "resolution": "2k"
    }
  }'
```

## Example - Image-to-Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedream-4.0",
    "input": {
      "prompt": "Add dramatic lighting and cinematic atmosphere",
      "image_urls": ["https://example.com/reference.jpg"],
      "aspect_ratio": "16:9",
      "resolution": "2k"
    }
  }'
```

Each generation returns **4 images**.

## Response

```json
{
  "success": true,
  "code": 200,
  "data": {
    "task_id": "9d489f02-316f-4386-8188-dc19540d56f5",
    "status": "completed",
    "output": {
      "image_urls": [
        "https://files.storagecdn.online/image/92116e95-8dd4-4cbb-b53f-ee643e1045d8.jpg",
        "https://files.storagecdn.online/image/42eaa39a-a305-4d5d-a542-a6579dc5514d.jpg",
        "https://files.storagecdn.online/image/974167b1-4a7a-4258-ab01-dd46064ae036.jpg",
        "https://files.storagecdn.online/image/aa7765bd-ce24-46a6-8be9-cc9e281f7e87.jpg"
      ]
    }
  }
}
```

================================================================================
Topaz Image Upscale
================================================================================

Upscale and enhance images using AI-powered presets with support for up to 16x scaling, multiple AI models, and face enhancement.

## Model

```
topaz-labs/image-upscale
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `image_url` | string | Yes | - | URL of the image to upscale |
| `upscale_factor` | string | No | `1x` | `1x`, `2x`, `4x`, `8x`, or `16x` |
| `denoise` | float | No | `0.5` | Denoise strength (0.0–1.0) |
| `sharpen` | float | No | `0.5` | Sharpen strength (0.0–1.0) |
| `face_enhancement` | boolean | No | `true` | Enable face enhancement |

## Upscale Factors

| Factor | Description | Example |
|--------|-------------|---------|
| `1x` | Original resolution (enhancement only) | 500x500 → 500x500 |
| `2x` | 2x dimensions | 500x500 → 1000x1000 |
| `4x` | 4x dimensions | 500x500 → 2000x2000 |
| `8x` | 8x dimensions | 500x500 → 4000x4000 |
| `16x` | 16x dimensions | 500x500 → 8000x8000 |

## Example - Basic Upscale

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "topaz-labs/image-upscale",
    "input": {
      "image_url": "https://example.com/photo.jpg",
      "upscale_factor": "4x"
    }
  }'
```

## Example - High-Fidelity Upscale

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "topaz-labs/image-upscale",
    "input": {
      "image_url": "https://example.com/photo.jpg",
      "upscale_factor": "8x",
      "denoise": 0.1,
      "sharpen": 0.3
    }
  }'
```

## Example - Portrait with Face Enhancement

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "topaz-labs/image-upscale",
    "input": {
      "image_url": "https://example.com/portrait.jpg",
      "upscale_factor": "4x",
      "face_enhancement": true
    }
  }'
```

## Example - Text and Screenshot

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "topaz-labs/image-upscale",
    "input": {
      "image_url": "https://example.com/screenshot.png",
      "upscale_factor": "2x",
      "sharpen": 0.6
    }
  }'
```

## Example - Anime/CG Art

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "topaz-labs/image-upscale",
    "input": {
      "image_url": "https://example.com/anime.png",
      "upscale_factor": "16x",
      "sharpen": 0.7
    }
  }'
```

## Example - Full Enhancement

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "topaz-labs/image-upscale",
    "input": {
      "image_url": "https://example.com/photo.jpg",
      "upscale_factor": "4x",
      "denoise": 0.3,
      "sharpen": 0.5,
      "face_enhancement": true
    }
  }'
```

## Response

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

================================================================================
Grok Imagine Image
================================================================================

Generate and edit images using xAI's Grok Imagine model. Supports text-to-image generation and reference-based image editing.

## Model

```
xai/grok-imagine-image
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | Yes | — | Text description or edit instruction |
| `aspect_ratio` | string | No | `"1:1"` | `"1:1"`, `"2:3"`, `"3:2"`, `"9:16"`, `"16:9"` |
| `image_urls` | string[] | No | `null` | 1–5 reference image URLs (triggers edit mode) |
| `enable_pro` | boolean | No | `false` | Enable pro mode for higher quality results |
| `upsample_prompt` | boolean | No | `false` | Let AI enhance your prompt for better results |
| `enable_nsfw` | boolean | No | `false` | Enable NSFW content generation |

When `image_urls` is provided, the model runs in **edit mode** — it merges or edits the reference images based on your prompt. Otherwise it generates a new image from the prompt.

## Example Request

### Text to Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "xai/grok-imagine-image",
    "input": {
      "prompt": "A robot dancing in a field of sunflowers",
      "aspect_ratio": "16:9"
    }
  }'
```

### Image Editing

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "xai/grok-imagine-image",
    "input": {
      "prompt": "Merge these images into one scene",
      "image_urls": [
        "https://example.com/img1.jpg",
        "https://example.com/img2.jpg"
      ]
    }
  }'
```

Text-to-image returns **6 images** as `image_urls`. Image editing returns a single `image_url`.

## Response (Text to Image)

```json
{
  "code": 200,
  "success": true,
  "data": {
    "task_id": "abc123def456",
    "status": "completed",
    "output": {
      "image_urls": [
        "https://files.storagecdn.online/image/92116e95-8dd4-4cbb-b53f-ee643e1045d8.jpg",
        "https://files.storagecdn.online/image/42eaa39a-a305-4d5d-a542-a6579dc5514d.jpg",
        "https://files.storagecdn.online/image/974167b1-4a7a-4258-ab01-dd46064ae036.jpg",
        "https://files.storagecdn.online/image/aa7765bd-ce24-46a6-8be9-cc9e281f7e87.jpg",
        "https://files.storagecdn.online/image/5c3a7e12-1f8b-4d9a-bc2e-7f6d4e3a1b09.jpg",
        "https://files.storagecdn.online/image/d8e2f1a4-6b3c-4a7e-9d5f-2c8b1e4a7f03.jpg"
      ]
    }
  }
}
```

## Response (Image Editing)

```json
{
  "code": 200,
  "success": true,
  "data": {
    "task_id": "abc123def456",
    "status": "completed",
    "output": {
      "image_url": "https://files.storagecdn.online/image/92116e95-8dd4-4cbb-b53f-ee643e1045d8.jpg"
    }
  }
}
```

================================================================================
Qwen Image 2.0 Pro
================================================================================

Generate the highest quality AI images using Qwen Image 2.0 Pro with best-in-class text rendering, semantic adherence, and realistic textures. Supports text-to-image and image editing via reference images.

## Model

```
alibaba/qwen-image-2.0-pro
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image (max 800 chars) |
| `aspect_ratio` | string | No | `1:1`, `16:9`, `9:16`, `4:3`, `3:4` (default: `1:1`) |
| `image_urls` | array | No | Input image URLs for editing or multi-image fusion |
| `negative_prompt` | string | No | What to avoid in the image (max 500 chars) |
| `prompt_extend` | boolean | No | Smart prompt rewriting (default: `true`) |
| `seed` | integer | No | Seed for reproducibility |

## Example - Text-to-Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/qwen-image-2.0-pro",
    "input": {
      "prompt": "A cinematic portrait of a fox in autumn forest, golden hour lighting",
      "aspect_ratio": "16:9"
    }
  }'
```

## Example - Image Editing

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/qwen-image-2.0-pro",
    "input": {
      "prompt": "Change the background to a beach at sunset",
      "image_urls": ["https://example.com/photo.jpg"],
      "aspect_ratio": "4:3"
    }
  }'
```

## Example - Multi-Image Fusion

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/qwen-image-2.0-pro",
    "input": {
      "prompt": "The girl from Image 1 wears the dress from Image 2",
      "image_urls": ["https://example.com/girl.jpg", "https://example.com/dress.jpg"]
    }
  }'
```

## Response

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

================================================================================
Qwen Image 2.0
================================================================================

Generate AI images using Qwen Image 2.0, a faster accelerated version of 2.0 Pro. Supports text-to-image and image editing via reference images with the same capabilities at a lower price.

## Model

```
alibaba/qwen-image-2.0
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image (max 800 chars) |
| `aspect_ratio` | string | No | `1:1`, `16:9`, `9:16`, `4:3`, `3:4` (default: `1:1`) |
| `image_urls` | array | No | Input image URLs for editing or multi-image fusion |
| `negative_prompt` | string | No | What to avoid in the image (max 500 chars) |
| `prompt_extend` | boolean | No | Smart prompt rewriting (default: `true`) |
| `seed` | integer | No | Seed for reproducibility |

## Example - Text-to-Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/qwen-image-2.0",
    "input": {
      "prompt": "Watercolor painting of a cozy bookshop interior",
      "aspect_ratio": "1:1"
    }
  }'
```

## Example - Image Editing

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/qwen-image-2.0",
    "input": {
      "prompt": "Add a rainbow in the sky behind the mountains",
      "image_urls": ["https://example.com/landscape.jpg"]
    }
  }'
```

## Response

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

================================================================================
Qwen Image Max
================================================================================

Generate photorealistic AI images using Qwen Image Max. Produces the highest realism with the fewest AI artifacts. Supports text-to-image and image editing via a specialized edit model under the hood (industrial design, geometric reasoning, character consistency).

## Model

```
alibaba/qwen-image-max
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image (max 800 chars) |
| `aspect_ratio` | string | No | `1:1`, `16:9`, `9:16`, `4:3`, `3:4` (default: `1:1`) |
| `image_urls` | array | No | Input image URLs for editing. Omit for text-to-image |
| `negative_prompt` | string | No | What to avoid in the image (max 500 chars) |
| `prompt_extend` | boolean | No | Smart prompt rewriting (default: `true`) |
| `seed` | integer | No | Seed for reproducibility |

## Example - Text-to-Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/qwen-image-max",
    "input": {
      "prompt": "Photorealistic close-up of a bumblebee on a lavender flower",
      "aspect_ratio": "4:3"
    }
  }'
```

## Example - Image Editing

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/qwen-image-max",
    "input": {
      "prompt": "Change the dress to red",
      "image_urls": ["https://example.com/photo.jpg"]
    }
  }'
```

## Response

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

================================================================================
Qwen Image Plus
================================================================================

Generate AI images in diverse artistic styles using Qwen Image Plus. Fast generation optimized for creative and stylistic variety. Supports text-to-image and image editing via a specialized edit model under the hood.

## Model

```
alibaba/qwen-image-plus
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image (max 800 chars) |
| `aspect_ratio` | string | No | `1:1`, `16:9`, `9:16`, `4:3`, `3:4` (default: `1:1`) |
| `image_urls` | array | No | Input image URLs for editing. Omit for text-to-image |
| `negative_prompt` | string | No | What to avoid in the image (max 500 chars) |
| `prompt_extend` | boolean | No | Smart prompt rewriting (default: `true`) |
| `seed` | integer | No | Seed for reproducibility |

## Example - Text-to-Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/qwen-image-plus",
    "input": {
      "prompt": "Art deco poster of a jazz musician playing saxophone",
      "aspect_ratio": "9:16"
    }
  }'
```

## Example - Image Editing

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/qwen-image-plus",
    "input": {
      "prompt": "Replace the background with a neon-lit cityscape",
      "image_urls": ["https://example.com/photo.jpg"]
    }
  }'
```

## Response

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

================================================================================
Qwen Image
================================================================================

Generate AI images using Qwen Image, the base model in the Qwen image family. Supports text-to-image and image editing via a specialized edit model under the hood.

## Model

```
alibaba/qwen-image
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image (max 800 chars) |
| `aspect_ratio` | string | No | `1:1`, `16:9`, `9:16`, `4:3`, `3:4` (default: `1:1`) |
| `image_urls` | array | No | Input image URLs for editing. Omit for text-to-image |
| `negative_prompt` | string | No | What to avoid in the image (max 500 chars) |
| `prompt_extend` | boolean | No | Smart prompt rewriting (default: `true`) |
| `seed` | integer | No | Seed for reproducibility |

## Example - Text-to-Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/qwen-image",
    "input": {
      "prompt": "A serene Japanese garden with cherry blossoms",
      "aspect_ratio": "16:9"
    }
  }'
```

## Example - Image Editing

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/qwen-image",
    "input": {
      "prompt": "Add snow falling in the scene",
      "image_urls": ["https://example.com/photo.jpg"]
    }
  }'
```

## Response

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

================================================================================
Z-Image Turbo
================================================================================

Generate AI images quickly using Z-Image Turbo. Lightweight and fast text-to-image model with Chinese and English text rendering. Does not support image editing.

## Model

```
alibaba/z-image-turbo
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image (max 800 chars) |
| `aspect_ratio` | string | No | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9` (default: `1:1`) |
| `prompt_extend` | boolean | No | Prompt rewriting (default: `false`). Enabling doubles cost |
| `seed` | integer | No | Seed for reproducibility |

## Example

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/z-image-turbo",
    "input": {
      "prompt": "Stylish young woman in front of a cartoon mural",
      "aspect_ratio": "3:4"
    }
  }'
```

## Response

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

================================================================================
Wan 2.7 Pro
================================================================================

Generate the highest quality AI images using Wan 2.7 Pro Image. Features thinking mode for text-to-image, supports editing with up to 9 reference images, and up to 4K resolution.

## Model

```
alibaba/wan-2.7-pro-image
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image (max 5000 chars) |
| `aspect_ratio` | string | No | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3` (default: `1:1`). Editing preserves input ratio |
| `image_urls` | array | 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 |

## Example - Text-to-Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.7-pro-image",
    "input": {
      "prompt": "A flower shop with exquisite windows and flowers on display",
      "aspect_ratio": "16:9"
    }
  }'
```

## Example - Image Editing

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.7-pro-image",
    "input": {
      "prompt": "Change the dress to a red evening gown",
      "image_urls": ["https://example.com/photo.jpg"]
    }
  }'
```

## Response

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

================================================================================
Wan 2.7
================================================================================

Generate AI images using Wan 2.7 Image, a faster variant of Wan 2.7 Pro. Same capabilities with max 2K resolution. Supports text-to-image and editing.

## Model

```
alibaba/wan-2.7-image
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image (max 5000 chars) |
| `aspect_ratio` | string | No | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3` (default: `1:1`). Editing preserves input ratio |
| `image_urls` | array | 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 |

## Example - Text-to-Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.7-image",
    "input": {
      "prompt": "A cozy cabin in the mountains surrounded by pine trees",
      "aspect_ratio": "16:9"
    }
  }'
```

## Example - Image Editing

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.7-image",
    "input": {
      "prompt": "Add a sunset sky behind the mountains",
      "image_urls": ["https://example.com/landscape.jpg"]
    }
  }'
```

## Response

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

================================================================================
Wan 2.6
================================================================================

Generate AI images using Wan 2.6 Image. Automatically selects T2I or editing mode based on whether `image_urls` is provided. Supports style transfer with 1–4 reference images.

## Model

```
alibaba/wan-2.6-image
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image (max 2000 chars) |
| `aspect_ratio` | string | No | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9` (default: `1:1`) |
| `image_urls` | array | No | Omit for T2I. 1–4 images for editing/style transfer |
| `negative_prompt` | string | No | What to avoid in the image (max 500 chars) |
| `prompt_extend` | boolean | No | Smart prompt rewriting (default: `true`) |
| `seed` | integer | No | Seed for reproducibility |

## Example - Text-to-Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.6-image",
    "input": {
      "prompt": "A cozy reading nook with warm lighting"
    }
  }'
```

## Example - Style Transfer

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.6-image",
    "input": {
      "prompt": "Generate a tomato stir-fry in the style of this image",
      "image_urls": ["https://example.com/style.png"]
    }
  }'
```

## Response

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

================================================================================
Wan 2.5
================================================================================

Generate AI images using Wan 2.5 Image. Automatically selects T2I or editing mode based on whether `image_urls` is provided. Supports 1–3 reference images for editing.

## Model

```
alibaba/wan-2.5-image
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image (max 2000 chars) |
| `aspect_ratio` | string | No | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9` (default: `1:1`) |
| `image_urls` | array | No | Omit for T2I. 1–3 images for editing |
| `negative_prompt` | string | No | What to avoid in the image (max 500 chars) |
| `prompt_extend` | boolean | No | Smart prompt rewriting (default: `true`) |
| `seed` | integer | No | Seed for reproducibility |

## Example - Text-to-Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.5-image",
    "input": {
      "prompt": "A flower shop with a beautiful wooden door"
    }
  }'
```

## Example - Image Editing

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.5-image",
    "input": {
      "prompt": "Change the floral dress to a vintage lace dress",
      "image_urls": ["https://example.com/photo.jpg"]
    }
  }'
```

## Response

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

================================================================================
Wan 2.2
================================================================================

Generate AI images using Wan 2.2 Image. Text-to-image only — does not support image editing.

## Model

```
alibaba/wan-2.2-image
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image (max 500 chars) |
| `aspect_ratio` | string | No | `1:1`, `3:4`, `4:3`, `9:16`, `16:9` (default: `1:1`) |
| `negative_prompt` | string | No | What to avoid in the image |
| `seed` | integer | No | Seed for reproducibility |

## Example

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.2-image",
    "input": {
      "prompt": "Aurora borealis over a snowy chapel, soft light",
      "aspect_ratio": "16:9"
    }
  }'
```

## Response

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

================================================================================
Wan 2.2 Flash
================================================================================

Generate AI images quickly using Wan 2.2 Flash Image. The fastest and cheapest Wan image model. Text-to-image only — does not support image editing.

## Model

```
alibaba/wan-2.2-flash-image
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image (max 500 chars) |
| `aspect_ratio` | string | No | `1:1`, `3:4`, `4:3`, `9:16`, `16:9` (default: `1:1`) |
| `negative_prompt` | string | No | What to avoid in the image |
| `seed` | integer | No | Seed for reproducibility |

## Example

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.2-flash-image",
    "input": {
      "prompt": "A minimalist logo design for a coffee shop"
    }
  }'
```

## Response

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

================================================================================
Grok Imagine Video
================================================================================

Generate high-quality AI videos using xAI's Grok Imagine model.

## Model

```
xai/grok-imagine-video
```

## Parameters

| Parameter | Type | Required | Default | Allowed Values | Description |
|-----------|------|----------|---------|----------------|-------------|
| `prompt` | string | Yes | — | — | Video generation prompt |
| `aspect_ratio` | string | No | `"1:1"` | `"1:1"`, `"2:3"`, `"3:2"`, `"9:16"`, `"16:9"` | Output aspect ratio |
| `duration` | int | No | `10` | `1`–`10` | Video duration in seconds |
| `resolution` | string | No | `"720p"` | `"480p"`, `"720p"` | Output resolution |
| `image_url` | string | No | `null` | — | Reference image URL (optional) |
| `video_preset` | string | No | `"custom"` | `"custom"`, `"spicy"`, `"fun"`, `"normal"` | Generation style preset |

**Video presets:**

| Preset | Style |
|--------|-------|
| `custom` | Default generation |
| `spicy` | Extremely spicy/nsfw |
| `fun` | Extremely crazy/fun |
| `normal` | Normal style |

## Example Request

### Text to Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "xai/grok-imagine-video",
    "input": {
      "prompt": "A futuristic cityscape at sunset with flying cars",
      "duration": 10,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "video_preset": "custom"
    }
  }'
```

### Image to Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "xai/grok-imagine-video",
    "input": {
      "prompt": "Camera slowly zooms in while clouds move across the sky",
      "image_url": "https://example.com/landscape.jpg",
      "duration": 6,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'
```

## Response

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

================================================================================
Grok Imagine Video Edit
================================================================================

Edit videos using xAI's Grok Imagine model. Provide an input video and a prompt describing the desired changes.

## Model

```
xai/grok-imagine-video-edit
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | Yes | — | Text description of the edit to apply |
| `video_url` | string | Yes | — | URL of the input video to edit |

<Note>
The maximum input video length is **8.7 seconds**. The `duration`, `aspect_ratio`, and `resolution` parameters are not supported — the output retains the duration and aspect ratio of the input and matches its resolution (capped at 720p).
</Note>

## Example Request

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "xai/grok-imagine-video-edit",
    "input": {
      "prompt": "Make the sky turn purple and add shooting stars",
      "video_url": "https://files.storagecdn.online/video/d0ff305c-0200-4d27-9b94-d183ebc91a7c.mp4"
    }
  }'
```

## Response

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

================================================================================
Grok Imagine Video Extend
================================================================================

Extend a previously generated video using xAI's Grok Imagine model via HTTP streaming. Provide the `task_id` of a completed video generation and choose between **preset mode** or **custom mode**.

## Model

```
xai/grok-imagine-video-extend
```

## Modes

There are two mutually exclusive modes:

| Mode | How to activate | Behaviour |
|------|----------------|-----------|
| **Preset** | Provide `video_preset` | The preset controls the video style. `prompt`, `extend_at`, and `extend_duration` are ignored |
| **Custom** | Omit `video_preset` | You control timing and prompt. `prompt`, `extend_at`, and `extend_duration` are required |

## Parameters

| 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 in the source video to start the extension from. **Required in custom mode** |
| `extend_duration` | int | No | Length of the extension: `6` or `10` seconds. **Required in custom mode** |

## Example Requests

### Preset Mode

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "xai/grok-imagine-video-extend",
    "input": {
      "task_id": "abc123def456",
      "video_preset": "spicy"
    }
  }'
```

### Custom Mode

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "xai/grok-imagine-video-extend",
    "input": {
      "task_id": "abc123def456",
      "prompt": "The camera continues panning right to reveal a mountain range",
      "extend_at": 8.5,
      "extend_duration": 10
    }
  }'
```

## Response

```json
{
  "code": 200,
  "success": true,
  "data": {
    "task_id": "xyz789ghi012",
    "status": "pending"
  }
}
```

================================================================================
Veo 3.1
================================================================================

Generate high-quality AI videos using Google's Veo 3.1 model. Available in multiple variants for generation, extending, and upscaling.

## Models

| Model | Description |
|-------|-------------|
| `google/veo-3.1-fast` | Faster generation (~100s), supports reference images + voice |
| `google/veo-3.1-fast-relaxed` | Fast with lower priority, supports reference images + voice |
| `google/veo-3.1-quality` | Higher quality (~240s) |
| `google/veo-3.1-lite` | Lightweight generation (~110s), supports reference images + voice |
| `google/veo-3.1-lite-relaxed` | Lite with lower priority, supports reference images + voice |
| `google/veo-3.1-extend` | Extend a previously generated video |
| `google/veo-3.1-upscale` | Upscale a completed video to 1080p or 4K |

## Video Modes

There are two mutually exclusive image modes. You must pick one or the other — the API rejects requests that mix them.

| Mode | Fields | Availability |
|------|--------|--------------|
| **Frame mode** | `start_image_url` [+ `end_image_url`] | All models |
| **Reference mode** | `reference_image_urls` [+ `voice`] | Fast, Fast-relaxed, Lite, and Lite-relaxed |

<Warning>
  Frame mode fields (`start_image_url`, `end_image_url`) and reference mode fields (`reference_image_urls`) cannot be combined in the same request.
</Warning>

## Generate Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text prompt for video generation |
| `aspect_ratio` | string | No | `"16:9"` (default) or `"9:16"` |
| `seed` | integer | No | Reproducibility seed |
| `start_image_url` | string | No | Start frame image URL. **Cannot be combined with `reference_image_urls`** |
| `end_image_url` | string | No | End frame image URL. Requires `start_image_url`. **Cannot be combined with `reference_image_urls`** |
| `reference_image_urls` | string[] | No | 1–3 reference image URLs. **Fast, Fast-relaxed, Lite, and Lite-relaxed only. Cannot be combined with `start_image_url`/`end_image_url`** |
| `voice` | string | No | Voice preset ID. Requires at least 1 reference image. **Fast, Fast-relaxed, Lite, and Lite-relaxed only**. See [available voices](/api-reference/resources#get-google-veo-voices) |

## Text-to-Video

```bash
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 cinematic shot of a cat walking through a garden",
      "aspect_ratio": "16:9"
    }
  }'
```

## Quality Model

```bash
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-quality",
    "input": {
      "prompt": "Cinematic drone shot over mountains",
      "aspect_ratio": "16:9"
    }
  }'
```

## Frame Mode (Image-to-Video)

Use `start_image_url` and optionally `end_image_url` to guide the video with start/end frames. Available on all models.

```bash
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": "Camera slowly zooms in",
      "start_image_url": "https://example.com/start.jpg",
      "end_image_url": "https://example.com/end.jpg",
      "aspect_ratio": "16:9"
    }
  }'
```

## Reference Mode (Fast & Lite Models)

Use `reference_image_urls` to provide 1–3 reference images as ingredients for the video. Optionally add a `voice` preset.

<Info>
  Reference mode and the `voice` parameter are available on `google/veo-3.1-fast`, `google/veo-3.1-fast-relaxed`, `google/veo-3.1-lite`, and `google/veo-3.1-lite-relaxed`. Not supported on the Quality variant.
</Info>

```bash
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 person explains quantum physics in a lab",
      "reference_image_urls": [
        "https://example.com/ref1.jpg",
        "https://example.com/ref2.jpg"
      ],
      "voice": "achernar",
      "aspect_ratio": "16:9"
    }
  }'
```

## Extend

Extend a previously generated video using `google/veo-3.1-extend`. The 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`, `fast-relaxed` |
| `seed` | integer | No | Reproducibility seed |

```bash
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-extend",
    "input": {
      "prompt": "The camera continues to pan across the landscape",
      "task_id": "abc123def456",
      "model": "fast"
    }
  }'
```

## Upscale

Upscale a completed video to a higher resolution using `google/veo-3.1-upscale`.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task_id` | string | Yes | Task ID of a completed generation |
| `resolution` | string | Yes | `"1080p"` or `"4k"` |

```bash
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-upscale",
    "input": {
      "task_id": "abc123def456",
      "resolution": "4k"
    }
  }'
```

## Response

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

================================================================================
Minimax Hailuo
================================================================================

Generate high-quality AI videos using Minimax Hailuo models.

## Models

| Model | Description |
|-------|-------------|
| `hailuo/minimax-2.0` | MiniMax 02 — T2V and I2V with end frame support |
| `hailuo/minimax-2.3` | MiniMax 2.3 — auto-selects T2V or I2V |
| `hailuo/minimax-2.3-fast` | MiniMax I2V-2.3-Fast — faster image-to-video |

## Parameters

### minimax-2.0

| 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` |
| `end_image_url` | string | No | End frame image URL (768p/1080p only) |
| `duration` | integer | No | `6` (default) or `10`. 1080p only supports `6` |
| `resolution` | string | No | `"512p"`, `"768p"` (default), `"1080p"` |
| `prompt_optimization` | boolean | No | Let MiniMax optimize prompt |

- **512p** requires `start_image_url` (I2V only)
- **1080p** only supports `duration: 6`
- **end_image_url** only with 768p or 1080p
- At minimum one of `prompt` or `start_image_url` must be provided

### minimax-2.3

| 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` |
| `duration` | integer | No | `6` (default) or `10`. 1080p only supports `6` |
| `resolution` | string | No | `"768p"` (default), `"1080p"` |
| `prompt_optimization` | boolean | No | Let MiniMax optimize prompt |

Auto-selects **T2V-2.3** (prompt only) or **I2V-2.3** (when `start_image_url` is provided).

### minimax-2.3-fast

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | No | Max 2000 chars |
| `start_image_url` | string | **Yes** | Image URL (auto-uploaded) |
| `duration` | integer | No | `6` (default) or `10`. 1080p only supports `6` |
| `resolution` | string | No | `"768p"` (default), `"1080p"` |
| `prompt_optimization` | boolean | No | Let MiniMax optimize prompt |

## Resolution Limits

| Model | 6s Duration | 10s Duration |
|-------|-------------|--------------|
| minimax-2.0 | 512p (I2V only), 768p, 1080p | 512p (I2V only), 768p only |
| minimax-2.3 / minimax-2.3-fast | 768p, 1080p | 768p only |

## Example Request

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "hailuo/minimax-2.0",
    "input": {
      "prompt": "A beautiful sunset animation",
      "start_image_url": "https://example.com/sunset.jpg",
      "duration": 6,
      "resolution": "1080p"
    }
  }'
```

## With End Image (minimax-2.0 only)

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "hailuo/minimax-2.0",
    "input": {
      "prompt": "Smooth transition between scenes",
      "start_image_url": "https://example.com/start.jpg",
      "end_image_url": "https://example.com/end.jpg",
      "duration": 6
    }
  }'
```

## Response

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

================================================================================
Higgsfield Video
================================================================================

Generate high-quality AI videos from images using Higgsfield's Video models with motion templates.

## Models

| Model | Speed | Quality |
|-------|-------|---------|
| `higgsfield-ai/lite` | 6x Slower | Basic |
| `higgsfield-ai/turbo` | 1.5x Faster | Medium |
| `higgsfield-ai/standard` | Normal | Best |

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the desired video motion/action |
| `start_image_url` | string | Yes | Starting frame image URL |
| `end_image_url` | string | No | Ending frame image URL (for guided transitions) |
| `enhance_prompt` | boolean | No | Let AI enhance your prompt for better results. Default: `false` |
| `seed` | integer | No | 0-999999 for reproducibility |
| `motion_id` | string | No | [Motion preset ID](/api-reference/resources#higgsfield-ai) (UUID) |

## Example Request

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "higgsfield-ai/turbo",
    "input": {
      "prompt": "A beautiful sunset animation",
      "start_image_url": "https://example.com/start.jpg",
      "motion_id": "d2389a9a-91c2-4276-bc9c-c9e35e8fb85a"
    }
  }'
```

## With End Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "higgsfield-ai/standard",
    "input": {
      "prompt": "Smooth transition between scenes",
      "start_image_url": "https://example.com/start.jpg",
      "end_image_url": "https://example.com/end.jpg",
      "motion_id": "d2389a9a-91c2-4276-bc9c-c9e35e8fb85a",
      "enhance_prompt": true
    }
  }'
```

## Response

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

## Resources

Get available motion presets from the [Resources API](/api-reference/resources):

```
GET /v1/resources/higgsfield-ai/motions
```

================================================================================
Cinematic Studio Video v3.5
================================================================================

Cinematic Studio Video v3.5 is a single-shot model that adds the v3.5 style controls: either a free-form `style_prompt` (which fully overrides everything) **or** the structured trio `color_palette` / `lighting` / `camera_moveset_style` (each can be left as `auto`). It also exposes the full Higgsfield camera body, lens, focal length, and aperture preset slots.

## Model

```
higgsfield-ai/cinematic-studio-video-3.5
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | **Yes** | Required text prompt |
| `image_urls` | string[] | No | Up to 3 reference image URLs |
| `start_image_url` | string | No | Optional first-frame image |
| `end_image_url` | string | No | Optional last-frame image |
| `duration` | integer | No | Video duration in seconds (4-15) |
| `aspect_ratio` | string | No | `auto` (default), `1:1`, `3:4`, `9:16`, `4:3`, `16:9`, `21:9` |
| `resolution` | string | No | `480p`, `720p`, `1080p` |
| `genre` | string | No | `general` (default), `action`, `horror`, `comedy`, `noir`, `epic`, `drama` |
| `generate_audio` | boolean | No | Generate accompanying audio |
| `seed` | integer | No | Random seed; auto-generated if omitted |
| `style_prompt` | string | No | Free-form style description. **When provided it FULLY OVERRIDES `color_palette`, `lighting`, and `camera_moveset_style`** |
| `color_palette` | string | No | Color grading preset. Sent as `color_grading` upstream. Ignored if `style_prompt` is set. Values: `auto`, `naturalistic_clean`, `bleached_warm`, `hyper_neon`, `teal_orange_epic`, `sodium_decay`, `cold_steel`, `bleach_bypass`, `classic_bw` |
| `lighting` | string | No | Lighting scheme. Sent as `light_scheme` upstream. Ignored if `style_prompt` is set. Values: `auto`, `soft_cross`, `contre_jour`, `overhead_fall`, `window`, `practicals`, `silhouette` |
| `camera_moveset_style` | string | No | Camera moveset style. Sent as `camera_style` upstream. Ignored if `style_prompt` is set. Values: `auto`, `classic_static`, `silent_machine`, `one_take`, `epic_scale`, … |
| `camera_motion_id` | string | No | Camera movement preset id (sent as `preset_id`) |
| `camera_model_id` | string | No | Camera body preset id (from `GET /higgsfield/camera-settings`) |
| `camera_lens_id` | string | No | Camera lens preset id |
| `camera_focal_length_id` | string | No | Camera focal length preset id |
| `camera_aperture_id` | string | No | Camera aperture preset id |

## Notes

Calls Higgsfield `/jobs/v2/cinematic_studio_video_3_5`.

**Public → wire field renames:**

| Public field | Wire field |
|-------------|-----------|
| `color_palette` | `color_grading` |
| `lighting` | `light_scheme` |
| `camera_moveset_style` | `camera_style` |
| `camera_motion_id` | `preset_id` |

This model is **single-shot only** — there is no `shot_mode` or `multi_shots` parameter.

## Example - Structured Style

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "higgsfield-ai/cinematic-studio-video-3.5",
    "input": {
      "prompt": "A lone detective walks through a rain-soaked alley at night",
      "duration": 8,
      "aspect_ratio": "21:9",
      "resolution": "1080p",
      "genre": "noir",
      "color_palette": "teal_orange_epic",
      "lighting": "contre_jour",
      "camera_moveset_style": "one_take",
      "generate_audio": true
    }
  }'
```

## Example - Free-form Style Prompt

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "higgsfield-ai/cinematic-studio-video-3.5",
    "input": {
      "prompt": "A cyberpunk samurai meditates on a rooftop overlooking neon Tokyo",
      "style_prompt": "Wong Kar-wai style: smeary highlights, step-printed motion, jewel-tone neons reflected in puddles, intimate handheld framing",
      "duration": 10,
      "aspect_ratio": "16:9",
      "resolution": "1080p",
      "genre": "drama",
      "generate_audio": true
    }
  }'
```

## Example - With Camera Body and Lens Presets

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "higgsfield-ai/cinematic-studio-video-3.5",
    "input": {
      "prompt": "Wide anamorphic shot of a desert at golden hour",
      "duration": 6,
      "aspect_ratio": "21:9",
      "resolution": "1080p",
      "genre": "epic",
      "camera_model_id": "<camera-body-preset-id>",
      "camera_lens_id": "<lens-preset-id>",
      "camera_focal_length_id": "<focal-length-preset-id>",
      "camera_aperture_id": "<aperture-preset-id>",
      "camera_motion_id": "<motion-preset-id>"
    }
  }'
```

## Response

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

================================================================================
Cinematic Studio Video v3.0
================================================================================

Cinematic Studio Video v3.0 adds per-shot speedramp control, native audio generation, an expanded resolution range (480p / 720p / 1080p), and a refreshed genre set.

## Model

```
higgsfield-ai/cinematic-studio-video-3.0
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Conditional | Text prompt. **Required** when `shot_mode` is `single` or `multi_shot_auto` |
| `shot_mode` | string | No | `single` (default), `multi_shot_auto`, `multi_shot_manual`. `single` and `multi_shot_auto` produce the same wire payload (auto cuts). `multi_shot_manual` requires the `multi_shots` array |
| `multi_shots` | object[] | Conditional | **Required** when `shot_mode='multi_shot_manual'`. Each item carries its own speedramp + camera movement. See [Multi-Shot Manual](#multi-shot-manual) below |
| `image_urls` | string[] | No | Up to 3 reference image URLs |
| `start_image_url` | string | No | Optional first-frame image |
| `end_image_url` | string | No | Optional last-frame image |
| `duration` | integer | No | Total video duration in seconds (4-15) |
| `aspect_ratio` | string | No | `auto` (default — model picks; otherwise dims are derived from the ratio), `1:1`, `3:4`, `9:16`, `4:3`, `16:9`, `21:9` |
| `resolution` | string | No | `480p`, `720p`, `1080p` |
| `genre` | string | No | `general` (default), `action`, `horror`, `comedy`, `noir`, `epic` |
| `camera_motion_id` | string | No | Top-level camera movement preset id (sent as `preset_id`) |
| `generate_audio` | boolean | No | Generate accompanying audio |
| `seed` | integer | No | Random seed; auto-generated if omitted |

## Shot Modes

**Single (default)**

Standard single-shot video generation. Requires `prompt`.

**Multi-Shot Auto**

Produces the same wire payload as `single` (auto cuts). Requires `prompt`.

**Multi-Shot Manual**

User defines each shot individually via `multi_shots`. Each shot can have its own speedramp and camera movement.

### Multi-Shot Manual

Each item in `multi_shots` accepts:

| Field | Type | Description |
|-------|------|-------------|
| `prompt` | string | Per-shot text prompt |
| `duration` | integer | Per-shot duration in seconds |
| `camera_motion_id` | string | Camera movement preset id (sent as `preset_id`) |
| `speedramp` | string | One of `ramp_up`, `flash_in`, `flash_out`, `hero_moment`. Wire mapping: `ramp_up` → `speedup`, `flash_in` → `fast_to_slowmo`, `flash_out` → `slowmo_to_fast`, `hero_moment` → `impact` |

## Notes

Calls Higgsfield `/jobs/v2/cinematic_studio_3_0`. A single-shot request is internally mapped to `multi_shots=true`, `multi_shot_mode=auto`, `multi_prompt=[]` per Higgsfield's wire format.

## Example - Single Shot

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "higgsfield-ai/cinematic-studio-video-3.0",
    "input": {
      "prompt": "A cinematic dolly shot through a neon-lit alley at night",
      "duration": 8,
      "aspect_ratio": "16:9",
      "resolution": "1080p",
      "genre": "noir",
      "generate_audio": true
    }
  }'
```

## Example - With Reference Images and Camera Motion

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "higgsfield-ai/cinematic-studio-video-3.0",
    "input": {
      "prompt": "Hero walks toward camera in slow motion",
      "image_urls": [
        "https://example.com/ref1.jpg",
        "https://example.com/ref2.jpg"
      ],
      "camera_motion_id": "fc583228-7a2e-4e94-8c3b-38962895e99d",
      "duration": 6,
      "aspect_ratio": "21:9",
      "resolution": "1080p",
      "genre": "epic",
      "generate_audio": true
    }
  }'
```

## Example - Multi-Shot Manual with Speedramps

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "higgsfield-ai/cinematic-studio-video-3.0",
    "input": {
      "shot_mode": "multi_shot_manual",
      "multi_shots": [
        {
          "prompt": "Wide establishing shot of a futuristic city skyline",
          "duration": 4,
          "camera_motion_id": "fc583228-7a2e-4e94-8c3b-38962895e99d",
          "speedramp": "ramp_up"
        },
        {
          "prompt": "Close-up of the protagonist looking up at the skyline",
          "duration": 5,
          "speedramp": "hero_moment"
        },
        {
          "prompt": "Sudden snap cut to a dramatic reveal",
          "duration": 4,
          "speedramp": "flash_out"
        }
      ],
      "aspect_ratio": "16:9",
      "resolution": "1080p",
      "genre": "action",
      "generate_audio": true
    }
  }'
```

## Response

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

================================================================================
Cinematic Studio Video v2.5
================================================================================

Generate cinematic videos with camera movement presets, multi-shot support, genres, and AI sound effects.

## Model

```
higgsfield-ai/cinematic-studio-video-2.5
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Conditional | Text description. **Required** for `single` and `multi_shot_auto` shot modes. Can include image references like `<<<image_1>>>`, `<<<image_2>>>`, `<<<image_3>>>` |
| `shot_mode` | string | No | Controls multi-shot behavior: `single` (default), `multi_shot_auto`, `multi_shot_manual` |
| `multi_shots` | object[] | Conditional | Array of shot definitions. **Required** for `multi_shot_manual` mode. Each object has: `prompt` (string, required), `duration` (integer, required), `camera_movement_id` (string, optional) |
| `image_urls` | string[] | No | Reference image URLs (max 3). Reference in prompts as `<<<image_1>>>`, `<<<image_2>>>`, `<<<image_3>>>` |
| `start_image_url` | string | No | Starting frame image URL |
| `end_image_url` | string | No | Ending frame image URL. When provided, `generate_audio` is forced to `false` |
| `duration` | integer | No | Duration in seconds (3-12). Default: `5` |
| `aspect_ratio` | string | No | `1:1`, `3:4`, `2:3`, `9:16`, `3:2`, `4:3`, `16:9`, `21:9`. Default: `16:9` |
| `resolution` | string | No | `720p` (default) or `1080p` |
| `genre` | string | No | `auto` (default), `action`, `horror`, `comedy`, `western`, `suspense`, `intimate`, `spectacle` |
| `camera_movement_id` | string | No | Camera movement preset ID from [Resources API](/api-reference/resources#higgsfield-ai) |
| `generate_audio` | boolean | No | Enable AI-generated sound effects. Default: `false`. Forced to `false` when `end_image_url` is provided |
| `seed` | integer | No | 0-999999 for reproducibility |

## Shot Modes

**Single (default)**

Standard single-shot video generation. Requires `prompt`.

**Multi-Shot Auto**

Automatically splits the video into multiple shots. Requires `prompt`. The system determines shot boundaries and transitions.

**Multi-Shot Manual**

User defines each shot individually via the `multi_shots` array. Each shot has its own `prompt`, `duration`, and optional `camera_movement_id`.

## Example - Single Shot with Reference Images

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "higgsfield-ai/cinematic-studio-video-2.5",
    "input": {
      "prompt": "<<<image_1>>> A cinematic scene with dramatic lighting <<<image_2>>>",
      "image_urls": [
        "https://example.com/ref1.jpg",
        "https://example.com/ref2.jpg"
      ],
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "1080p",
      "genre": "action",
      "camera_movement_id": "fc583228-7a2e-4e94-8c3b-38962895e99d",
      "generate_audio": true
    }
  }'
```

## Example - With Start and End Frames

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "higgsfield-ai/cinematic-studio-video-2.5",
    "input": {
      "prompt": "Smooth transition between scenes",
      "start_image_url": "https://example.com/start.jpg",
      "end_image_url": "https://example.com/end.jpg",
      "duration": 7,
      "aspect_ratio": "21:9",
      "resolution": "720p",
      "genre": "auto"
    }
  }'
```

## Example - Multi-Shot Auto

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "higgsfield-ai/cinematic-studio-video-2.5",
    "input": {
      "prompt": "An epic journey through a fantasy landscape",
      "shot_mode": "multi_shot_auto",
      "duration": 10,
      "aspect_ratio": "16:9",
      "resolution": "1080p",
      "genre": "spectacle"
    }
  }'
```

## Example - Multi-Shot Manual

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "higgsfield-ai/cinematic-studio-video-2.5",
    "input": {
      "shot_mode": "multi_shot_manual",
      "multi_shots": [
        {
          "prompt": "Wide establishing shot of the city skyline",
          "duration": 3,
          "camera_movement_id": "fc583228-7a2e-4e94-8c3b-38962895e99d"
        },
        {
          "prompt": "Close-up of the main character walking",
          "duration": 4,
          "camera_movement_id": "63468666-8652-40d9-8539-708e62c74846"
        },
        {
          "prompt": "Dramatic reveal of the destination",
          "duration": 3
        }
      ],
      "duration": 10,
      "image_urls": ["https://example.com/ref1.jpg"],
      "aspect_ratio": "21:9",
      "resolution": "1080p",
      "genre": "suspense"
    }
  }'
```

## Supported Aspect Ratios

| Aspect Ratio | Resolution |
|--------------|------------|
| 1:1 | 1280x1280 |
| 3:4 | 1080x1440 |
| 2:3 | 1080x1620 |
| 9:16 | 1080x1920 |
| 3:2 | 1620x1080 |
| 4:3 | 1440x1080 |
| 16:9 | 1920x1080 |
| 21:9 | 2520x1080 |

## Response

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

================================================================================
Kling v3.0
================================================================================

Kling 3.0 is an advanced video generation model that supports:
- Text-to-video generation (omit `start_frame_url`)
- Start/end frame video generation
- Multi-shot video generation (2–6 shots)
- Inline character/object elements with voice support
- AI audio generation (on by default)
- Resolutions: 720p (std) and 1080p (pro)
- Aspect ratios: 1:1, 16:9, 9:16
- Duration: 3–15 seconds

## Model

```
kuaishou/kling-3.0-video
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | Conditional | - | Text prompt. Mutually exclusive with `multi_shots` |
| `mode` | string | No | `"pro"` | `"std"` (720p) or `"pro"` (1080p) |
| `duration` | integer | No | `5` | Video duration in seconds (3–15) |
| `aspect_ratio` | string | No | `"16:9"` | `"1:1"`, `"16:9"`, or `"9:16"`. Safe to omit — server defaults to `"16:9"` |
| `native_audio` | boolean | No | `true` | Generate AI audio from the video content |
| `start_frame_url` | string | No | - | First frame image URL. Omit for text-to-video |
| `end_frame_url` | string | No | - | Last frame image URL |
| `elements` | array | No | - | Character/object elements to include in the video |
| `multi_shots` | array | No | - | Multi-shot sequence (2–6 shots, each with `prompt` and `duration`). Mutually exclusive with `prompt` |

## Elements

Elements are created automatically from your input, used during generation, then auto-deleted on completion.

```json
"elements": [
  {"description": "Woman in red jacket", "type": "image", "image_urls": ["front.jpg", "side.jpg"]},
  {"description": "Man dancing", "type": "video", "video_url": "dance.mp4"}
]
```

Each element accepts:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `description` | string | `""` | Short description of the element (max 100 chars) |
| `type` | string | `"image"` | Element source type: `"image"` or `"video"` |
| `image_urls` | string[] | - | Source image URLs for an image element (max 4) |
| `video_url` | string | - | Source video URL for a video element |

## Multi-Shot Mode

Generate multi-scene videos with 2–6 shots. When using `multi_shots`, the `prompt` field is not used.

**Key Points:**
- Each shot **must** have a `prompt` and `duration` (minimum 1 second)
- Total duration of all shots must be between 3–15 seconds
- `multi_shots` and `prompt` are mutually exclusive

---

## Examples

### Example 1: Text-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-3.0-video",
    "input": {
      "prompt": "A cinematic drone shot over a misty forest at dawn",
      "duration": 10,
      "mode": "pro",
      "native_audio": true
    }
  }'
```

### Example 2: Image-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-3.0-video",
    "input": {
      "prompt": "A majestic eagle soaring through mountain peaks at sunset",
      "start_frame_url": "https://example.com/eagle.jpg",
      "duration": 10,
      "mode": "pro",
      "native_audio": true
    }
  }'
```

### Example 3: Start and End Frames

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-3.0-video",
    "input": {
      "prompt": "Character walks towards the camera with a confident stride",
      "start_frame_url": "https://example.com/start-pose.jpg",
      "end_frame_url": "https://example.com/end-pose.jpg",
      "duration": 8,
      "mode": "pro"
    }
  }'
```

### Example 4: Multi-Shot

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-3.0-video",
    "input": {
      "start_frame_url": "https://example.com/scene.jpg",
      "mode": "pro",
      "native_audio": true,
      "multi_shots": [
        {
          "prompt": "Person walking towards camera in a park",
          "duration": 5
        },
        {
          "prompt": "Close-up of person smiling warmly",
          "duration": 4
        },
        {
          "prompt": "Wide shot of the beautiful landscape panorama",
          "duration": 6
        }
      ]
    }
  }'
```

## Response

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

================================================================================
Kling v3.0 Omni
================================================================================

Generate high-quality AI videos using Kling v3.0 Omni. Supports text-to-video, raw reference images, persistent subject/object elements, start/end frames, video transform, video reference, and multi-shot generation.

## Model

```
kuaishou/kling-3.0-omni-video
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `video_mode` | string | No | - | Input mode. Allowed: `"elements"`, `"start_end_frame"`, `"transform"`, `"video_reference"`. Omit for text-to-video |
| `prompt` | string | Conditional | - | Text prompt. Mutually exclusive with `multi_shots` |
| `mode` | string | No | `"pro"` | `"std"` (720p) or `"pro"` (1080p) |
| `duration` | integer | No | `5` | Video length in seconds (3–15) |
| `aspect_ratio` | string | No | - | `"1:1"`, `"9:16"`, `"16:9"`, or `"auto"`. Must be `"auto"` when `video_url` is set; rejected otherwise. Omit to let the server choose (`"auto"` if `video_url`, else `"16:9"`) |
| `native_audio` | boolean | No | `false` | Generate AI audio from the video content |
| `image_urls` | string[] | No | - | Raw reference image URLs uploaded per request (max 7). No description, no reuse. Use `@Image1`, `@Image2` in `prompt` |
| `start_image_index` | integer | No | - | 1-based index into `image_urls` marking which reference image anchors the first frame. No end-frame equivalent |
| `elements` | ElementInput30[] | No | - | Persistent subject/object assets. Auto-created on Kling and auto-deleted if submit fails. Use `@Element1`, `@Element2` in `prompt`. Coexists with `image_urls` |
| `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 | - | Multi-shot sequence (2–6 shots, each with `prompt` and `duration`). Mutually exclusive with `prompt` |

## Modes

| Mode | Required inputs | Optional inputs | Notes |
|------|-----------------|-----------------|-------|
| _omitted_ (text-to-video) | `prompt` or `multi_shots` | — | Rejects every input field including `elements`, `image_urls`, `start_frame_url`, `video_url` |
| `elements` | At least one of `image_urls`, `elements` | — | Combined `image_urls` + `elements` cap of **7**. `video_url` rejected |
| `start_end_frame` | `start_frame_url` | `end_frame_url`, `elements` | — |
| `transform` | `video_url` | `image_urls`, `elements` | Combined `image_urls` + `elements` cap of **4**. `aspect_ratio` must be `"auto"` |
| `video_reference` | `video_url` | `image_urls`, `elements` | Combined `image_urls` + `elements` cap of **4**. `aspect_ratio` must be `"auto"` |

<Note>
**Text-to-video with elements** — set `video_mode: "elements"` and pass only the `elements` array (no `image_urls` required). The omit-`video_mode` path is strictly for pure text-to-video with **zero** inputs; any reference (image or element) requires `elements` mode.
</Note>

## Reference images vs elements

- **`image_urls`** — raw images uploaded per request. Single-use, no description, no reuse across tasks. Cap 7. Reference in `prompt` as `@Image1`, `@Image2`, …
- **`elements`** — persistent subject/object assets stored on the Kling account. Auto-created from your input on submit and auto-deleted if the submit fails. Reference in `prompt` as `@Element1`, `@Element2`, …

Both can be used together; they share the per-mode combined cap.

## Elements

v3 Omni supports both IMAGE and VIDEO elements. A `video_url` and any element with `type: "video"` are mutually exclusive — passing both returns 400 (the video element counts as your video reference).

```json
"elements": [
  {"description": "Woman in red jacket", "type": "image", "image_urls": ["front.jpg", "side.jpg"]},
  {"description": "Man dancing", "type": "video", "video_url": "dance.mp4"}
]
```

Each element accepts:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `description` | string | `""` | Short description of the element (max 100 chars) |
| `type` | string | `"image"` | Element source type: `"image"` or `"video"` |
| `image_urls` | string[] | - | Source image URLs for an image element (max 4) |
| `video_url` | string | - | Source video URL for a video element |

## Example - Text-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-3.0-omni-video",
    "input": {
      "prompt": "A majestic eagle soaring through mountain peaks at sunset",
      "duration": 5,
      "mode": "pro"
    }
  }'
```

## Example - With Elements

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-3.0-omni-video",
    "input": {
      "video_mode": "elements",
      "prompt": "@Element1 walks through a park at sunset",
      "elements": [
        {"description": "Woman in red jacket", "type": "image", "image_urls": ["https://example.com/front.jpg"]}
      ],
      "duration": 10,
      "mode": "pro"
    }
  }'
```

## Example - Reference Images with Start Frame

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-3.0-omni-video",
    "input": {
      "video_mode": "elements",
      "prompt": "@Image2 walks toward @Image1 across a meadow",
      "image_urls": [
        "https://example.com/character.jpg",
        "https://example.com/scene.jpg"
      ],
      "start_image_index": 2,
      "duration": 5,
      "mode": "pro"
    }
  }'
```

## Example - Multi-Shot

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-3.0-omni-video",
    "input": {
      "mode": "pro",
      "multi_shots": [
        { "prompt": "Wide shot of city skyline", "duration": 5 },
        { "prompt": "Close-up of glass buildings", "duration": 5 }
      ]
    }
  }'
```

## Response

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

================================================================================
Kling v3.0 Omni Video Edit
================================================================================

Edit and transform videos using Kling v3.0 Omni Video Edit with support for reference images and elements.

## Model

```
kuaishou/kling-3.0-omni-video-edit
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `video_url` | string | **Yes** | - | Source video URL to edit |
| `prompt` | string | **Yes** | - | Text prompt describing the edit |
| `video_mode` | string | No | `"reference"` | Edit mode: `"reference"` (use video as style guide) or `"transform"` (restyle the video) |
| `keep_audio` | boolean | No | `false` | Preserve original audio from the source video |
| `mode` | string | No | `"std"` | `"std"` (720p) or `"pro"` (1080p) |
| `aspect_ratio` | string | No | `"16:9"` | `"1:1"`, `"9:16"`, or `"16:9"` |
| `image_urls` | string[] | No | - | Reference image URLs (max 4). Use `@Image1`, `@Image2` in prompt |
| `elements` | array | No | - | Character/object elements (max 4) |

**Note:** Duration is locked to the input video length and cannot be set manually.

## Elements

Elements are created automatically from your input, used during generation, then auto-deleted on completion.

```json
"elements": [
  {"description": "Woman in red jacket", "type": "image", "image_urls": ["front.jpg", "side.jpg"]},
  {"description": "Man dancing", "type": "video", "video_url": "dance.mp4"}
]
```

Each element accepts:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `description` | string | `""` | Short description of the element (max 100 chars) |
| `type` | string | `"image"` | Element source type: `"image"` or `"video"` |
| `image_urls` | string[] | - | Source image URLs for an image element (max 4) |
| `video_url` | string | - | Source video URL for a video element |

## Example - Reference Mode

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-3.0-omni-video-edit",
    "input": {
      "prompt": "Transform into anime style",
      "video_url": "https://example.com/video.mp4",
      "video_mode": "reference",
      "mode": "pro"
    }
  }'
```

## Example - Transform Mode with Reference Images

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-3.0-omni-video-edit",
    "input": {
      "prompt": "Replace the person with @Image1",
      "video_url": "https://example.com/video.mp4",
      "video_mode": "transform",
      "image_urls": ["https://example.com/person.jpg"],
      "mode": "pro"
    }
  }'
```

## Response

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

================================================================================
Kling v2.6
================================================================================

Generate high-quality AI videos using Kling v2.6 with text-to-video, start/end frame, and voice support.

## Model

```
kuaishou/kling-2.6-video
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | **Yes** | - | Text prompt describing the video to generate |
| `mode` | string | No | `"pro"` | `"std"` (720p) or `"pro"` (1080p) |
| `duration` | integer | No | `5` | `5` or `10` seconds |
| `native_audio` | boolean | No | `false` | Enable AI audio generation. Required for voices, pro mode only |
| `start_frame_url` | string | No | - | First frame image URL. Omit for text-to-video |
| `end_frame_url` | string | No | - | Last frame image URL (not available with native_audio) |
| `voices` | array | No | - | Voice references for character speech (max 5, requires native_audio) |

Each voice accepts:

| Parameter | Type | Description |
|-----------|------|-------------|
| `voice_id` | integer | Official voice ID (use [GET /v1/resources/kuaishou/kling/voices](/api-reference/resources#get-kling-voices) to list). Mutually exclusive with `voice_url` |
| `voice_url` | string | Custom voice MP3 URL. Mutually exclusive with `voice_id` |

## Constraints

- `native_audio` requires `mode: "pro"`
- `end_frame_url` is not available when `native_audio` is enabled
- `voices` require `native_audio` to be enabled

## Example - Text-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-2.6-video",
    "input": {
      "prompt": "A cinematic drone shot over a misty forest at dawn",
      "duration": 10,
      "mode": "pro"
    }
  }'
```

## Example - Image-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-2.6-video",
    "input": {
      "prompt": "Animate this scene with gentle movement",
      "start_frame_url": "https://example.com/my-image.jpg",
      "duration": 5
    }
  }'
```

## Example - With Voice

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-2.6-video",
    "input": {
      "prompt": "Person speaking to the camera about their day",
      "start_frame_url": "https://example.com/person.jpg",
      "duration": 10,
      "mode": "pro",
      "native_audio": true,
      "voices": [
        { "voice_url": "https://example.com/voice-sample.mp3" }
      ]
    }
  }'
```

## Response

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

================================================================================
Kling v2.5 Turbo
================================================================================

Generate high-quality AI videos using Kling v2.5 Turbo with optional start/end frame and sound effects.

## Model

```
kuaishou/kling-2.5-turbo-video
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | **Yes** | - | Text prompt describing the video to generate |
| `mode` | string | No | `"pro"` | `"std"` (720p) or `"pro"` (1080p) |
| `duration` | integer | No | `5` | `5` or `10` seconds |
| `aspect_ratio` | string | No | `"16:9"` | `"1:1"`, `"9:16"`, or `"16:9"`. Ignored when `start_frame_url` is set. Safe to omit |
| `start_frame_url` | string | No | - | First frame image URL (uses image native ratio) |
| `end_frame_url` | string | No | - | Last frame image URL |
| `sound_effects` | object | No | - | Sound effects and music configuration. Omit to disable audio |

Sound effects fields:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `sound` | string | `""` | Sound effect prompt (e.g. "wind blowing, birds chirping") |
| `music` | string | `""` | Background music prompt (e.g. "cinematic orchestral") |
| `asmr_mode` | boolean | `false` | Enable ASMR-style audio generation |

## Example - Text-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-2.5-turbo-video",
    "input": {
      "prompt": "Cinematic scene with dramatic lighting",
      "duration": 10,
      "sound_effects": {
        "music": "cinematic orchestral"
      }
    }
  }'
```

## Example - Image-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-2.5-turbo-video",
    "input": {
      "prompt": "Cinematic scene with dramatic lighting",
      "start_frame_url": "https://example.com/start.jpg",
      "duration": 10,
      "sound_effects": {
        "sound": "wind blowing, birds chirping",
        "music": "ambient nature"
      }
    }
  }'
```

## Response

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

================================================================================
Kling v2.1
================================================================================

Generate high-quality AI videos using Kling v2.1 with flexible generation modes.

## Models

| Model | Mode | Features |
|-------|------|----------|
| `kuaishou/kling-2.1-video` | `std`, `pro` | Image-to-video only, end frame supported |
| `kuaishou/kling-2.1-master-video` | `pro` only | Text-to-video + image-to-video, no end frame |

---

## Kling v2.1

Image-to-video only — `start_frame_url` is required.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | **Yes** | - | Text prompt describing the video to generate |
| `start_frame_url` | string | **Yes** | - | First frame image URL |
| `end_frame_url` | string | No | - | Last frame image URL |
| `duration` | integer | No | `5` | `5` or `10` seconds |
| `mode` | string | No | `"pro"` | `"std"` (720p) or `"pro"` (1080p) |
| `sound_effects` | object | No | - | Sound effects and music configuration. Omit to disable audio |

### Example

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-2.1-video",
    "input": {
      "prompt": "A butterfly landing on a flower in slow motion",
      "start_frame_url": "https://example.com/butterfly.jpg",
      "duration": 5,
      "mode": "pro"
    }
  }'
```

---

## Kling v2.1 Master

Supports both text-to-video and image-to-video. Pro-only mode. No end frame support.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | **Yes** | - | Text prompt describing the video to generate |
| `duration` | integer | No | `5` | `5` or `10` seconds |
| `start_frame_url` | string | No | - | First frame image URL (optional) |
| `sound_effects` | object | No | - | Sound effects and music configuration. Omit to disable audio |

### Example - Text-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-2.1-master-video",
    "input": {
      "prompt": "Cinematic scene with dramatic lighting",
      "duration": 10,
      "sound_effects": {
        "music": "cinematic orchestral"
      }
    }
  }'
```

### Example - Image-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-2.1-master-video",
    "input": {
      "prompt": "Cinematic scene with dramatic lighting",
      "start_frame_url": "https://example.com/start.jpg",
      "duration": 10
    }
  }'
```

---

## Sound Effects

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `sound` | string | `""` | Sound effect prompt (e.g. "wind blowing, birds chirping") |
| `music` | string | `""` | Background music prompt (e.g. "cinematic orchestral") |
| `asmr_mode` | boolean | `false` | Enable ASMR-style audio generation |

## Response

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

================================================================================
Kling O1 Video
================================================================================

Generate high-quality AI videos using Kling O1. Supports text-to-video, raw reference images, persistent subject/object elements (image only), start/end frames, video transform, and video reference.

Same shape as Omni 3.0 but does not support `multi_shots`, `native_audio`, or video-type elements. Max duration 10s.

## Model

```
kuaishou/kling-o1-video
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `video_mode` | string | No | - | Input mode. Allowed: `"elements"`, `"start_end_frame"`, `"transform"`, `"video_reference"`. Omit for text-to-video |
| `prompt` | string | **Yes** | - | Text prompt |
| `mode` | string | No | `"pro"` | `"std"` (720p) or `"pro"` (1080p) |
| `duration` | integer | No | `5` | Video length in seconds (3–10) |
| `aspect_ratio` | string | No | - | `"1:1"`, `"9:16"`, `"16:9"`, or `"auto"`. Must be `"auto"` when `video_url` is set; rejected otherwise. Omit to let the server choose (`"auto"` if `video_url`, else `"16:9"`) |
| `image_urls` | string[] | No | - | Raw reference image URLs uploaded per request (max 7). No description, no reuse. Use `@Image1`, `@Image2` in `prompt` |
| `start_image_index` | integer | No | - | 1-based index into `image_urls` marking which reference image anchors the first frame. No end-frame equivalent |
| `elements` | ElementInput30[] | No | - | Persistent subject/object assets (image only on O1). Auto-created on Kling and auto-deleted if submit fails. Use `@Element1`, `@Element2` in `prompt`. Coexists with `image_urls` |
| `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) |

## Modes

| Mode | Required inputs | Optional inputs | Notes |
|------|-----------------|-----------------|-------|
| _omitted_ (text-to-video) | `prompt` | — | Rejects every input field including `elements`, `image_urls`, `start_frame_url`, `video_url` |
| `elements` | At least one of `image_urls`, `elements` | — | Combined `image_urls` + `elements` cap of **7**. `video_url` rejected |
| `start_end_frame` | `start_frame_url` | `end_frame_url`, `elements` | — |
| `transform` | `video_url` | `image_urls`, `elements` | Combined `image_urls` + `elements` cap of **4**. `aspect_ratio` must be `"auto"` |
| `video_reference` | `video_url` | `image_urls`, `elements` | Combined `image_urls` + `elements` cap of **4**. `aspect_ratio` must be `"auto"` |

<Note>
**Text-to-video with elements** — set `video_mode: "elements"` and pass only the `elements` array (no `image_urls` required). The omit-`video_mode` path is strictly for pure text-to-video with **zero** inputs; any reference (image or element) requires `elements` mode.
</Note>

## Reference images vs elements

- **`image_urls`** — raw images uploaded per request. Single-use, no description, no reuse across tasks. Cap 7. Reference in `prompt` as `@Image1`, `@Image2`, …
- **`elements`** — persistent subject/object assets stored on the Kling account. Auto-created from your input on submit and auto-deleted if the submit fails. Reference in `prompt` as `@Element1`, `@Element2`, …

Both can be used together; they share the per-mode combined cap.

## Elements

O1 supports IMAGE elements only — passing an element with `type: "video"` returns 400.

```json
"elements": [
  {"description": "Woman in red jacket", "type": "image", "image_urls": ["front.jpg", "side.jpg"]}
]
```

Each element accepts:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `description` | string | `""` | Short description of the element (max 100 chars) |
| `type` | string | `"image"` | Must be `"image"` on O1 |
| `image_urls` | string[] | - | Source image URLs for the element (max 4) |

## Example - Text-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-o1-video",
    "input": {
      "prompt": "A cinematic drone shot over a misty forest at dawn",
      "duration": 10,
      "mode": "pro"
    }
  }'
```

## Example - Reference Images

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-o1-video",
    "input": {
      "video_mode": "elements",
      "prompt": "Create a video featuring @Image1 and @Image2",
      "image_urls": ["https://example.com/ref1.jpg", "https://example.com/ref2.jpg"],
      "duration": 10,
      "mode": "pro"
    }
  }'
```

## Example - With Elements

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-o1-video",
    "input": {
      "video_mode": "elements",
      "prompt": "@Element1 walks through a park at sunset",
      "elements": [
        {"description": "Woman in red jacket", "type": "image", "image_urls": ["https://example.com/front.jpg"]}
      ],
      "duration": 10,
      "mode": "pro"
    }
  }'
```

## Example - Start/End Frame

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-o1-video",
    "input": {
      "prompt": "Smooth transition between scenes",
      "video_mode": "start_end_frame",
      "start_frame_url": "https://example.com/start.jpg",
      "end_frame_url": "https://example.com/end.jpg",
      "duration": 10,
      "mode": "pro"
    }
  }'
```

## Response

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

================================================================================
Kling O1 Video Edit
================================================================================

Edit and transform videos using Kling O1 Video Edit with support for reference images.

## Model

```
kuaishou/kling-o1-video-edit
```

## Parameters

Same parameters as Omni 3.0 video edit but does not support `elements`.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `video_url` | string | **Yes** | - | Source video URL to edit |
| `prompt` | string | **Yes** | - | Text prompt describing the edit |
| `video_mode` | string | No | `"reference"` | Edit mode: `"reference"` or `"transform"` |
| `keep_audio` | boolean | No | `false` | Preserve original audio from the source video |
| `mode` | string | No | `"std"` | `"std"` (720p) or `"pro"` (1080p) |
| `aspect_ratio` | string | No | `"16:9"` | `"1:1"`, `"9:16"`, or `"16:9"` |
| `image_urls` | string[] | No | - | Reference image URLs (max 4). Use `@Image1`, `@Image2` in prompt |

**Note:** Duration is locked to the input video length and cannot be set manually.

## Example - Reference Mode

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-o1-video-edit",
    "input": {
      "prompt": "Transform into anime style",
      "video_url": "https://example.com/video.mp4",
      "video_mode": "reference",
      "mode": "pro"
    }
  }'
```

## Example - Transform Mode with Reference Images

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-o1-video-edit",
    "input": {
      "prompt": "Replace the person with @Image1",
      "video_url": "https://example.com/video.mp4",
      "video_mode": "transform",
      "image_urls": ["https://example.com/person.jpg"],
      "mode": "pro"
    }
  }'
```

## Response

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

================================================================================
Kling Motion Control 2.6
================================================================================

Transfer motion from a reference video onto a character in a reference image.

## Model

```
kuaishou/kling-2.6-motion-control
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | **Yes** | - | Text prompt describing the motion to generate |
| `image_url` | string | **Yes** | - | Character/subject image URL |
| `video_url` | string | **Yes** | - | Motion reference video URL |
| `mode` | string | No | `"std"` | `"std"` (720p) or `"pro"` (1080p) |
| `keep_audio` | boolean | No | `true` | Preserve original audio from the motion reference video |
| `character_orientation` | string | No | `"video"` | Character orientation source: `"video"` (follow motion) or `"image"` (preserve pose) |

## Image Requirements

The reference image must show the subject's **head, shoulders, and torso clearly visible**.

## Example

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-2.6-motion-control",
    "input": {
      "prompt": "Person dancing gracefully",
      "video_url": "https://example.com/dance-motion.mp4",
      "image_url": "https://example.com/person.jpg",
      "character_orientation": "video",
      "mode": "pro",
      "keep_audio": true
    }
  }'
```

## Response

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

================================================================================
Kling Motion Control 3.0
================================================================================

Transfer motion from a reference video onto a character in a reference image. Upgraded from v2.6 with high facial consistency and inline element support.

## Model

```
kuaishou/kling-3.0-motion-control
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | **Yes** | - | Text prompt describing the motion to generate |
| `image_url` | string | **Yes** | - | Character/subject image URL |
| `video_url` | string | **Yes** | - | Motion reference video URL |
| `mode` | string | No | `"std"` | `"std"` (720p) or `"pro"` (1080p) |
| `keep_audio` | boolean | No | `true` | Preserve original audio from the motion reference video |
| `character_orientation` | string | No | `"video"` | Character orientation source: `"video"` (follow motion) or `"image"` (preserve pose) |
| `elements` | array | No | - | Additional character/object elements |

## Elements

```json
"elements": [
  {"description": "Woman in red jacket", "type": "image", "image_urls": ["front.jpg", "side.jpg"]}
]
```

Each element accepts:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `description` | string | `""` | Short description of the element (max 100 chars) |
| `type` | string | `"image"` | Element source type: `"image"` or `"video"` |
| `image_urls` | string[] | - | Source image URLs for an image element (max 4) |
| `video_url` | string | - | Source video URL for a video element |

## Image Requirements

The reference image must show the subject's **head, shoulders, and torso clearly visible**.

## Example

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kuaishou/kling-3.0-motion-control",
    "input": {
      "prompt": "Person dancing gracefully",
      "video_url": "https://example.com/dance-motion.mp4",
      "image_url": "https://example.com/person.jpg",
      "character_orientation": "video",
      "mode": "pro",
      "keep_audio": true
    }
  }'
```

## Response

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

================================================================================
SeeDance 2.0 Fast
================================================================================

Generate videos using ByteDance SeeDance 2.0 Fast with text-to-video, first & last frame, and omni-reference modes. Supports 4–15 second durations at 720p.

## Model

```
bytedance/seedance-2.0-fast
```

## Supported Modes

| Mode | Description |
|------|-------------|
| `text_to_video` | Text-to-video. You control the aspect ratio. |
| `first_last_frame` | Start frame required, end frame optional. Aspect ratio auto-detected from input. |
| `omni_reference` | Up to 9 image/video/audio references (audio max 15s). Use `@Image1`/`@Video1`/`@Audio1` placeholders in prompt. |

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | No | `""` | Text prompt. Use `@Image1`/`@Video1`/`@Audio1` placeholders in `omni_reference` mode. |
| `mode` | string | Yes | — | `text_to_video`, `first_last_frame`, or `omni_reference` |
| `aspect_ratio` | string | No | `"1:1"` | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. Only used for text-to-video. |
| `duration` | integer | No | `5` | Duration in seconds (4–15) |
| `seed` | integer | No | random | Seed for reproducibility |
| `first_frame_url` | string | Conditional | `null` | Start frame image. **Required** for `first_last_frame`. |
| `last_frame_url` | string | No | `null` | End frame image. Optional for `first_last_frame`. |
| `references` | string[] | Conditional | `null` | Media URLs (images/videos/audio). Audio max 15s. **Required** for `omni_reference`. Max 9. |

## Example - Text-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedance-2.0-fast",
    "input": {
      "prompt": "A drone shot flying over a neon-lit cyberpunk city at night",
      "mode": "text_to_video",
      "aspect_ratio": "16:9",
      "duration": 5
    }
  }'
```

## Example - First & Last Frame

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedance-2.0-fast",
    "input": {
      "prompt": "Smooth camera pan from left to right",
      "mode": "first_last_frame",
      "duration": 8,
      "first_frame_url": "https://example.com/start.jpg",
      "last_frame_url": "https://example.com/end.jpg"
    }
  }'
```

## Example - Omni-Reference

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedance-2.0-fast",
    "input": {
      "prompt": "Transform the background of @Video1 to match the scenery in @Image1",
      "mode": "omni_reference",
      "duration": 8,
      "references": [
        "https://example.com/scenery.jpg",
        "https://example.com/clip.mp4"
      ]
    }
  }'
```

References are numbered in order: first image = `@Image1`, first video = `@Video1`, first audio = `@Audio1`, etc. Images, videos, and audio are numbered independently.

## Response

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

================================================================================
SeeDance 2.0 Pro
================================================================================

Generate videos using ByteDance SeeDance 2.0 Pro with text-to-video, first & last frame, and omni-reference modes. Supports 4–15 second durations at 720p with higher quality output.

## Model

```
bytedance/seedance-2.0-pro
```

## Supported Modes

| Mode | Description |
|------|-------------|
| `text_to_video` | Text-to-video. You control the aspect ratio. |
| `first_last_frame` | Start frame required, end frame optional. Aspect ratio auto-detected from input. |
| `omni_reference` | Up to 9 image/video/audio references (audio max 15s). Use `@Image1`/`@Video1`/`@Audio1` placeholders in prompt. |

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | No | `""` | Text prompt. Use `@Image1`/`@Video1`/`@Audio1` placeholders in `omni_reference` mode. |
| `mode` | string | Yes | — | `text_to_video`, `first_last_frame`, or `omni_reference` |
| `aspect_ratio` | string | No | `"1:1"` | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. Only used for text-to-video. |
| `duration` | integer | No | `5` | Duration in seconds (4–15) |
| `seed` | integer | No | random | Seed for reproducibility |
| `first_frame_url` | string | Conditional | `null` | Start frame image. **Required** for `first_last_frame`. |
| `last_frame_url` | string | No | `null` | End frame image. Optional for `first_last_frame`. |
| `references` | string[] | Conditional | `null` | Media URLs (images/videos/audio). Audio max 15s. **Required** for `omni_reference`. Max 9. |

## Example - Text-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedance-2.0-pro",
    "input": {
      "prompt": "Cinematic slow-motion shot of a dancer performing on a rain-soaked stage",
      "mode": "text_to_video",
      "aspect_ratio": "16:9",
      "duration": 10
    }
  }'
```

## Example - First & Last Frame

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedance-2.0-pro",
    "input": {
      "prompt": "The car accelerates and drives away into the sunset",
      "mode": "first_last_frame",
      "duration": 12,
      "first_frame_url": "https://example.com/start.jpg",
      "last_frame_url": "https://example.com/end.jpg"
    }
  }'
```

## Example - Omni-Reference

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedance-2.0-pro",
    "input": {
      "prompt": "Make @Image1 come alive in the style of @Video1",
      "mode": "omni_reference",
      "duration": 8,
      "references": [
        "https://example.com/portrait.jpg",
        "https://example.com/animation-style.mp4"
      ]
    }
  }'
```

References are numbered in order: first image = `@Image1`, first video = `@Video1`, first audio = `@Audio1`, etc. Images, videos, and audio are numbered independently.

## Response

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

================================================================================
SeeDance 1.5 Pro
================================================================================

Generate videos using ByteDance SeeDance 1.5 Pro with text-to-video and first & last frame modes. Supports 5, 10, and 12 second durations at 720p or 1080p.

## Model

```
bytedance/seedance-1.5-pro
```

## Supported Modes

| Mode | Description |
|------|-------------|
| `text_to_video` | Text-to-video. You control the aspect ratio. |
| `first_last_frame` | Start frame required, end frame optional. Aspect ratio auto-detected from input. |

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | No | `""` | Text description of the desired video |
| `mode` | string | Yes | — | `text_to_video` or `first_last_frame` |
| `aspect_ratio` | string | No | `"1:1"` | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. Only used for text-to-video. |
| `duration` | integer | No | `5` | Duration in seconds: `5`, `10`, or `12` |
| `resolution` | string | No | `"720p"` | `720p` or `1080p` |
| `seed` | integer | No | random | Seed for reproducibility |
| `first_frame_url` | string | Conditional | `null` | Start frame image. **Required** for `first_last_frame`. |
| `last_frame_url` | string | No | `null` | End frame image. Optional for `first_last_frame`. |

## Example - Text-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedance-1.5-pro",
    "input": {
      "prompt": "A dancer performing an elegant routine on a moonlit stage",
      "mode": "text_to_video",
      "aspect_ratio": "9:16",
      "duration": 10,
      "resolution": "1080p"
    }
  }'
```

## Example - First & Last Frame

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedance-1.5-pro",
    "input": {
      "prompt": "The car accelerates and drives away into the sunset",
      "mode": "first_last_frame",
      "duration": 10,
      "resolution": "1080p",
      "first_frame_url": "https://example.com/start.jpg",
      "last_frame_url": "https://example.com/end.jpg"
    }
  }'
```

## Response

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

================================================================================
SeeDance 1.0 Pro
================================================================================

Generate videos using ByteDance SeeDance 1.0 Pro with text-to-video and first & last frame modes. Supports 5 and 10 second durations at 720p.

## Model

```
bytedance/seedance-1.0-pro
```

## Supported Modes

| Mode | Description |
|------|-------------|
| `text_to_video` | Text-to-video. You control the aspect ratio. |
| `first_last_frame` | Start frame required, end frame optional. Aspect ratio auto-detected from input. |

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | No | `""` | Text description of the desired video |
| `mode` | string | Yes | — | `text_to_video` or `first_last_frame` |
| `aspect_ratio` | string | No | `"1:1"` | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. Only used for text-to-video. |
| `duration` | integer | No | `5` | Duration in seconds: `5` or `10` |
| `seed` | integer | No | random | Seed for reproducibility |
| `first_frame_url` | string | Conditional | `null` | Start frame image. **Required** for `first_last_frame`. |
| `last_frame_url` | string | No | `null` | End frame image. Optional for `first_last_frame`. |

## Example - Text-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedance-1.0-pro",
    "input": {
      "prompt": "A person dancing in a vibrant street scene",
      "mode": "text_to_video",
      "aspect_ratio": "9:16",
      "duration": 5
    }
  }'
```

## Example - First & Last Frame

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedance-1.0-pro",
    "input": {
      "prompt": "Smooth transition between poses",
      "mode": "first_last_frame",
      "duration": 10,
      "first_frame_url": "https://example.com/start.jpg",
      "last_frame_url": "https://example.com/end.jpg"
    }
  }'
```

## Response

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

================================================================================
SeeDance 1.0 Mini
================================================================================

Generate videos using ByteDance SeeDance 1.0 Mini with text-to-video, first & last frame, and multi-frame modes. Supports 5 and 10 second durations at 720p or 1080p.

## Model

```
bytedance/seedance-1.0-mini
```

## Supported Modes

| Mode | Description |
|------|-------------|
| `text_to_video` | Text-to-video. You control the aspect ratio. |
| `first_last_frame` | Start frame required, end frame optional. Aspect ratio auto-detected from input. |
| `multi_frame` | Keyframe images with per-frame prompts and durations. **720p only.** |

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | No | `""` | Text description of the desired video |
| `mode` | string | Yes | — | `text_to_video`, `first_last_frame`, or `multi_frame` |
| `aspect_ratio` | string | No | `"1:1"` | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. Only used for text-to-video. |
| `duration` | integer | No | `5` | Duration in seconds: `5` or `10`. Auto-calculated in `multi_frame` mode. |
| `resolution` | string | No | `"720p"` | `720p` or `1080p`. Multi-frame mode requires `720p`. |
| `seed` | integer | No | random | Seed for reproducibility |
| `first_frame_url` | string | Conditional | `null` | Start frame image. **Required** for `first_last_frame`. |
| `last_frame_url` | string | No | `null` | End frame image. Optional for `first_last_frame`. |
| `frames` | object[] | Conditional | `null` | Keyframes. **Required** for `multi_frame`. Min 1. |

### Multi-Frame `frames` Object

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `image_url` | string | No | `null` | Keyframe image URL. Omit for text-only frame. |
| `prompt` | string | No | `""` | Per-frame prompt |
| `duration` | integer | No | `5` | Segment duration in seconds |

At least one frame must have an `image_url`. Total video duration = sum of all frame durations.

## Example - Text-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedance-1.0-mini",
    "input": {
      "prompt": "A butterfly landing on a flower in slow motion",
      "mode": "text_to_video",
      "aspect_ratio": "1:1",
      "duration": 5,
      "resolution": "1080p"
    }
  }'
```

## Example - First & Last Frame

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedance-1.0-mini",
    "input": {
      "prompt": "Gradual zoom into the subject",
      "mode": "first_last_frame",
      "duration": 10,
      "resolution": "1080p",
      "first_frame_url": "https://example.com/start.jpg"
    }
  }'
```

## Example - Multi-Frame

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedance-1.0-mini",
    "input": {
      "mode": "multi_frame",
      "resolution": "720p",
      "frames": [
        {
          "prompt": "A car driving through a city transitioning from day to night",
          "duration": 3
        },
        {
          "image_url": "https://example.com/daytime.jpg",
          "prompt": "Bright sunny street with the car approaching",
          "duration": 5
        },
        {
          "image_url": "https://example.com/nighttime.jpg",
          "prompt": "Neon-lit street at night as the car drives away",
          "duration": 5
        }
      ]
    }
  }'
```

## Response

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

================================================================================
SeeDance 1.0 Fast
================================================================================

Generate videos using ByteDance SeeDance 1.0 Fast with text-to-video, first & last frame, and multi-frame modes. Supports 5 and 10 second durations at 720p or 1080p.

## Model

```
bytedance/seedance-1.0-fast
```

## Supported Modes

| Mode | Description |
|------|-------------|
| `text_to_video` | Text-to-video. You control the aspect ratio. |
| `first_last_frame` | Start frame required, end frame optional. Aspect ratio auto-detected from input. |
| `multi_frame` | Keyframe images with per-frame prompts and durations. |

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | No | `""` | Text description of the desired video |
| `mode` | string | Yes | — | `text_to_video`, `first_last_frame`, or `multi_frame` |
| `aspect_ratio` | string | No | `"1:1"` | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. Only used for text-to-video. |
| `duration` | integer | No | `5` | Duration in seconds: `5` or `10`. Auto-calculated in `multi_frame` mode. |
| `resolution` | string | No | `"720p"` | `720p` or `1080p` |
| `seed` | integer | No | random | Seed for reproducibility |
| `first_frame_url` | string | Conditional | `null` | Start frame image. **Required** for `first_last_frame`. |
| `last_frame_url` | string | No | `null` | End frame image. Optional for `first_last_frame`. |
| `frames` | object[] | Conditional | `null` | Keyframes. **Required** for `multi_frame`. Min 1. |

### Multi-Frame `frames` Object

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `image_url` | string | No | `null` | Keyframe image URL. Omit for text-only frame. |
| `prompt` | string | No | `""` | Per-frame prompt |
| `duration` | integer | No | `5` | Segment duration in seconds |

At least one frame must have an `image_url`. Total video duration = sum of all frame durations.

## Example - Text-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedance-1.0-fast",
    "input": {
      "prompt": "A person breakdancing in an urban setting",
      "mode": "text_to_video",
      "aspect_ratio": "9:16",
      "duration": 10,
      "resolution": "1080p"
    }
  }'
```

## Example - First & Last Frame

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedance-1.0-fast",
    "input": {
      "prompt": "Smooth transition from standing to sitting",
      "mode": "first_last_frame",
      "duration": 5,
      "resolution": "720p",
      "first_frame_url": "https://example.com/standing.jpg",
      "last_frame_url": "https://example.com/sitting.jpg"
    }
  }'
```

## Example - Multi-Frame

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "bytedance/seedance-1.0-fast",
    "input": {
      "mode": "multi_frame",
      "resolution": "720p",
      "frames": [
        {
          "prompt": "A car driving through a city transitioning from day to night",
          "duration": 3
        },
        {
          "image_url": "https://example.com/daytime.jpg",
          "prompt": "Bright sunny street with the car approaching",
          "duration": 5
        },
        {
          "image_url": "https://example.com/nighttime.jpg",
          "prompt": "Neon-lit street at night as the car drives away",
          "duration": 5
        }
      ]
    }
  }'
```

## Response

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

================================================================================
Wan 2.7
================================================================================

Generate videos using Wan 2.7 with three modes: text-to-video, image-to-video (first frame, keyframes, continuation, lip-sync), and reference-to-video (character/object consistency).

## Model

```
alibaba/wan-2.7-video
```

## Modes

| Mode | Description |
|------|-------------|
| `t2v` | Generate video from a text prompt. Multi-shot via natural language. |
| `i2v` | Generate video from a first frame, first + last frames, or continue an existing video. Optional driving audio. |
| `r2v` | Generate video from reference images/videos. Use "Image 1"/"Video 1" identifiers in prompt. |

## Common Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `mode` | string | No | `"t2v"` | `"t2v"`, `"i2v"`, or `"r2v"` |
| `prompt` | string | Depends | `""` | Text prompt (max 5000 chars). Required for T2V and R2V |
| `negative_prompt` | string | No | `""` | What to avoid (max 500 chars) |
| `resolution` | string | No | `"1080P"` | `"720P"` or `"1080P"` |
| `duration` | integer | No | `5` | Output duration in seconds (2-15) |
| `prompt_extend` | boolean | No | `true` | LLM-based prompt rewriting. Improves short prompts but adds latency |
| `watermark` | boolean | No | `false` | Add "AI Generated" watermark in lower-right corner |
| `seed` | integer | No | `null` | Random seed (0-2147483647) |

---

## T2V Mode

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `audio_url` | string | No | `null` | Audio file URL. Formats: WAV, MP3. Duration: 2-30s. Max 15MB. Truncated to `duration` if longer |
| `ratio` | string | No | `"16:9"` | Aspect ratio: `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"`, `"3:4"` |

### Multi-shot

Control shot structure using natural language in the prompt:

- **Single shot:** "Generate a single-shot video"
- **Multi-shot:** "Generate a multi-shot video" or describe shots with timestamps (e.g., "Shot 1 [0-3 seconds] wide shot: Rainy New York street at night")
- **Default:** If unspecified, the model interprets the prompt content

### Example - Basic Text-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.7-video",
    "input": {
      "mode": "t2v",
      "prompt": "A kitten running in the moonlight",
      "resolution": "720P",
      "ratio": "16:9"
    }
  }'
```

### Example - Multi-shot Narrative

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.7-video",
    "input": {
      "mode": "t2v",
      "prompt": "A tense detective story. Shot 1 [0-3 seconds] wide shot: Rainy New York street at night. Shot 2 [3-6 seconds] medium shot: The detective enters an old building.",
      "resolution": "720P",
      "ratio": "16:9",
      "duration": 6
    }
  }'
```

### Example - With Audio File

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.7-video",
    "input": {
      "mode": "t2v",
      "prompt": "A cartoon kitten general stands bravely on a cliff",
      "audio_url": "https://example.com/epic.mp3",
      "resolution": "1080P",
      "ratio": "16:9",
      "duration": 10
    }
  }'
```

---

## I2V Mode

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `first_frame_url` | string | Depends | `null` | First frame image URL. Formats: JPEG, JPG, PNG, BMP, WEBP. Resolution: 240-8000px. Max 20MB |
| `last_frame_url` | string | No | `null` | Last frame image URL. Same format limits. Requires `first_frame_url` |
| `video_url` | string | Depends | `null` | Video to continue (MP4/MOV, 2-10s, max 100MB). Mutually exclusive with `first_frame_url`/`last_frame_url` |
| `audio_url` | string | No | `null` | Driving audio URL for lip-sync / action timing. Formats: WAV, MP3. Duration: 2-30s. Max 15MB |

### Validation Rules

- At least one of `first_frame_url` or `video_url` is required
- `last_frame_url` requires `first_frame_url`
- `video_url` (continuation) is mutually exclusive with `first_frame_url` / `last_frame_url`

### Example - First Frame to Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.7-video",
    "input": {
      "mode": "i2v",
      "prompt": "A kitten runs across the grass",
      "first_frame_url": "https://example.com/cat.png",
      "resolution": "720P",
      "duration": 10
    }
  }'
```

### Example - First + Last Frame

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.7-video",
    "input": {
      "mode": "i2v",
      "prompt": "A small black cat looks up at the sky curiously",
      "first_frame_url": "https://example.com/first.png",
      "last_frame_url": "https://example.com/last.png",
      "duration": 10,
      "prompt_extend": false
    }
  }'
```

### Example - Video Continuation

Continue an existing video clip. If the input is 3s and `duration` is 15, the model generates 12s of new content. The final output is 15s.

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.7-video",
    "input": {
      "mode": "i2v",
      "prompt": "A girl takes a selfie in the mirror, then leaves with her backpack",
      "video_url": "https://example.com/clip.mp4",
      "duration": 15
    }
  }'
```

---

## R2V Mode

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `reference_image_urls` | string[] | Depends | `null` | Reference images for characters/objects/scenes. Each must contain a single subject. Formats: JPEG, JPG, PNG, BMP, WEBP. Max 20MB each |
| `reference_video_urls` | string[] | Depends | `null` | Reference videos for characters. Each must contain a single subject. Formats: MP4, MOV. Duration: 1-30s. Max 100MB each |
| `first_frame_url` | string | No | `null` | First frame image for scene control. Overrides `ratio` |
| `reference_voice_url` | string | No | `null` | Audio URL for voice timbre override. Formats: WAV, MP3. Duration: 1-10s. Max 15MB |
| `ratio` | string | No | `"16:9"` | Aspect ratio: `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"`, `"3:4"`. Ignored when `first_frame_url` is set |

### Prompt Identifiers

Use "Image 1", "Image 2" to reference images and "Video 1", "Video 2" to reference videos. Images and videos are numbered separately based on array order. If there is only one reference, you can use "the reference image" or "the reference video".

### Validation Rules

- At least 1 `reference_image_urls` or `reference_video_urls` is required
- Total images + videos must not exceed 5

### Example - Multi-Reference

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.7-video",
    "input": {
      "mode": "r2v",
      "prompt": "Video 2 holds Image 3 and plays a soothing country ballad, while Video 1 smiles and watches",
      "reference_video_urls": [
        "https://example.com/person1.mp4",
        "https://example.com/person2.mp4"
      ],
      "reference_image_urls": [
        "https://example.com/guitar.png"
      ],
      "resolution": "720P",
      "duration": 10,
      "prompt_extend": false
    }
  }'
```

### Example - Single Reference Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.7-video",
    "input": {
      "mode": "r2v",
      "prompt": "The reference image character walks through a sunlit garden",
      "reference_image_urls": ["https://example.com/person.png"],
      "resolution": "1080P",
      "ratio": "16:9",
      "duration": 5
    }
  }'
```

---

## Input Limits

| Asset | Formats | Resolution | Duration | File Size |
|-------|---------|------------|----------|-----------|
| Audio (T2V / I2V driving) | WAV, MP3 | — | 2-30s | 15MB |
| Voice timbre (R2V) | WAV, MP3 | — | 1-10s | 15MB |
| First/last frame image | JPEG, JPG, PNG, BMP, WEBP | 240-8000px, ratio 1:8 to 8:1 | — | 20MB |
| Input video (I2V continuation) | MP4, MOV | 240-4096px, ratio 1:8 to 8:1 | 2-10s | 100MB |
| Reference video (R2V) | MP4, MOV | 240-4096px, ratio 1:8 to 8:1 | 1-30s | 100MB |
| Reference image (R2V) | JPEG, JPG, PNG, BMP, WEBP | 240-8000px, ratio 1:8 to 8:1 | — | 20MB |

## Response

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

================================================================================
Wan 2.7 Video Edit
================================================================================

Edit or style-transfer an existing video using Wan 2.7 Video Edit. Supports reference images for content transfer. This is a separate model from `alibaba/wan-2.7-video`.

## Model

```
alibaba/wan-2.7-video-edit
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | No | `""` | Text prompt describing the desired edit (max 5000 chars) |
| `negative_prompt` | string | No | `""` | What to avoid (max 500 chars) |
| `video_url` | string | Yes | — | Video to edit (MP4/MOV, 2-10s, max 100MB) |
| `reference_image_urls` | string[] | No | `null` | Up to 4 reference images for style/content transfer. Formats: JPEG, JPG, PNG, BMP, WEBP. Max 20MB each |
| `resolution` | string | No | `"1080P"` | `"720P"` or `"1080P"` |
| `duration` | integer | No | `null` | Output duration in seconds (2-10). Omit to keep input duration |
| `ratio` | string | No | `null` | Force output aspect ratio: `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"`, `"3:4"`. Omit to match input video |
| `audio_setting` | string | No | `"auto"` | `"auto"` (model decides based on prompt) or `"origin"` (keep original audio unchanged) |
| `prompt_extend` | boolean | No | `true` | LLM-based prompt rewriting. Improves short prompts but adds latency |
| `watermark` | boolean | No | `false` | Add "AI Generated" watermark in lower-right corner |
| `seed` | integer | No | `null` | Random seed (0-2147483647) |

## Example - Style Transfer

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.7-video-edit",
    "input": {
      "prompt": "Convert the entire scene to a claymation style",
      "video_url": "https://example.com/scene.mp4",
      "resolution": "720P"
    }
  }'
```

## Example - With Reference Image

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.7-video-edit",
    "input": {
      "prompt": "Replace the clothes of the girl with the clothes from the image",
      "video_url": "https://example.com/girl.mp4",
      "reference_image_urls": ["https://example.com/outfit.png"]
    }
  }'
```

## Input Limits

| Asset | Formats | Resolution | Duration | File Size |
|-------|---------|------------|----------|-----------|
| Input video | MP4, MOV | 240-4096px, ratio 1:8 to 8:1 | 2-10s | 100MB |
| Reference image | JPEG, JPG, PNG, BMP, WEBP | 240-8000px, ratio 1:8 to 8:1 | — | 20MB |

## Response

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

================================================================================
Wan 2.6
================================================================================

Generate AI videos using Wan 2.6 with support for text-to-video, image-to-video, reference-to-video (character consistency), and multi-shot narratives. Includes automatic audio generation.

## Model

```
alibaba/wan-2.6-video
```

## Modes

Set `mode` explicitly to select generation type:
- `t2v` (default) — text-to-video
- `i2v` — image-to-video (requires `start_image_url`)
- `r2v` — reference-to-video (requires `video_urls`)

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the video. For R2V, use `character1`, `character2`, etc. matching `video_urls` order |
| `mode` | string | No | `t2v`, `i2v`, or `r2v` (default: `t2v`) |
| `start_image_url` | string | No | First-frame image URL for I2V mode (JPEG, PNG, BMP, WEBP) |
| `video_urls` | array | No | Reference image/video URLs for R2V mode. Up to 5 (max 3 videos). Each = one character |
| `audio_url` | string | No | Custom audio URL for audio-video sync (wav/mp3, max 15MB, 3-30s) |
| `multi_prompt` | array | No | Multi-shot segments `[{prompt, duration}]`. Auto-sets shot type and calculates total duration |
| `negative_prompt` | string | No | What to avoid in the video (max 500 chars). Ignored for R2V |
| `resolution` | string | No | `720p` or `1080p` (default: `720p`) |
| `duration` | integer | No | Video length in seconds, 2-15s (R2V: 2-10s). Overridden by `multi_prompt` if set (default: `5`) |
| `prompt_extend` | boolean | No | Intelligent prompt rewriting (default: `true`) |
| `watermark` | boolean | No | Add watermark (default: `false`) |
| `audio` | boolean | No | Auto-generate audio. Set `false` for silent video (default: `true`) |
| `seed` | integer | No | Seed for reproducibility. Not supported for R2V |

## Example - Text-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.6-video",
    "input": {
      "prompt": "A cinematic shot of a red fox walking through a misty forest at dawn",
      "mode": "t2v",
      "resolution": "720p",
      "duration": 5
    }
  }'
```

## Example - Image-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.6-video",
    "input": {
      "prompt": "The camera slowly pans up from below the sea turtle",
      "mode": "i2v",
      "start_image_url": "https://example.com/turtle.jpg",
      "resolution": "720p",
      "duration": 10
    }
  }'
```

## Example - Reference-to-Video (Single Character)

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.6-video",
    "input": {
      "prompt": "character1 gives an enthusiastic product introduction to camera",
      "mode": "r2v",
      "video_urls": ["https://example.com/presenter.mp4"],
      "duration": 5
    }
  }'
```

## Example - Reference-to-Video (Multi-Character)

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.6-video",
    "input": {
      "prompt": "character1 says to character2: I will rely on you tomorrow! character2 replies: You can count on me!",
      "mode": "r2v",
      "video_urls": ["https://example.com/person-a.mp4", "https://example.com/person-b.mp4"],
      "duration": 10
    }
  }'
```

## Example - Multi-Shot

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.6-video",
    "input": {
      "prompt": "Cinematic detective story",
      "multi_prompt": [
        {"prompt": "Wide shot of rainy New York streets, neon lights", "duration": 5},
        {"prompt": "Close-up of detective walking into an old building", "duration": 5}
      ],
      "resolution": "1080p"
    }
  }'
```

## Example - Image-to-Video with Custom Audio

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.6-video",
    "input": {
      "prompt": "A graffiti character raps energetically under a bridge",
      "mode": "i2v",
      "start_image_url": "https://example.com/graffiti.png",
      "audio_url": "https://example.com/rap.mp3",
      "duration": 10
    }
  }'
```

## Example - Silent Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.6-video",
    "input": {
      "prompt": "A cat running on the grass",
      "audio": false,
      "duration": 5
    }
  }'
```

## Response

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

================================================================================
Wan 2.6 Flash
================================================================================

Generate AI videos using Wan 2.6 Flash with the same capabilities as Wan 2.6 but faster and cheaper. Supports text-to-video, image-to-video, reference-to-video (character consistency), and multi-shot narratives with audio generation.

## Model

```
alibaba/wan-2.6-flash-video
```

## Modes

Set `mode` explicitly to select generation type:
- `t2v` (default) — text-to-video
- `i2v` — image-to-video (requires `start_image_url`)
- `r2v` — reference-to-video (requires `video_urls`)

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the video. For R2V, use `character1`, `character2`, etc. matching `video_urls` order |
| `mode` | string | No | `t2v`, `i2v`, or `r2v` (default: `t2v`) |
| `start_image_url` | string | No | First-frame image URL for I2V mode (JPEG, PNG, BMP, WEBP) |
| `video_urls` | array | No | Reference image/video URLs for R2V mode. Up to 5 (max 3 videos). Each = one character |
| `audio_url` | string | No | Custom audio URL for audio-video sync (wav/mp3, max 15MB, 3-30s) |
| `multi_prompt` | array | No | Multi-shot segments `[{prompt, duration}]`. Auto-sets shot type and calculates total duration |
| `negative_prompt` | string | No | What to avoid in the video (max 500 chars). Ignored for R2V |
| `resolution` | string | No | `720p` or `1080p` (default: `720p`) |
| `duration` | integer | No | Video length in seconds, 2-15s (R2V: 2-10s). Overridden by `multi_prompt` if set (default: `5`) |
| `prompt_extend` | boolean | No | Intelligent prompt rewriting (default: `true`) |
| `watermark` | boolean | No | Add watermark (default: `false`) |
| `audio` | boolean | No | Auto-generate audio. Set `false` for silent video (default: `true`) |
| `seed` | integer | No | Seed for reproducibility. Not supported for R2V |

## Example - Text-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.6-flash-video",
    "input": {
      "prompt": "A cat running on the grass",
      "mode": "t2v",
      "resolution": "720p",
      "duration": 5
    }
  }'
```

## Example - Image-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.6-flash-video",
    "input": {
      "prompt": "The camera slowly pans up from below the sea turtle",
      "mode": "i2v",
      "start_image_url": "https://example.com/turtle.jpg",
      "resolution": "720p",
      "duration": 10
    }
  }'
```

## Example - Reference-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.6-flash-video",
    "input": {
      "prompt": "character1 gives an enthusiastic product introduction to camera",
      "mode": "r2v",
      "video_urls": ["https://example.com/presenter.mp4"],
      "duration": 5
    }
  }'
```

## Example - Multi-Shot

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.6-flash-video",
    "input": {
      "prompt": "Cinematic detective story",
      "multi_prompt": [
        {"prompt": "Wide shot of rainy New York streets, neon lights", "duration": 5},
        {"prompt": "Close-up of detective walking into an old building", "duration": 5}
      ],
      "resolution": "1080p"
    }
  }'
```

## Response

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

================================================================================
Wan 2.5
================================================================================

Generate AI videos using Wan 2.5 with text-to-video and image-to-video capabilities. Supports 480p to 1080p resolution, 5-10 second videos, and automatic audio generation.

## Model

```
alibaba/wan-2.5-video
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the video |
| `mode` | string | No | `t2v` or `i2v` (default: `t2v`) |
| `start_image_url` | string | No | First-frame image URL (required for `i2v`) |
| `audio_url` | string | No | Custom audio URL for audio-video sync |
| `negative_prompt` | string | No | What to avoid in the video |
| `resolution` | string | No | `480p`, `720p`, or `1080p` (default: `720p`) |
| `duration` | integer | No | `5` or `10` seconds (default: `5`) |
| `prompt_extend` | boolean | No | Intelligent prompt rewriting (default: `true`) |
| `watermark` | boolean | No | Add watermark (default: `false`) |
| `audio` | boolean | No | Auto-generate audio. Set `false` for silent video (default: `true`) |
| `seed` | integer | No | Seed for reproducibility |

<Note>`video_urls` and `multi_prompt` are not supported on Wan 2.5. For reference-to-video or multi-shot, use [Wan 2.6](/models/video/alibaba/wan-2.6-video).</Note>

## Example - Text-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.5-video",
    "input": {
      "prompt": "Sunset over ocean waves",
      "mode": "t2v",
      "resolution": "1080p",
      "duration": 10
    }
  }'
```

## Example - Image-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.5-video",
    "input": {
      "prompt": "Person walking through a forest",
      "mode": "i2v",
      "start_image_url": "https://example.com/person.jpg",
      "resolution": "720p",
      "duration": 10
    }
  }'
```

## Response

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

================================================================================
Wan 2.2
================================================================================

Generate AI videos using Wan 2.2 with text-to-video and image-to-video capabilities. Produces silent video only at 480p or 1080p resolution.

## Model

```
alibaba/wan-2.2-video
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the video |
| `mode` | string | No | `t2v` or `i2v` (default: `t2v`) |
| `start_image_url` | string | No | First-frame image URL (required for `i2v`) |
| `negative_prompt` | string | No | What to avoid in the video |
| `resolution` | string | No | `480p` or `1080p` (default: `480p`) |
| `duration` | integer | No | Fixed at `5` seconds |
| `prompt_extend` | boolean | No | Intelligent prompt rewriting (default: `true`) |
| `watermark` | boolean | No | Add watermark (default: `false`) |
| `seed` | integer | No | Seed for reproducibility |

<Note>Wan 2.2 produces silent video only. `audio`, `audio_url`, `video_urls`, and `multi_prompt` are not supported.</Note>

## Example - Text-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.2-video",
    "input": {
      "prompt": "A street musician plays guitar in a vintage subway station",
      "mode": "t2v",
      "resolution": "1080p"
    }
  }'
```

## Example - Image-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.2-video",
    "input": {
      "prompt": "Gentle waves lapping against the shore",
      "mode": "i2v",
      "start_image_url": "https://example.com/beach.jpg",
      "resolution": "480p"
    }
  }'
```

## Response

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

================================================================================
Wan 2.2 Flash
================================================================================

Generate AI videos using Wan 2.2 Flash, a faster version of Wan 2.2. Produces silent video only. I2V supports 720p in addition to 480p and 1080p.

## Model

```
alibaba/wan-2.2-flash-video
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the video |
| `mode` | string | No | `t2v` or `i2v` (default: `t2v`) |
| `start_image_url` | string | No | First-frame image URL (required for `i2v`) |
| `negative_prompt` | string | No | What to avoid in the video |
| `resolution` | string | No | `480p`, `720p` (I2V only), or `1080p` (default: `480p`) |
| `duration` | integer | No | Fixed at `5` seconds |
| `prompt_extend` | boolean | No | Intelligent prompt rewriting (default: `true`) |
| `watermark` | boolean | No | Add watermark (default: `false`) |
| `seed` | integer | No | Seed for reproducibility |

<Note>Wan 2.2 Flash produces silent video only. `720p` resolution is only available in I2V mode.</Note>

## Example - Text-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.2-flash-video",
    "input": {
      "prompt": "A bird taking flight from a tree branch",
      "mode": "t2v",
      "resolution": "1080p"
    }
  }'
```

## Example - Image-to-Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "alibaba/wan-2.2-flash-video",
    "input": {
      "prompt": "A bird taking flight",
      "mode": "i2v",
      "start_image_url": "https://example.com/bird.jpg",
      "resolution": "720p"
    }
  }'
```

## Response

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

================================================================================
Topaz Video Upscale
================================================================================

Upscale and enhance videos using AI-powered Topaz Video technology with multiple AI models, resolution scaling, frame interpolation, and slow motion effects.

## Model

```
topaz-labs/video-upscale
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `video_url` | string | Yes | - | URL of the video to upscale |
| `resolution` | string | No | `1080p` | `720p`, `1080p`, `1440p`, or `2160p` |
| `fps` | integer | No | 30 | 24, 25, 30, 45, 50, or 60 |
| `enhancement_model` | string | No | `proteus` | Topaz AI enhancement model |
| `frame_interpolation` | string | No | `apollo` | `apollo` or `chronos` |
| `focus` | float | No | `0.2` | Focus / detail strength (0.0–1.0) |
| `sharpen` | float | No | `0.6` | Sharpen strength (0.0–1.0) |

## Enhancement Models

| Model | Description | Best For |
|-------|-------------|----------|
| `proteus` | General-purpose enhancement | Default choice, works well on most content |
| `artemis` | Optimized for human faces | Portrait videos, interviews, vlogs |
| `nyx` | Low-light enhancement | Dark or underexposed footage |
| `rhea` | Designed for high-resolution output | 4K+ video upscaling |
| `gaia` | Stylized processing | Anime, cartoons, and animated content |
| `colorize` | Add color to B&W footage | Black-and-white video colorization |
| `dione` | Interlaced video enhancement | Legacy interlaced footage |
| `theia` | Detail-focused enhancement | Videos with fine textures and details |
| `iris` | Alternative face optimization | Portrait videos with different processing style |
| `themis` | Stabilization-focused | Shaky or handheld footage |

<Note>The `colorize` model is not available with `720p` resolution.</Note>

## Frame Interpolation Methods

| Method | Description |
|--------|-------------|
| `apollo` | Default interpolation, good balance of speed and quality |
| `chronos` | Higher quality interpolation, slower processing |

## Example - Basic Upscale

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "topaz-labs/video-upscale",
    "input": {
      "video_url": "https://example.com/video.mp4",
      "resolution": "2160p"
    }
  }'
```

## Example - With Frame Interpolation

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "topaz-labs/video-upscale",
    "input": {
      "video_url": "https://example.com/video.mp4",
      "resolution": "2160p",
      "fps": 60,
      "enhancement_model": "rhea",
      "frame_interpolation": "chronos"
    }
  }'
```

## Example - Anime Video

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "topaz-labs/video-upscale",
    "input": {
      "video_url": "https://example.com/anime.mp4",
      "resolution": "2160p",
      "enhancement_model": "gaia"
    }
  }'
```

## Example - Full Enhancement

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "topaz-labs/video-upscale",
    "input": {
      "video_url": "https://example.com/video.mp4",
      "resolution": "2160p",
      "fps": 60,
      "enhancement_model": "proteus",
      "frame_interpolation": "apollo",
      "focus": 0.4,
      "sharpen": 0.7
    }
  }'
```

## Response

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

================================================================================
Music Generation
================================================================================

Generate complete songs using Suno AI with simple or custom mode.

## Model

```
suno-ai/music
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mv` | string | Yes | Model version (see below) |
| `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 |

## Model Versions

| Version | Description |
|---------|-------------|
| `chirp-v3-5` | Version 3.5 |
| `chirp-v4` | Version 4.0 |
| `chirp-auk` | Version 4.5 |
| `chirp-bluejay` | Version 4.5+ |
| `chirp-crow` | Version 5.0 |
| `chirp-fenix` | Version 5.5 |

## Model Limits

| Version | Prompt Limit | Style Limit |
|---------|--------------|-------------|
| v3.5, v4 | 3,000 chars | 200 chars |
| v4.5, v4.5+, v5, v5.5 | 5,000 chars | 1,000 chars |
| Simple Mode | 500 chars | - |

## Example - Simple Mode

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "suno-ai/music",
    "input": {
      "mv": "chirp-bluejay",
      "custom": false,
      "gpt_description_prompt": "[Verse 1]\nHello world\n[Chorus]\nThis is my song",
      "make_instrumental": false,
      "title": "My First Song"
    }
  }'
```

## Example - Custom Mode

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "suno-ai/music",
    "input": {
      "mv": "chirp-bluejay",
      "custom": true,
      "prompt": "[Verse 1]\nWalking down the street at night...",
      "tags": "pop, electronic, upbeat",
      "title": "Night Walk",
      "negative_tags": "metal, jazz"
    }
  }'
```

## Response

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

================================================================================
Extend Music
================================================================================

Extend an existing song or uploaded audio.

## Model

```
suno-ai/extend
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mv` | string | Yes | Model version |
| `custom` | boolean | Yes | Simple or custom mode |
| `clip_id` | string | No | Existing Suno clip ID to extend |
| `audio_url` | string | No | Audio file URL to extend |
| `continue_at` | number | Yes | Time in seconds where extension should begin |
| `gpt_description_prompt` | string | No | Simple mode description |
| `prompt` | string | No | Custom mode lyrics/prompt |
| `title` | string | No | Title for extended version |
| `make_instrumental` | boolean | No | Generate instrumental |

<Note>
  Provide either `clip_id` (for Suno-generated clips) or `audio_url` (for uploaded audio).
</Note>

## Example - Extend Existing Clip

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "suno-ai/extend",
    "input": {
      "mv": "chirp-bluejay",
      "custom": false,
      "clip_id": "69ad968a-23c4-40e0-9cdc-80f9649c5209",
      "continue_at": 99.6,
      "gpt_description_prompt": "Continue the epic chorus"
    }
  }'
```

## Example - Upload and Extend

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "suno-ai/extend",
    "input": {
      "mv": "chirp-bluejay",
      "custom": true,
      "audio_url": "https://example.com/audio.mp3",
      "continue_at": 60,
      "prompt": "[Verse 3]\nExtended lyrics here...",
      "title": "Extended Version"
    }
  }'
```

## Response

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

================================================================================
Cover Generation
================================================================================

Generate a cover version of an existing song or uploaded audio.

## Model

```
suno-ai/cover
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mv` | string | Yes | Model version |
| `custom` | boolean | Yes | Simple or custom mode |
| `clip_id` | string | No | Existing Suno clip ID |
| `audio_url` | string | No | Audio file URL |
| `gpt_description_prompt` | string | No | Simple mode description |
| `prompt` | string | No | Custom mode prompt |
| `title` | string | No | Title for cover |
| `make_instrumental` | boolean | No | Generate instrumental |

## Example - Cover Existing Clip

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "suno-ai/cover",
    "input": {
      "mv": "chirp-bluejay",
      "custom": false,
      "clip_id": "5a6bb955-1536-4f43-877a-b4aa9fb18a4e",
      "gpt_description_prompt": "Jazz style cover with saxophone"
    }
  }'
```

## Example - Upload and Cover

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "suno-ai/cover",
    "input": {
      "mv": "chirp-bluejay",
      "custom": true,
      "audio_url": "https://example.com/audio.mp3",
      "prompt": "Acoustic guitar cover with soft vocals",
      "title": "Acoustic Cover"
    }
  }'
```

## Response

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

================================================================================
Add Vocals
================================================================================

Add vocals to uploaded music. Only works with uploaded audio, not Suno-generated clips.

## Model

```
suno-ai/add-vocals
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mv` | string | Yes | Model version |
| `clip_id` | string | Yes | Clip ID from uploaded audio |
| `audio_url` | string | No | Audio file URL |
| `gpt_description_prompt` | string | No | Vocal description/lyrics |
| `prompt` | string | No | Custom mode prompt |
| `start_s` | number | No | Start time in seconds |
| `end_s` | number | No | End time in seconds |
| `make_instrumental` | boolean | No | Generate instrumental |
| `title` | string | No | Title for result |

## Example

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "suno-ai/add-vocals",
    "input": {
      "mv": "chirp-bluejay",
      "clip_id": "ec0be483-2de2-4abc-a5ce-3d8258f52ed4",
      "gpt_description_prompt": "[Verse 1]\nNew vocal lyrics here",
      "start_s": 10,
      "end_s": 60
    }
  }'
```

## Response

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

================================================================================
Add Instrumental
================================================================================

Add instrumental backing to uploaded music. Only works with uploaded audio, not Suno-generated clips.

## Model

```
suno-ai/add-instrumental
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mv` | string | Yes | Model version |
| `clip_id` | string | Yes | Clip ID from uploaded audio |
| `audio_url` | string | No | Audio file URL |
| `gpt_description_prompt` | string | No | Simple mode description |
| `prompt` | string | No | Custom mode prompt |
| `start_s` | number | No | Start time in seconds |
| `end_s` | number | No | End time in seconds |
| `title` | string | No | Title for result |

## Example - Simple Mode

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "suno-ai/add-instrumental",
    "input": {
      "mv": "chirp-bluejay",
      "clip_id": "ec0be483-2de2-4abc-a5ce-3d8258f52ed4",
      "gpt_description_prompt": "Hip-hop beats with 808 bass",
      "start_s": 0,
      "end_s": 60
    }
  }'
```

## Example - Custom Mode

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "suno-ai/add-instrumental",
    "input": {
      "mv": "chirp-bluejay",
      "clip_id": "ec0be483-2de2-4abc-a5ce-3d8258f52ed4",
      "prompt": "Rock guitar and drums with heavy bass",
      "title": "With Instrumental",
      "start_s": 0,
      "end_s": 60
    }
  }'
```

## Response

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

================================================================================
Extract Stems
================================================================================

Extract vocals and instrumental tracks from a song.

## Models

| Model | Description |
|-------|-------------|
| `suno-ai/stems` | Extract vocals + instrumental |
| `suno-ai/stems-all` | Extract all stems |

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `clip_id` | string | Yes | Clip ID to extract stems from |
| `title` | string | No | Title for extraction |

## Available Stems (stems-all)

- Vocals
- Backing Vocals
- Drums
- Bass
- Guitar
- Keyboard
- Percussion
- Strings
- Synth
- FX
- Brass
- Woodwinds

## Example - Basic Stems

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "suno-ai/stems",
    "input": {
      "clip_id": "1901ec96-72c6-4c26-8e56-91028ca6070d",
      "title": "My Stems"
    }
  }'
```

## Example - All Stems

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "suno-ai/stems-all",
    "input": {
      "clip_id": "1901ec96-72c6-4c26-8e56-91028ca6070d",
      "title": "All My Stems"
    }
  }'
```

## Response

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

================================================================================
Generate Lyrics
================================================================================

Generate AI-powered lyrics based on a description.

## Model

```
suno-ai/lyrics
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Description of lyrics to generate |
| `mv` | string | Yes | Lyrics model: `remi-v1` or `default` |

## Example

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "suno-ai/lyrics",
    "input": {
      "prompt": "A chill rock song about summer days at the beach",
      "mv": "remi-v1"
    }
  }'
```

## Response

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

## Completed Response

The API returns two variations of lyrics (a and b):

```json
{
  "code": 200,
  "success": true,
  "data": {
    "task_id": "fd743167-d03d-4c48-84c1-2ca01002562b",
    "status": "completed",
    "output": {
      "a": {
        "text": "[Verse]\nOut in the yard\nCrawlin' with all the animals...",
        "title": "All the Days",
        "tags": ["chill rock", "rock"]
      },
      "b": {
        "text": "[Verse]\nGimme those nights on a beach somewhere...",
        "title": "Summer Days",
        "tags": ["rock", "electric guitar", "chill"]
      }
    }
  }
}
```

================================================================================
WAV Export
================================================================================

Export Suno AI clips as high-quality WAV audio files.

## Model

```
suno-ai/wav
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `clip_id` | string | Yes | Clip ID to export as WAV |

## Example

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "suno-ai/wav",
    "input": {
      "clip_id": "1901ec96-72c6-4c26-8e56-91028ca6070d"
    }
  }'
```

## Response

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

================================================================================
Sound Effects
================================================================================

Generate sound effects (not music) using Suno AI.

## Model

```
suno-ai/sound
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | Yes | — | Sound description (e.g. `"dog barking in street"`) |
| `mv` | string | Yes | — | Model version (e.g. `chirp-fenix`) |
| `title` | string | No | — | Sound title |
| `negative_tags` | string | No | — | Tags to avoid |
| `bpm` | int | No | — | Tempo / beats per minute (1–300) |
| `key` | string | No | — | Musical key (see Valid Keys) |
| `type` | string | No | `"one-shot"` | `"one-shot"` or `"loop"` |

## Valid Keys

| Mode | Keys |
|------|------|
| Major | `C` `C#` `D` `D#` `E` `F` `F#` `G` `G#` `A` `A#` `B` |
| Minor | `Cm` `C#m` `Dm` `D#m` `Em` `Fm` `F#m` `Gm` `G#m` `Am` `A#m` `Bm` |

## Example

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "suno-ai/sound",
    "input": {
      "prompt": "dog barking in street",
      "mv": "chirp-fenix",
      "title": "Dog Bark",
      "type": "one-shot",
      "bpm": 120,
      "key": "Am"
    }
  }'
```

## Response

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

Status response uses the same clip format as [Music Generation](/models/audio/suno/music).

================================================================================
Voice Creation
================================================================================

Create a custom voice from audio recordings. This is an async operation — returns a `task_id`, poll for the result.

## Model

```
suno-ai/voice
```

## Flow

1. Call [`GET /v1/resources/suno-ai/voice/verification-phrase`](/api-reference/resources#get-suno-voice-verification-phrase) to get a `phrase_id` and `phrase_text`
2. Record two audio files: a voice sample and the user reading the verification phrase
3. Host both as publicly accessible URLs
4. Call this endpoint with both URLs and the `phrase_id`

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `voice_audio_url` | string | Yes | — | URL to voice recording |
| `verification_audio_url` | string | Yes | — | URL to verification phrase recording |
| `phrase_id` | string | Yes | — | Phrase ID from verification-phrase endpoint |
| `name` | string | Yes | — | Voice name |
| `description` | string | No | `""` | Voice description |
| `styles` | string | No | `""` | Genre tags (e.g. `"funk edm"`) |
| `singer_skill_level` | string | No | `"Beginner"` | `Beginner`, `Intermediate`, `Advanced`, `Professional` |
| `vocal_start_s` | float | No | `0` | Vocal start time in voice audio |
| `vocal_end_s` | float | No | auto | Vocal end time in voice audio |

## Example

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "suno-ai/voice",
    "input": {
      "voice_audio_url": "https://example.com/my-voice.wav",
      "verification_audio_url": "https://example.com/my-verification.wav",
      "phrase_id": "35989bb7-9fe5-4be2-b7d2-ef8124ae3e8b",
      "name": "My Voice",
      "description": "Warm male vocal",
      "styles": "funk edm",
      "singer_skill_level": "Intermediate"
    }
  }'
```

## Response

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

## Status Response (Completed)

```json
{
  "success": true,
  "code": 200,
  "data": {
    "task_id": "...",
    "status": "completed",
    "persona_id": "44706829-...",
    "name": "My Voice",
    "image_url": "https://...",
    "styles": "funk edm"
  }
}
```

## Status Response (Failed — Verification Rejected)

```json
{
  "success": false,
  "code": 400,
  "data": {
    "message": "Voice verification rejected: didnt_say_verification_phrase",
    "status": "failed"
  }
}
```

================================================================================
Custom Model
================================================================================

Train a custom audio model from your own tracks. This is an async operation — returns a `task_id`, poll for the result.

## Model

```
suno-ai/custom-model
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `audio_urls` | list[string] | Yes | — | 6–24 audio URLs to train on |
| `name` | string | Yes | — | Model name |

## Example

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "suno-ai/custom-model",
    "input": {
      "audio_urls": [
        "https://example.com/track1.mp3",
        "https://example.com/track2.mp3",
        "https://example.com/track3.mp3",
        "https://example.com/track4.mp3",
        "https://example.com/track5.mp3",
        "https://example.com/track6.mp3"
      ],
      "name": "audio model v1"
    }
  }'
```

## Response

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

## Status Response (Completed)

```json
{
  "success": true,
  "code": 200,
  "data": {
    "task_id": "...",
    "status": "completed",
    "model_id": "b7bc275b-...",
    "name": "audio model v1",
    "mv": "chirp-custom:b7bc275b-..."
  }
}
```

Use the `mv` value (e.g. `chirp-custom:b7bc275b-...`) in [music generation](/models/audio/suno/music) requests as the model version.

================================================================================
Text-to-Speech
================================================================================

Generate speech audio from text using various voices and optional background sounds.

## Model

```
higgsfield-ai/text-to-speech
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `voice_id` | string | Yes | [Voice ID](/api-reference/resources#higgsfield-ai) |
| `prompt` | string | Yes | Text to convert to speech |
| `sound_id` | string | No | [Background sound ID](/api-reference/resources#higgsfield-ai) |
| `similarity_boost` | integer | No | Voice similarity 0-100 (default 90) |
| `style` | integer | No | Voice style/expressiveness 0-100 (default 60) |
| `speed` | number | No | Speech speed 0-1.2 (default 1.1) |
| `stability` | integer | No | Voice stability 0-100 (default 30) |

## Example

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "higgsfield-ai/text-to-speech",
    "input": {
      "voice_id": "1YxkwUwGY4H3slvZUBRhXW",
      "prompt": "Hello, this is a test of text to speech generation.",
      "sound_id": "DwUP9LmFKqHsvvWQkjLE6",
      "similarity_boost": 90,
      "style": 60,
      "speed": 1.1,
      "stability": 30
    }
  }'
```

## Response

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

## Resources

Get available voices and sounds from the [Resources API](/api-reference/resources):

- **Voices:** `GET /v1/resources/higgsfield-ai/voices`
- **Sounds:** `GET /v1/resources/higgsfield-ai/sounds`

## Voice Categories

Available categories for filtering voices:
- emotions
- stream
- car talk
- podcast
- vlog
- forum
- coaching
- reporter
- selling
- beauty
- professions
- other

================================================================================
Text-to-Speech
================================================================================

Generate high-quality speech audio from text using ElevenLabs models with a variety of voices.

## Model

```
elevenlabs/text-to-speech
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `text` | string | Yes | - | Text to convert to speech |
| `voice` | string | Yes | - | [Voice ID](/api-reference/resources#elevenlabs) to use |
| `model_id` | string | No | `eleven_flash_v2_5` | TTS model (see models below) |
| `output_format` | string | No | `mp3_44100_128` | Audio output format (see formats below) |
| `language_code` | string | No | `auto` | ISO 639-1 language code to force language |
| `seed` | integer | No | - | Seed for deterministic output (0–4294967295) |
| `voice_settings` | object | No | - | Fine-tune voice behavior (see below) |

### voice_settings

| Field | Type | Description |
|-------|------|-------------|
| `stability` | number | 0–1. Lower = more emotional range, higher = more monotone |
| `similarity_boost` | number | 0–1. How closely to match the original voice |
| `style` | number | 0–1. Amplifies the style of the original speaker. Increases latency |
| `speed` | number | Speech speed multiplier. `1.0` = normal, `<1` = slower, `>1` = faster |
| `use_speaker_boost` | boolean | Boost similarity to original voice. Slightly increases latency |

## Available Models

| Model | Description | Languages | Char Limit |
|-------|-------------|-----------|------------|
| `eleven_flash_v2_5` | Ultra-fast, low latency (~75ms) | 32 | 40,000 |
| `eleven_turbo_v2_5` | Balanced quality and speed (~250ms) | 32 | 40,000 |
| `eleven_multilingual_v2` | Highest quality, rich emotion | 29 | 10,000 |
| `eleven_v3` | Most expressive, dramatic delivery | 70+ | 5,000 |

## Output Formats

| Format | Description |
|--------|-------------|
| `mp3_22050_32` | MP3 22.05kHz 32kbps |
| `mp3_44100_64` | MP3 44.1kHz 64kbps |
| `mp3_44100_96` | MP3 44.1kHz 96kbps |
| `mp3_44100_128` | MP3 44.1kHz 128kbps (default) |
| `mp3_44100_192` | MP3 44.1kHz 192kbps |
| `opus_48000_32` | Opus 48kHz 32kbps |
| `opus_48000_64` | Opus 48kHz 64kbps |
| `opus_48000_96` | Opus 48kHz 96kbps |
| `opus_48000_128` | Opus 48kHz 128kbps |
| `opus_48000_192` | Opus 48kHz 192kbps |
| `pcm_16000` | Raw PCM 16kHz |
| `pcm_22050` | Raw PCM 22.05kHz |
| `pcm_24000` | Raw PCM 24kHz |
| `pcm_44100` | Raw PCM 44.1kHz |
| `pcm_48000` | Raw PCM 48kHz |
| `wav_44100` | WAV 44.1kHz |
| `ulaw_8000` | μ-law 8kHz (Twilio) |
| `alaw_8000` | A-law 8kHz |

## Resources

Get available voices from the [Resources API](/api-reference/resources):

```
GET /v1/resources/elevenlabs/voices
```

## Example

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "elevenlabs/text-to-speech",
    "input": {
      "text": "Hello world, this is a test.",
      "voice": "TX3LPaxmHKxFdv7VOQHJ",
      "model_id": "eleven_flash_v2_5",
      "output_format": "mp3_44100_128",
      "language_code": "en",
      "seed": 42,
      "voice_settings": {
        "stability": 0.5,
        "similarity_boost": 0.75,
        "speed": 1.0
      }
    }
  }'
```

## Response

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

## Completed Response

```json
{
  "code": 200,
  "success": true,
  "data": {
    "task_id": "abc123def456",
    "status": "completed",
    "output": {
      "audio_url": "https://files.storagecdn.online/audio/abc123.mp3"
    }
  }
}
```

================================================================================
Text-to-Dialogue
================================================================================

Generate multi-voice dialogue audio using ElevenLabs eleven_v3 model with support for multiple speakers and emotion tags.

## Model

```
elevenlabs/text-to-dialogue
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `dialogue` | array | Yes | - | Array of dialogue objects with `text` and `voice` |
| `language_code` | string | No | `en` | Language code for generation (`"auto"` defaults to `"en"`) |
| `stability` | number | No | `0.5` | Voice stability 0-1 |

### Dialogue Object

Each item in the `dialogue` array must contain:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `text` | string | Yes | Text for this speaker (supports emotion tags like `[excitedly]`) |
| `voice` | string | Yes | [Voice ID](/api-reference/resources#elevenlabs) for this speaker |

<Note>Text-to-Dialogue always uses the `eleven_v3` model - no model selection needed.</Note>

## Resources

Get available voices from the [Resources API](/api-reference/resources):

```
GET /v1/resources/elevenlabs/voices
```

## Example

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "elevenlabs/text-to-dialogue",
    "input": {
      "stability": 0.5,
      "language_code": "auto",
      "dialogue": [
        {
          "text": "[excitedly] Hey Jessica! Have you tried the new ElevenLabs V3?",
          "voice": "TX3LPaxmHKxFdv7VOQHJ"
        },
        {
          "text": "[curiously] Yeah, just got it! The emotion is so amazing.",
          "voice": "cgSgspJ2msm6clMCkdW9"
        }
      ]
    }
  }'
```

## Example - Longer Conversation

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "elevenlabs/text-to-dialogue",
    "input": {
      "stability": 0.6,
      "dialogue": [
        {
          "text": "[warmly] Welcome to the podcast! Today we have a special guest.",
          "voice": "TX3LPaxmHKxFdv7VOQHJ"
        },
        {
          "text": "[grateful] Thanks for having me! I am excited to be here.",
          "voice": "cgSgspJ2msm6clMCkdW9"
        },
        {
          "text": "[interested] So tell us about your latest project.",
          "voice": "TX3LPaxmHKxFdv7VOQHJ"
        },
        {
          "text": "[enthusiastically] Well, it all started last year when...",
          "voice": "cgSgspJ2msm6clMCkdW9"
        }
      ]
    }
  }'
```

## Emotion Tags

You can add emotion tags in square brackets at the start of text to control the speaker's tone:

- `[excitedly]` - Excited, energetic delivery
- `[curiously]` - Questioning, interested tone
- `[warmly]` - Friendly, welcoming tone
- `[sadly]` - Melancholic delivery
- `[angrily]` - Frustrated, angry tone
- `[whispered]` - Quiet, whispered speech
- `[shouted]` - Loud, shouted delivery

## Response

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

## Completed Response

```json
{
  "code": 200,
  "success": true,
  "data": {
    "task_id": "abc123def456",
    "status": "completed",
    "output": {
      "audio_url": "https://files.storagecdn.online/abc123.mp3"
    }
  }
}
```

================================================================================
Sound Effect
================================================================================

Generate sound effects from text descriptions using ElevenLabs AI.

## Model

```
elevenlabs/sound-effect
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `text` | string | Yes | - | Description of the sound effect |
| `prompt_influence` | number | No | `0.5` | How much the prompt influences generation (0-1) |
| `duration` | number/string | No | `auto` | Duration in seconds (0.5-30) or `"auto"` |
| `loop` | boolean | No | `false` | If true, audio loops seamlessly |

## Duration Options

| Value | Description |
|-------|-------------|
| `"auto"` | Automatic duration based on the sound (default) |
| `0.5` - `30` | Specific duration in seconds |

## Example - Basic Sound Effect

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "elevenlabs/sound-effect",
    "input": {
      "text": "wolf howling at the moon"
    }
  }'
```

## Example - With Duration

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "elevenlabs/sound-effect",
    "input": {
      "text": "thunder rumbling in the distance",
      "duration": 5,
      "prompt_influence": 0.7
    }
  }'
```

## Example - Looping Sound

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "elevenlabs/sound-effect",
    "input": {
      "text": "rain falling on a window",
      "loop": true,
      "duration": 10
    }
  }'
```

## Example - Ambient Sound

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "elevenlabs/sound-effect",
    "input": {
      "text": "busy coffee shop with people chatting and cups clinking",
      "prompt_influence": 0.8,
      "duration": "auto",
      "loop": true
    }
  }'
```

## Response

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

## Completed Response

```json
{
  "code": 200,
  "success": true,
  "data": {
    "task_id": "abc123def456",
    "status": "completed",
    "output": {
      "audio_url": "https://files.storagecdn.online/abc123.mp3"
    }
  }
}
```

================================================================================
Voice Isolation
================================================================================

Isolate vocals from audio files using ElevenLabs AI, removing background music and noise.

## Model

```
elevenlabs/voice-isolation
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `audio_url` | string | Yes | URL of the audio file to isolate vocals from |

## Example

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "elevenlabs/voice-isolation",
    "input": {
      "audio_url": "https://example.com/audio.mp3"
    }
  }'
```

## Response

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

## Completed Response

```json
{
  "code": 200,
  "success": true,
  "data": {
    "task_id": "abc123def456",
    "status": "completed",
    "output": {
      "audio_url": "https://files.storagecdn.online/abc123.mp3"
    }
  }
}
```

================================================================================
Speech-to-Text
================================================================================

Transcribe audio files to text using ElevenLabs Scribe v2 with word-level timestamps, speaker diarization, and entity detection.

## Model

```
elevenlabs/speech-to-text
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `audio_url` | string | Yes | - | URL of the audio file to transcribe |
| `language_code` | string | No | auto-detect | ISO 639-1/639-3 language code |
| `diarize` | boolean | No | `false` | Identify who is speaking (speaker diarization) |
| `num_speakers` | integer | No | auto | Max number of speakers (up to 32) |
| `diarization_threshold` | number | No | `0.22` | Higher = fewer speakers, lower = more. Only used when `diarize` is true and `num_speakers` is not set |
| `timestamps_granularity` | string | No | `word` | `"none"`, `"word"`, or `"character"` |
| `tag_audio_events` | boolean | No | `true` | Tag events like (laughter), (music), (footsteps) |
| `entity_detection` | string/array | No | - | Detect entities: `"all"`, or specific types like `"pii"`, `"phi"`, `"pci"`, `"offensive_language"` |
| `temperature` | number | No | `0` | Randomness (0–2). Higher = more diverse output |
| `seed` | integer | No | - | Seed for deterministic results (0–2147483647) |
| `keyterms` | array | No | - | Words/phrases to boost recognition accuracy (max 100, each under 50 chars) |

## Example - Basic Transcription

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "elevenlabs/speech-to-text",
    "input": {
      "audio_url": "https://example.com/audio.mp3"
    }
  }'
```

## Example - With Diarization

```bash
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "elevenlabs/speech-to-text",
    "input": {
      "audio_url": "https://example.com/meeting.mp3",
      "diarize": true,
      "num_speakers": 3,
      "language_code": "en",
      "timestamps_granularity": "word",
      "tag_audio_events": true,
      "entity_detection": "all",
      "keyterms": ["ElevenLabs", "API"]
    }
  }'
```

## Response

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

## Completed Response

```json
{
  "code": 200,
  "success": true,
  "data": {
    "task_id": "abc123def456",
    "status": "completed",
    "output": {
      "language_code": "eng",
      "language_probability": 0.97,
      "text": "Hello world",
      "words": [
        {
          "text": "Hello",
          "start": 0.0,
          "end": 0.5,
          "type": "word",
          "speaker_id": "speaker_0"
        },
        {
          "text": " ",
          "start": 0.5,
          "end": 0.6,
          "type": "spacing"
        },
        {
          "text": "world",
          "start": 0.6,
          "end": 1.0,
          "type": "word",
          "speaker_id": "speaker_0"
        }
      ]
    }
  }
}
```

## Word Object

Each word in the `words` array contains:

| Field | Type | Description |
|-------|------|-------------|
| `text` | string | The transcribed text |
| `start` | number | Start time in seconds |
| `end` | number | End time in seconds |
| `type` | string | `"word"`, `"spacing"`, or audio event type |
| `speaker_id` | string | Speaker identifier (when `diarize` is enabled) |