# UniAll Docs Full Markdown

Generated from the UniAll documentation source for AI and LLM consumption.

Website: https://docs.uniall.ai/
Index: https://docs.uniall.ai/llms.txt

---

# Documentation Overview

Locale: en
URL: https://docs.uniall.ai/
Source: site-docs/overview.md
Description: UniAll developer documentation scope, API style, and selected model documentation structure.

UniAll Docs is the developer reference for the selected API and model pages migrated from the current Apifox documentation scope. The source menu is used as an inventory only. The new site normalizes naming, routes, examples, and page structure so the docs read as one UniAll product surface.

The current public documentation is intentionally narrow. It includes the selected balance, model listing, image, video, audio, and digital-human pages from the approved scope. Standalone quick start, authentication, billing policy, error-code catalog, changelog, and generated API reference pages are not part of this phase.

## Included Documentation

| Area | Current pages | Main purpose |
| --- | --- | --- |
| Account | [Query Balance](/balance) | Confirm account and API key quota before submitting tasks. |
| Model index | [Models](/models) | List model documentation by capability and describe the model-list endpoint. |
| Image generation | [Async Image Generation](/models/image/async-image-generation), Seedream, GPT-Image-2, Nano Series | Use async tasks or synchronous image endpoints depending on the model page. |
| Video generation | Happy-Horse, Seedance 2.0, [Grok Imagine](/models/video/grok-imagine), Veo 3.1, Vidu, Kling, Wan 2.6, Sora 2 | Submit video tasks, poll status, and retrieve completed videos. |
| Audio and music | Music Generation, Speech Synthesis | Generate music or speech with model-specific request fields. |
| Digital humans | Digital Human Video | Generate narrated digital-human videos. |

## API Style

Most model pages use a task-based flow:

1. Submit a task with `Authorization: Bearer sk-***`.
2. Store the returned task ID.
3. Poll the task endpoint every 2 to 5 seconds.
4. Stop polling when the task reaches a terminal status such as `succeeded`, `completed`, or `failed`.
5. Use the returned result URL or content endpoint to download the final asset.

Balance and model listing pages are synchronous API concept pages. They return immediately and do not require polling.

## Common Conventions

| Convention | Rule |
| --- | --- |
| Base URL | `https://api.uniall.ai`; `{BASE_URL}` in examples means this value. |
| Authentication | Use `Authorization: Bearer sk-***` unless a page documents a compatibility-specific header. |
| Request examples | `curl` is the primary example format. |
| Model IDs | Use exact model IDs in JSON, such as `grok-imagine` and `gpt-image-2`. |
| Result URLs | Treat returned URLs as generated assets; do not assume they are permanent unless the product contract says so. |
| Billing | Page-level billing notes explain what affects cost, but exact prices should come from the current product pricing surface. |

## Language And AI-Readable Docs

English is the default locale at `/`. Chinese is available under `/zh-CN/`. Code examples, JSON keys, endpoint paths, and model IDs stay identical across languages.

The site also publishes AI-readable indexes:

- [`/llms.txt`](/llms.txt)
- [`/llms-full.txt`](/llms-full.txt)

Use these files when an agent or external AI tool needs a compact view of the current documentation surface.

## Related Pages

- [Query Balance](/balance)
- [Models](/models)
- [Async Image Generation](/models/image/async-image-generation)
- [Grok Imagine Video Generation](/models/video/grok-imagine)

---

# Query Balance

Locale: en
URL: https://docs.uniall.ai/balance
Source: site-docs/balance.md
Description: Query account balance and credit usage.

## 1. Endpoint Description

 Endpoint standard API key query:

- API Key user ID
- user account balance
- display balance converted by site configuration
- quota information for the current API key

 Endpointuse `sk-...` API Key call, requires usingr.

---

## 2. Details
| | |
| --- | --- |
| Method | `GET` |
| Path | `/api/usage/balance` |
| Authentication | `Authorization: Bearer sk-xxx` |
| Content-Type |, pass |

---

## 3. Request Examples

```bash
curl -X GET "https://api.aijisu.cn/api/usage/balance" \
 -H "Authorization: Bearer sk-your-api-key"
```

---

## 4. SuccessResponse Examples

```json
{
  "success": true,
  "message": "",
  "data": {
    "object": "api_key_balance",
    "user_id": 1,
    "balance": {
      "quota": 1000000,
      "amount": 14.6,
      "display_amount": "¥14.60",
      "quota_per_unit": 500000,
      "quota_display_type": "CNY",
      "currency_symbol": "¥",
      "exchange_rate": 7.3
    },
    "token": {
      "id": 12,
      "name": "my-key",
      "remain_quota": 100000,
      "used_quota": 5000,
      "total_quota": 105000,
      "unlimited_quota": false,
      "expired_time": -1,
      "status": 1,
      "model_limits_enabled": false,
      "model_limits": {}
    }
  }
}
```

---

## 5. responsesParameter Reference

### 5.1 Parameters

| Parameters | Type | Note |
| --- | --- | --- |
| `success` | boolean | WhetherSuccess |
| `message` | string | responses, Success string |
| `data` | object | responses |

### 5.2 `data` Parameters

| Parameters | Type | Note |
| --- | --- | --- |
| `data.object`| string | object type,`api_key_balance` |
| `data.user_id` | number | API Key user ID |
| `data.balance` | object | user account balance |
| `data.token` | object | API Key quota |

### 5.3 `data.balance` Parameters

| Parameters | Type | Note |
| --- | --- | --- |
| `data.balance.quota` | number | useraccount quota, quota |
| `data.balance.amount` | number | balance |
| `data.balance.display_amount` | string | format, |
| `data.balance.quota_per_unit`| number | quota,`500000` `500000 quota = 1 USD` |
| `data.balance.quota_display_type`| string | balance Type, value:`USD`, `CNY`, `CUSTOM`, `TOKENS` |
| `data.balance.currency_symbol`| string |,`$`, `¥`; Type `TOKENS` string |
| `data.balance.exchange_rate`| number | use;`USD` `1`, `CNY`, `CUSTOM` |

### 5.4 `data.token` Parameters

| Parameters | Type | Note |
| --- | --- | --- |
| `data.token.id` | number | API Key ID |
| `data.token.name` | string | API Key name |
| `data.token.remain_quota` | number | API Key balance |
| `data.token.used_quota` | number | API Key usequota |
| `data.token.total_quota`| number | API Key quota,`remain_quota + used_quota` |
| `data.token.unlimited_quota` | boolean | API Key Whether quota |
| `data.token.expired_time`| number | API Key;`-1` |
| `data.token.status`| number | API Key Status;`1` |
| `data.token.model_limits_enabled` | boolean | API Key Whether Modelconstraints |
| `data.token.model_limits`| object | API Key Modelconstraints; constraints object `{}` |

---

---

## 6. Errorresponses

### 6.1 pass API Key

HTTP Status code: `401`

```json
{
  "success": false,
  "message": "Token not provided"
}
```

### 6.2 API Key or

HTTP Status code: `401`

```json
{
  "success": false,
  "message": "Invalid token"
}
```

### 6.3 API Key

HTTP Status code: `403`

```json
{
  "success": false,
  "message": "Token invalid"
}
```

---

## 7. callNote

- use `Authorization: Bearer sk-xxx` pass in API Key.
- return Yes API Key user accountbalance, Yesupstream balance.
- Endpoint return API Key string.
- API Key querybalance.
- API Key orquota, querybalance, Key user.
- `amount` and `display_amount` balance.

---

# Models

Locale: en
URL: https://docs.uniall.ai/models
Source: site-docs/models/index.md
Description: Supported UniAll model documentation grouped by capability, with the model-list endpoint.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

The Models page is the normalized entry point for the selected UniAll model documentation. It groups pages by capability instead of preserving the original Apifox menu order.

Use the model-list endpoint when you need to discover the models available to the current API key at runtime.

## Capability Categories

| Category | Pages | Typical endpoint |
| --- | --- | --- |
| Image Generation | Async Image Generation, Seedream, Seedream 5.0 Pro, GPT-Image-2, GPT-Image-2.5, Nano Series, Kling | `POST /v1/images/tasks`, `POST /v1/images/generations`, or `POST /v1/images/edits` |
| Video Generation | Happy Horse, Seedance 2.0, Seedance 2.5, Grok Imagine, Veo 3.1, Gemini Omni Flash Preview, Vidu Q3, Hailuo, Kling, Wan 2.6, Sora 2 | `POST /v1/video/generations`, `POST /v1/videos`, or `POST /v1beta/interactions` |
| Audio and Music | Music Generation, Speech Synthesis | Model-specific audio endpoints |
| Digital Humans | Digital Human Video | Model-specific avatar video endpoint |

## Model List Endpoint

```http
GET /v1/models
```

The endpoint returns the current model list. UniAll can return compatibility-specific formats based on request headers:

| Request style | Detection rule | Response style |
| --- | --- | --- |
| OpenAI compatible | Default request style | OpenAI model list |
| Anthropic compatible | Includes both `x-api-key` and `anthropic-version` | Anthropic-style model list |
| Gemini compatible | Includes `x-goog-api-key` header or `key` query parameter | Gemini-style model list |

For this documentation scope, the normalized pages focus on the selected image, video, audio, and digital-human capabilities.

## Required Headers

```http
Authorization: Bearer sk-***
```

Compatibility-specific clients may use their native authentication headers when documented by the client format.

## Request Example

```bash
curl "{BASE_URL}/v1/models" \
  -H "Authorization: Bearer sk-***"
```

## Response Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "grok-imagine",
      "object": "model",
      "created": 0,
      "owned_by": "uniall"
    },
    {
      "id": "gpt-image-2.5-flare",
      "object": "model",
      "created": 0,
      "owned_by": "uniall"
    },
    {
      "id": "gpt-image-2",
      "object": "model",
      "created": 0,
      "owned_by": "uniall"
    }
  ]
}
```

## Response Fields

| Field | Type | Description |
| --- | --- | --- |
| `object` | string | List object marker. |
| `data` | array | Available model records. |
| `data[].id` | string | Model ID to use in API requests. |
| `data[].object` | string | Object type for the model record. |
| `data[].created` | number | Creation timestamp if available. Some compatibility responses may use `0`. |
| `data[].owned_by` | string | Owner or provider label. |

## Selection Guidance

- Use [Async Image Generation](/models/image/async-image-generation) when the task is image generation or image editing through a polling flow.
- Use [GPT-Image-2.5](/models/image/gpt-image-2-5) for synchronous GPT Image 2.5 generation and editing.
- Use [Seedream 5.0 Pro Image Generation](/models/image/seedream-5-0-pro) when the model ID is `seedream-5.0-pro`.
- Use [Seedance 2.5](/models/video/seedance-2-5) when the model ID is `seedance2.5`.
- Use [Grok Imagine Video Generation](/models/video/grok-imagine) when the model ID is `grok-imagine`.
- Use [Gemini Omni Flash Preview Video Generation](/models/video/gemini-omni-flash-preview) when the model ID is `gemini-omni-flash-preview`.
- Use [Hailuo Video Generation](/models/video/hailuo) when the model ID is `hailuo-02`, `hailuo-2.3`, or `hailuo-2.3-fast`.
- Use [Kling Image](/models/image/kling) for `kling-v3`, `kling-v3-omni`, or `kling-image-o1` image tasks.
- Use [Kling Video](/models/video/kling) for version-level Kling video models, and [Digital Human Video](/models/avatar/digital-human) for `operation: avatar`.
- Use the capability-specific page for provider-specific fields, billing notes, and task lifecycle details.
- Treat `/v1/models` as runtime discovery. Do not use it as the only source of integration rules.

## Common Errors

| HTTP status | Meaning |
| --- | --- |
| `401` | Missing or invalid authentication. |
| `403` | The current API key is disabled or not allowed to access the model list. |

## Related Pages

- [Documentation Overview](/)
- [Query Balance](/balance)
- [Async Image Generation](/models/image/async-image-generation)
- [Seedream 5.0 Pro Image Generation](/models/image/seedream-5-0-pro)
- [Seedance 2.5](/models/video/seedance-2-5)
- [Grok Imagine Video Generation](/models/video/grok-imagine)
- [Gemini Omni Flash Preview Video Generation](/models/video/gemini-omni-flash-preview)
- [Hailuo Video Generation](/models/video/hailuo)
- [Kling Image](/models/image/kling)
- [Kling Video](/models/video/kling)
- [Digital Human Video](/models/avatar/digital-human)

---

# Music Generation

Locale: en
URL: https://docs.uniall.ai/models/audio/music-generation
Source: site-docs/models/audio/music-generation.md
Description: MiniMax Music generation source documentation.

This document explains how to use MiniMax Music 2.6 async music generation endpoint.

Supported models:

| Model name | Type | Suitable scenarios | Billing mode |
|---|---|---|---|
| `minimax-music-2.6` | music generation | ad music, short-video background music, podcast intro, product promo track, instrumental ambience bed | billed by output audio item count |

Endpoint async task mode:

| Operation | Method | Path |
|---|---|---|
| submit musictask | `POST`|`/v1/audio/tasks` |
| query musictask | `GET`|`/v1/audio/tasks/{task_id}` |

---

## 1. Authentication

 Endpoint requires request headers API Key:

```http
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
Content-Type: application/json
```

Example:

```uri
https://api.xxx.xx
```

---

## 2. Model overview

`minimax-music-2.6` music description and generate music audio. generation video, pass, music, BGM.

Modelsupports:
- pass `prompt`+`lyrics`
- music: pass `prompt`+`is_instrumental: true`

---

## 3. submit musictask

```http
POST https://api.xxx.xx/v1/audio/tasks
```

### 3.1 Request Parameters

| Parameters | Type | Required | Note |
|---|---|---|---|
| `model`| string | Yes |`minimax-music-2.6` |
| `prompt` | string | Yes | music description, recommended style, Purpose, |
| `lyrics` | string | No |. music recommendedprovides |
| `lyrics_optimizer` | boolean | No | Whether |
| `is_instrumental` | boolean | No | Whether to generate music |
| `audio_setting` | object | No | audio object, the platformavailableCapabilitypass through |

### 3.2 submitResponse Examples

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "audio.generation.job",
  "status": "queued"
}
```

Field Reference:

| Field | Note |
|---|---|
| `id`/`task_id` | async task ID, query result |
| `status`| task status, value `queued`, `processing`, `completed`, `failed` |

---

## 4. query musictask

```http
GET https://api.xxx.xx/v1/audio/tasks/{task_id}
```

queryExample:

```bash
curl -X GET "https://api.xxx.xx/v1/audio/tasks/task_xxxxxxxxxxxxx" \
 -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx"
```

Completed Response Example:

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "audio.generation.job",
  "status": "completed",
  "audio_url": "https://api.xxx.xx/media/xxxxx.mp3",
  "result": {
    "outputs": [
      "https://api.xxx.xx/media/xxxxx.mp3"
    ],
    "audios": [
      {
        "url": "https://api.xxx.xx/media/xxxxx.mp3"
      }
    ]
  }
}
```

---

## 5. Request Examples

### 5.1 generation

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-music-2.6",
 "prompt": "A bright synth pop song for a product launch, upbeat, modern commercial style, clean vocal, energetic chorus",
 "lyrics": "Hello future, we are ready now\nLight the skyline, make it loud\nEvery step is shining brighter\nWe are here and moving proud",
 "lyrics_optimizer": true,
 "is_instrumental": false}'
```

### 5.2 generationshort-video background music

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-music-2.6",
 "prompt": "A catchy 30-second lifestyle vlog background track, light guitar, soft beat, sunny mood, no vocal",
 "is_instrumental": true}'
```

### 5.3 generation music

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-music-2.6",
 "prompt": "A warm podcast intro jingle, 8 to 12 seconds feeling, soft piano, subtle electronic pulse, professional and friendly",
 "is_instrumental": true}'
```

### 5.4 generationChinese

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-music-2.6",
 "prompt": "Chinese mandopop brand song, warm female vocal, inspiring chorus, clean arrangement, suitable for a technology brand",
 "lyrics": " \nnew \n \n to change ",
 "lyrics_optimizer": true,
 "is_instrumental": false}'
```

### 5.5 generation music

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-music-2.6",
 "prompt": "Educational course intro music, calm but motivating, soft marimba, piano, gentle percussion, suitable for online learning",
 "is_instrumental": true}'
```

---


## 6. Common Errors

### 6.1 prompt

Error:

```json
{
  "model": "minimax-music-2.6",
  "lyrics": "Hello world"
}
```
`prompt`.

### 6.2 music

If:

```json
{
  "is_instrumental": false
}
```

recommended to pass both `lyrics`.

---

## 7. recommended

1. scenario music style, Purpose.
2. If required, provides.
3. submit `/v1/audio/tasks`.
4. poll `/v1/audio/tasks/{task_id}`.
5. task completed read `audio_url`.

---

## 8. Minimum Valid Request

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-music-2.6",
 "prompt": "A bright short commercial pop song, modern and uplifting",
 "is_instrumental": true}'
```

---

# Audio and Music Overview

Locale: en
URL: https://docs.uniall.ai/models/audio/overview
Source: site-docs/models/audio/overview.md
Description: UniAll speech synthesis and music generation docs entry point.

This category organizes speech synthesis and music generation from the source menu.

## Included Pages

- [Music Generation](/models/audio/music-generation)
- [Speech Synthesis](/models/audio/speech-synthesis)

## Integration Guidance

Use [Music Generation](/models/audio/music-generation) for `minimax-music-2.6` music tasks. Use [Speech Synthesis](/models/audio/speech-synthesis) for MiniMax Speech HD text-to-speech and voice management.

Both capabilities use asynchronous task flows for generated audio. Submit a task, poll by `task_id`, then read the returned audio URL after success.

---

# Speech Synthesis

Locale: en
URL: https://docs.uniall.ai/models/audio/speech-synthesis
Source: site-docs/models/audio/speech-synthesis.md
Description: Generate speech and manage MiniMax voices through UniAll async audio APIs.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

Use MiniMax Speech HD models to generate speech from text. Voice management APIs can list system voices and create reusable private `voice_id` values through voice cloning or voice design.

## When To Use It

- Generate voiceover for short videos, ads, courses, narration, or digital humans.
- Use a public voice from the voice list.
- Clone or design a private voice, then pass its `voice_id` into a speech task.

## Supported Models

| Model | Type | Recommended use |
| --- | --- | --- |
| `minimax-speech-2.8-hd` | Text to speech | Natural short-form speech, emotional narration, ads, digital-human voiceover. |
| `minimax-speech-02-hd` | Text to speech | Audiobooks, course narration, customer-service voice, news reading, long-form narration. |

## Endpoint

```http
POST /v1/audio/tasks
GET  /v1/audio/tasks/{task_id}
GET  /v1/audio/voices
POST /v1/audio/voices/clone
POST /v1/audio/voices/design
```

## Authentication

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## Speech Request Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | `minimax-speech-2.8-hd` or `minimax-speech-02-hd`. |
| `text` | string | Yes | Text to synthesize. |
| `voice_id` | string | Yes | Public or private voice ID. |
| `speed` | number | No | Speaking speed when supported by the model. |
| `volume` | number | No | Output volume when supported. |
| `pitch` | number | No | Pitch adjustment when supported. |
| `format` | string | No | Output format, such as `mp3` or `wav`, when supported. |
| `language` | string | No | Language hint for multilingual text. |
| `audio_setting` | object | No | Advanced audio settings passed through to the provider when supported. |

## Speech Request Example

```bash
curl -X POST "{BASE_URL}/v1/audio/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-2.8-hd",
    "text": "Welcome back. Today we will introduce a faster way to build AI applications.",
    "voice_id": "voice_xxx",
    "format": "mp3",
    "speed": 1
  }'
```

## Submit Response

```json
{
  "task_id": "task_xxx",
  "status": "queued",
  "model": "minimax-speech-2.8-hd",
  "created_at": 1773980459
}
```

## Query Task Status

```bash
curl "{BASE_URL}/v1/audio/tasks/task_xxx" \
  -H "Authorization: Bearer sk-***"
```

```json
{
  "task_id": "task_xxx",
  "status": "succeeded",
  "progress": "100%",
  "output": {
    "audio_url": "https://example.com/speech.mp3"
  },
  "error": null
}
```

## Voice Management

List available voices:

```bash
curl "{BASE_URL}/v1/audio/voices" \
  -H "Authorization: Bearer sk-***"
```

Clone a voice from reference audio:

```bash
curl -X POST "{BASE_URL}/v1/audio/voices/clone" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "brand-narrator",
    "audio_url": "https://example.com/reference.wav"
  }'
```

Design a voice from text:

```bash
curl -X POST "{BASE_URL}/v1/audio/voices/design" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "warm-host",
    "description": "Warm, clear, young adult narrator for product explainers"
  }'
```

Use the returned `voice_id` in later speech tasks.

## Billing Notes

Speech generation is billed by generated audio usage. Voice cloning and voice design may be billed separately because they create reusable private voices. Exact prices should come from the current product pricing surface.

## Common Errors

- Missing `text` or `voice_id`.
- Passing a private `voice_id` that is not visible to the current account.
- Submitting very long text without splitting it into smaller tasks.
- Using an unsupported output format.
- Insufficient balance or disabled API key.

## Related Pages

- [Audio and Music Overview](/models/audio/overview)
- [Music Generation](/models/audio/music-generation)
- [Digital Human Video](/models/avatar/digital-human)

---

# MiniMax Speech HD

Locale: en
URL: https://docs.uniall.ai/models/audio/speech/minimax-speech-hd
Source: site-docs/models/audio/speech/minimax-speech-hd.md
Description: MiniMax Speech HD generation source documentation.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

This document explains how to use MiniMax Speech HD async speech generation model.

Supported models:

| Model name | Type | Recommended scenarios |
|---|---|---|
| `minimax-speech-2.8-hd` | text-to-speech | short-video narration, ad voiceover, digital-human voice, emotional narration, natural spoken voice |
| `minimax-speech-02-hd` | text-to-speech | audiobook, course explanation, customer-service broadcast, news broadcast, long-form narration, multilingual speech |

Endpoint async task mode:

| Operation | Method | Path |
|---|---|---|
| submit speech task | `POST`|`/v1/audio/tasks` |
| query speech task | `GET`|`/v1/audio/tasks/{task_id}` |

 URL example:

```uri
https://api.xxx.xx
```

## 1. Model overview

### 1.1 minimax-speech-2.8-hd

`minimax-speech-2.8-hd` Yes new speech generation model, requires, and speech.

Suitable scenarios:

- short-video narration
- ad voiceover
- digital human

- podcast intro

Recommended text example:

```markdown
<#0.5#>. (laughs)
```

### 1.2 minimax-speech-02-hd

`minimax-speech-02-hd` Yes stable speech generation model, stable, text speech task.

Suitable scenarios:

- audiobook
- course explanation

- news broadcast
- speech
- long-form narration
- multilingual speech generation

Recommended text example:


## 2. Authentication

 requires API Key.

request headers:

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 3. submit speech generationtask

 URL:

```http
POST https://api.xxx.xx/v1/audio/tasks
```

### 3.1 Request Parameters

| Parameters | Type | Required | Note |
|---|---|---|---|
| `model`| string | Yes | Model name, supports `minimax-speech-2.8-hd`, `minimax-speech-02-hd` |
| `text` | string | Yes | generationspeech text |
| `input`| string | No |`text`, OpenAI style |
| `voice_id` | string | No | voice ID, the platformprovides voiceor voice ID |
| `voice` | string | No | voice name, compatibility field |
| `speed`| number | No |, range `0.5` `2.0` |
| `emotion`| string | No |,`happy`, `sad`, `angry`, `fearful`, `disgusted`, `surprised`, `neutral` |
| `language`| string | No | language,`Chinese`, `English`, `Japanese`, `auto` |
| `output_format`| string | No | format, recommended to use `url` |
| `response_format`| string | No | responsesformat, recommended to use `url` |
| `sample_rate`| number | No |,`32000`, `44100` |
| `pronunciation_dict` | object | No | |
| `timber_weights` | array | No | voice, |
| `subtitle_enable` | boolean | No | Whether generation |
| `metadata` | object | No | |
| `extra_body` | object | No | Parameters |

Note:

- `text` and `input` one of two required.
- recommendedprefer using `text`.
- If you pass both `text` and `input`.
- Endpoint async taskEndpoint, submit task requires `task_id` query result.
- billing detail, Chinese, English, punctuation, spaces, line breaks, emoji.
- Example `voice_id`, voice ID.

### 3.2 Request Examples

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-speech-2.8-hd",
 "text": ", use aijisu speech generationservice. "}'
```

### 3.3 submitSuccessResponse Example

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "audio.generation.job",
  "status": "queued",
  "raw_status": "SUBMITTED",
  "progress": "0%",
  "audio_url": null,
  "result": null,
  "error": null
}
```

## 4. Query Taskresult

 URL:

```http
GET https://api.xxx.xx/v1/audio/tasks/{task_id}
```

Request Examples:

```bash
curl -X GET "https://api.xxx.xx/v1/audio/tasks/task_xxxxxxxxxxxxx" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### 4.1 generation Response Example

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "audio.generation.job",
  "status": "in_progress",
  "raw_status": "IN_PROGRESS",
  "progress": "45%",
  "audio_url": null,
  "result": null,
  "error": null
}
```

### 4.2 generation completedResponse Example

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "audio.generation.job",
  "status": "completed",
  "raw_status": "SUCCESS",
  "progress": "100%",
  "audio_url": "https://example.com/audio.mp3",
  "result": {
    "audio_url": "https://example.com/audio.mp3",
    "outputs": [
      "https://example.com/audio.mp3"
    ],
    "audios": [
      {
        "url": "https://example.com/audio.mp3"
      }
    ]
  },
  "error": null
}
```

### 4.3 generationFailedResponse Example

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "audio.generation.job",
  "status": "failed",
  "raw_status": "FAILURE",
  "progress": "100%",
  "audio_url": null,
  "result": null,
  "error": {
    "message": "audio task failed"
  }
}
```

## 5. task status Values

| status | Note |
|---|---|
| `queued` | submit, processing |
| `in_progress` | generation |
| `processing` | In progress |
| `completed` | generation completed |
| `failed` | generationFailed |

recommended 2 5 query task status, recommended poll.

## 6. and

`minimax-speech-2.8-hd` use and.

| | Note |
|---|---|
| `<#0.5#>` | 0.5 |
| `<#1.0#>` | 1 |
| `(laughs)` | |
| `(sighs)` | |
| `(coughs)` | |
| `(clears throat)` | |
| `(gasps)` | |
| `(sniffs)` | |
| `(groans)` | |
| `(yawns)` | |

Example:

```markdown
<#0.8#>. (sighs)
```

## 7. Use Case Examples

### 7.1 Chinese short-video narration

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-speech-2.8-hd",
 "text": ". <#0.4#>. ",
 "voice_id": "Wise_Woman",
 "speed": 1.05,
 "emotion": "happy",
 "output_format": "url"}'
```

### 7.2 course explanation

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-speech-02-hd",
 "text": ". to change. ",
 "voice_id": "Wise_Woman",
 "speed": 0.95,
 "emotion": "neutral",
 "output_format": "url"}'
```

### 7.3 ad voiceover

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-speech-2.8-hd",
 "text": " new. <#0.3#>,! ",
 "voice_id": "Wise_Woman",
 "speed": 1.12,
 "emotion": "happy",
 "output_format": "url"}'
```

### 7.4 audiobook

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-speech-02-hd",
 "text": ".. ",
 "voice_id": "Wise_Woman",
 "speed": 0.88,
 "emotion": "neutral",
 "output_format": "url"}'
```

### 7.5 Details
```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-speech-2.8-hd",
 "text": ". <#0.6#>. (sighs)",
 "voice_id": "Wise_Woman",
 "speed": 0.92,
 "emotion": "sad",
 "output_format": "url"}'
```

### 7.6 Englishpodcast intro

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-speech-2.8-hd",
 "text": "Hey, welcome back to the show. <#0.4#> Today we are talking about how AI is changing creative work. (laughs)",
 "voice_id": "Wise_Woman",
 "speed": 1.0,
 "emotion": "happy",
 "language": "English",
 "output_format": "url"}'
```

### 7.7 language

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-speech-02-hd",
 "text": ", service. Please hold on for a moment. service. ",
 "voice_id": "Wise_Woman",
 "speed": 1.0,
 "language": "auto",
 "emotion": "neutral",
 "output_format": "url"}'
```

### 7.8 news broadcast

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-speech-02-hd",
 "text": " new:, new. ",
 "voice_id": "Wise_Woman",
 "speed": 1.0,
 "emotion": "neutral",
 "output_format": "url"}'
```

### 7.9 digital human

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-speech-2.8-hd",
 "text": ", Yes AI. <#0.4#>. ",
 "voice_id": "Wise_Woman",
 "speed": 1.03,
 "emotion": "happy",
 "output_format": "url"}'
```

### 7.10 Details
```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-speech-2.8-hd",
 "text": "., Yes. ",
 "voice_id": "Wise_Woman",
 "speed": 0.9,
 "emotion": "happy",
 "output_format": "url"}'
```

### 7.11 speech

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-speech-02-hd",
 "text": ". Operation. ",
 "voice_id": "Wise_Woman",
 "speed": 0.96,
 "emotion": "neutral",
 "output_format": "url"}'
```

### 7.12 Details
```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-speech-2.8-hd",
 "text": ". <#1.0#>. <#1.0#>. ",
 "voice_id": "Wise_Woman",
 "speed": 0.82,
 "emotion": "neutral",
 "output_format": "url"}'
```

### 7.13 use input Fieldsubmit

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-speech-02-hd",
 "input": " Yes use input Fieldsubmit speech generationtask. ",
 "voice_id": "Wise_Woman",
 "output_format": "url"}'
```

### 7.14 Details
```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-speech-2.8-hd",
 "text": " use AI, new the platform. ",
 "voice_id": "Wise_Woman",
 "output_format": "url",
 "pronunciation_dict": {"tone_list": ["AI /(A)(I)(ji2)(su4)"]}}'
```

### 7.15 audio

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-speech-2.8-hd",
 "text": " Yesa video quality. ",
 "voice_id": "Wise_Woman",
 "sample_rate": 44100,
 "output_format": "url"}'
```

### 7.16 IVR

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-speech-02-hd",
 "text": "., query, service. ",
 "voice_id": "Wise_Woman",
 "speed": 0.98,
 "emotion": "neutral",
 "output_format": "url"}'
```

### 7.17 video

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-speech-2.8-hd",
 "text": " Yes. <#0.4#> completed, and generation. ",
 "voice_id": "Wise_Woman",
 "speed": 1.02,
 "emotion": "happy",
 "output_format": "url"}'
```

### 7.18 Details
```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-speech-02-hd",
 "text": ", and. ",
 "voice_id": "Wise_Woman",
 "speed": 0.9,
 "emotion": "neutral",
 "output_format": "url"}'
```

## 8. JavaScript callExample

```javascript
const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://api.xxx.xx";

async function createAudioTask() {const response = await fetch(`${BASE_URL}/v1/audio/tasks`, {method: "POST",
 headers: {"Authorization": `Bearer ${API_KEY}`,
 "Content-Type": "application/json"},
 body: JSON.stringify({model: "minimax-speech-2.8-hd",
 text: ", Yesa aijisu generation speech. ",
 voice_id: "Wise_Woman",
 speed: 1,
 emotion: "neutral",
 output_format: "url"})});

 if (!response.ok) {throw new Error(await response.text());}

 return await response.json();}

async function getAudioTask(taskId) {const response = await fetch(`${BASE_URL}/v1/audio/tasks/${taskId}`, {method: "GET",
 headers: {"Authorization": `Bearer ${API_KEY}`}});

 if (!response.ok) {throw new Error(await response.text());}

 return await response.json();}

async function main() {const task = await createAudioTask();
 console.log("task_id:", task.task_id);

 while (true) {const result = await getAudioTask(task.task_id);
 console.log(result.status, result.progress);

 if (result.status === "completed") {console.log("audio_url:", result.audio_url);
 break;}

 if (result.status === "failed") {console.error("failed:", result.error);
 break;}

 await new Promise(resolve => setTimeout(resolve, 3000));}}

main().catch(console.error);
```

## 9. Python callExample

```python
import time
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.xxx.xx"

headers = {"Authorization": f"Bearer {API_KEY}",
 "Content-Type": "application/json"}

payload = {"model": "minimax-speech-02-hd",
 "text": ", Yesa Python submit speech generationtask. ",
 "voice_id": "Wise_Woman",
 "speed": 1,
 "emotion": "neutral",
 "output_format": "url"}

create_resp = requests.post(f"{BASE_URL}/v1/audio/tasks",
 headers=headers,
 json=payload)
create_resp.raise_for_status()

task = create_resp.json()
task_id = task["task_id"]

while True:
 query_resp = requests.get(f"{BASE_URL}/v1/audio/tasks/{task_id}",
 headers={"Authorization": f"Bearer {API_KEY}"})
 query_resp.raise_for_status()

 result = query_resp.json()
 print(result["status"], result.get("progress"))

 if result["status"] == "completed":
 print("audio_url:", result.get("audio_url"))
 break

 if result["status"] == "failed":
 print("failed:", result.get("error"))
 break

 time.sleep(3)
```

## 10. Billing Notes

speech generation billing detail.:

- Chinese
- English

- punctuation
- spaces
- line breaks
- emoji


Example:



 6 characters.

 billing model pricing, rules and account balance rules.

## 11. Model recommended

### 11.1 prefer using minimax-speech-2.8-hd:

- requires
- requires,
- short-video narration
- ad voiceover
- digital human
- speech

### 11.2 prefer using minimax-speech-02-hd:

- long-form narration
- audiobook
- course explanation
- customer-service broadcast
- news broadcast
- language
- stable scenario

## 12. recommended

### 12.1 short-video narration

```json
{
  "model": "minimax-speech-2.8-hd",
  "text": ". <#0.4#>. ",
  "voice_id": "Wise_Woman",
  "speed": 1.05,
  "emotion": "happy",
  "output_format": "url"
}
```

### 12.2 audiobook

```json
{
  "model": "minimax-speech-02-hd",
  "text": ". ",
  "voice_id": "Wise_Woman",
  "speed": 0.88,
  "emotion": "neutral",
  "output_format": "url"
}
```

### 12.3 customer-service broadcast

```json
{
  "model": "minimax-speech-02-hd",
  "text": ", service., service. ",
  "voice_id": "Wise_Woman",
  "speed": 1,
  "emotion": "neutral",
  "output_format": "url"
}
```

### 12.4 Details
```json
{
  "model": "minimax-speech-2.8-hd",
  "text": "? <#0.8#>. (sighs)",
  "voice_id": "Wise_Woman",
  "speed": 0.92,
  "emotion": "sad",
  "output_format": "url"
}
```

### 12.5 English

```json
{
  "model": "minimax-speech-2.8-hd",
  "text": "Welcome back. <#0.4#> Today we are going to talk about how creators can use AI to work faster.",
  "voice_id": "Wise_Woman",
  "speed": 1,
  "emotion": "happy",
  "language": "English",
  "output_format": "url"
}
```

## 13. Details
### 13.1 submit returnaudio?

 speech generationYesasync task. submit endpoint returntask ID, requires queryEndpoint audio URL.

### 13.2 `text` and `input`?

`input` Yes `text`. recommendedprefer using `text`.

### 13.3 generation audio?

 recommended generation audio. If required audio, recommended task submit.

### 13.4 text processing?

recommended task. controlFailed, and.

### 13.5 speech?

recommended:

- reservedpunctuation

- do not use
- scenario `speed`
-, digital humanprefer using `minimax-speech-2.8-hd`

### 13.6 audio URL?

task completed return `audio_url`, download or processing.

### 13.7 Failed?:

- API Key or
- `model`
- `text` or `input`
- pass both `text` and `input`,
- voice ID unavailable
- Parametersformat
- accountbalance or use Model

## 14. Example

###: submit task

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-speech-2.8-hd",
 "text": ", Yes speech. ",
 "voice_id": "Wise_Woman",
 "speed": 1,
 "emotion": "neutral",
 "output_format": "url"}'
```

return:

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "audio.generation.job",
  "status": "queued",
  "raw_status": "SUBMITTED",
  "progress": "0%",
  "audio_url": null,
  "result": null,
  "error": null
}
```

###: Query Task

```bash
curl -X GET "https://api.xxx.xx/v1/audio/tasks/task_xxxxxxxxxxxxx" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

###: audio URL

 `status` `completed`, read:

```json
{
  "audio_url": "https://example.com/audio.mp3"
}
```

 ordownloadgeneration audio.

---

# MiniMax Speech Voice Management

Locale: en
URL: https://docs.uniall.ai/models/audio/speech/voice-management
Source: site-docs/models/audio/speech/voice-management.md
Description: MiniMax Speech voice management source documentation.

This document explains how to use MiniMax voiceCapability, voice list, Voice CloningandVoice Design.

If you only need to generate speech from text, usespeech generation endpoint:

- `POST /v1/audio/tasks`
- `GET /v1/audio/tasks/{task_id}`

If you want to create your own `voice_id`, then use that `voice_id` in speech generation, use this page voice endpoints.

## 1. supportsCapability

| Capability | Endpoint | Whether | Note |
|---|---|---:|---|
| List Voices | `GET /v1/audio/voices` | No | return voiceand privatevoice |
| Voice Cloning | `POST /v1/audio/voices/clone`| Yes | reference audiogenerate a `voice_id` |
| Voice Design | `POST /v1/audio/voices/design`| Yes | description `voice_id` |
| usevoicegenerationspeech | `POST /v1/audio/tasks`| Yes |`voice_id` pass TTS Modelgenerate audio |

 recommended TTS Modeluse:

| Model name | Note |
|---|---|
| `minimax-speech-2.8-hd` | new speech generation model, video, digital human, ad voiceover |
| `minimax-speech-02-hd` | stable speech generation model, audiobook, text |

Voice CloningandVoice Designcreate `voice_id` TTS Modeluse.

## 2. EndpointURL

Example use:

```uri
https://api.xxx.xx
```

 call aijisu API.

| Operation | Method | Path |
|---|---|---|
| List Voices | `GET`|`/v1/audio/voices` |
| Voice Cloning | `POST`|`/v1/audio/voices/clone` |
| Voice Design | `POST`|`/v1/audio/voices/design` |
| submit speech generationtask | `POST`|`/v1/audio/tasks` |
| query speech generationtask | `GET`|`/v1/audio/tasks/{task_id}` |

## 3. Authentication

 Endpoint use Bearer Token:

```http
Authorization: Bearer YOUR_API_KEY
```

Example:

```bash
curl https://api.xxx.xx/v1/audio/voices \
 -H "Authorization: Bearer YOUR_API_KEY"
```

## 4. voice ID Note

`voice_id` Yescall TTS use voice.

voice:

| | Note |
|---|---|
| system voices | the platform voice, user queryanduse |
| privatevoice | Voice CloningorVoice Designcreate voice, and |

Voice CloningandVoice DesignSuccess, Endpoint return `voice_id`. to change, `/v1/audio/tasks` pass in `voice_id` generationspeech.

## 5. List Voices

### 5.1 Details
```http
GET /v1/audio/voices
```

Optional valuesqueryParameters:

| Parameters | Type | Required | Note |
|---|---|---:|---|
| `model`| string | No | compatibilityModel voice, Optional values `minimax-speech-2.8-hd` or `minimax-speech-02-hd` |

### 5.2 queryall voice

```bash
curl "https://api.xxx.xx/v1/audio/voices" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### 5.3 query Speech 2.8 HD voice

```bash
curl "https://api.xxx.xx/v1/audio/voices?model=minimax-speech-2.8-hd" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### 5.4 query Speech 02 HD voice

```bash
curl "https://api.xxx.xx/v1/audio/voices?model=minimax-speech-02-hd" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### 5.5 Response Examples

```json
{
  "object": "audio.voice.list",
  "model": "minimax-speech-2.8-hd",
  "data": [
    {
      "voice_id": "Chinese (Mandarin)_Kind-hearted_Elder",
      "display_name": "Kind-hearted Elder",
      "language": "Chinese (Mandarin)",
      "description": "MiniMax system voice",
      "source_type": "system",
      "visibility": "public",
      "status": "active",
      "compatible_models": [
        "minimax-speech-2.8-hd",
        "minimax-speech-02-hd"
      ],
      "preview_audio_url": null,
      "created_at": "2026-06-23T18:05:59Z"
    },
    {
      "voice_id": "ttv-voice-2026062416421526-E4jmMP8B",
      "display_name": "local-design-taskid-smoke",
      "language": "Chinese (Mandarin)",
      "description": "Local smoke test for task id in sync response.",
      "source_type": "voice_design",
      "visibility": "private",
      "status": "active",
      "compatible_models": [
        "minimax-speech-2.8-hd",
        "minimax-speech-02-hd"
      ],
      "preview_audio_url": "https://api.xxx.xx/media/preview.mp3",
      "created_at": "2026-06-24T08:42:23Z"
    }
  ]
}
```

### 5.6 Response Fields

| Field | Note |
|---|---|
| `object`|`audio.voice.list` |
| `model` | Model |
| `data` | voicearray |
| `data[].voice_id` | voice ID, TTS callpass value |
| `data[].display_name` | voice name |
| `data[].language` | voice language |
| `data[].description` | voice description |
| `data[].source_type`| voice, Yes `system`, `voice_clone`, `voice_design` |
| `data[].visibility`|, Yes `public` or `private` |
| `data[].status`| Status,`active` |
| `data[].compatible_models` | use voice TTS Model |
| `data[].preview_audio_url` | audio URL, |
| `data[].created_at` | Created time |

## 6. Voice Cloning

Voice Cloning areference audio, create newprivate `voice_id`.

Suitable scenarios:

- digital humangeneration voice
-, audiobook, video
- to change call TTS voice

### 6.1 Details
```http
POST /v1/audio/voices/clone
```

 JSON.

| Parameters | Type | Required | Note |
|---|---|---:|---|
| `audio_url` | string | Yes | reference audio URL, requiresEndpointservice |
| `text` | string | recommended | reference audio textor text, qualityandgeneration |
| `preview_text`| string | No |`text` compatibility field. pass both, recommendedand `text` |
| `display_name` | string | No | voice name, list |
| `name`| string | No |`display_name` compatibility field |
| `language`| string | No | voice language,`Chinese (Mandarin)`, `English` |
| `description` | string | No | voice description |
| `noise_reduction` | boolean | No | Whether |
| `need_volume_normalization` | boolean | No | Whether |
| `accuracy` | number/string | No | Parameters, the platform supportspass through |

### 6.2 reference audiorecommended

| | recommended |
|---|---|
| audio |, |
| audio | recommended 10, |
| quality |, music, |
| | stable, do not or |
| text | If audio, recommendedto change `text` |
| | use |

### 6.3 Request Examples

```bash
curl -X POST "https://api.xxx.xx/v1/audio/voices/clone" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"audio_url": "https://example.com/audio/reference-speaker.mp3",
 "text": ". Method. ",
 "display_name": "course-teacher-voice",
 "language": "Chinese (Mandarin)"}'
```

### 6.4 and

```bash
curl -X POST "https://api.xxx.xx/v1/audio/voices/clone" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"audio_url": "https://example.com/audio/noisy-reference.wav",
 "text": " Yes Voice Cloning reference audio, voice stable. ",
 "display_name": "cleaned-brand-speaker",
 "language": "Chinese (Mandarin)",
 "description": " voice",
 "noise_reduction": true,
 "need_volume_normalization": true}'
```

### 6.5 English Voice Cloning

```bash
curl -X POST "https://api.xxx.xx/v1/audio/voices/clone" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"audio_url": "https://example.com/audio/english-host.mp3",
 "text": "Welcome back to the show. Today we are going to explore a simple but powerful idea.",
 "display_name": "english-podcast-host",
 "language": "English",
 "description": "Warm English podcast host voice"}'
```

### 6.6 Response Examples

```json
{
  "object": "audio.voice",
  "model": "minimax-voice-clone",
  "task_id": "task_abc123",
  "voice_id": "VoiceClone123456",
  "preview_audio_url": "https://api.xxx.xx/media/voice-clone-preview.mp3",
  "voice": {
    "voice_id": "VoiceClone123456",
    "display_name": "course-teacher-voice",
    "language": "Chinese (Mandarin)",
    "description": " voice",
    "source_type": "voice_clone",
    "visibility": "private",
    "status": "active",
    "compatible_models": [
      "minimax-speech-2.8-hd",
      "minimax-speech-02-hd"
    ],
    "preview_audio_url": "https://api.xxx.xx/media/voice-clone-preview.mp3",
    "created_at": "2026-06-24T08:42:23Z"
  },
  "billing_contract": {
    "billing_version": "media-v1",
    "public_model": "minimax-voice-clone",
    "operation": "audio.voice_clone",
    "settlement_policy": "fixed_at_estimate",
    "billing_stage": "final",
    "facts": {
      "voice_clones": 1,
      "preview_characters": 36
    }
  },
  "outputs": [
    {
      "url": "https://api.xxx.xx/media/voice-clone-preview.mp3",
      "type": "audio"
    }
  ]
}
```

## 7. Voice Design

Voice Design descriptiongenerate anewprivate `voice_id`, requires passreference audio.

Suitable scenarios:

- video voice
- digital human

- fast generation, voice
- reference audio, description scenario

### 7.1 Details
```http
POST /v1/audio/voices/design
```

 JSON.

| Parameters | Type | Required | Note |
|---|---|---:|---|
| `prompt` | string | Yes | Voice design description, voice description, language, scenario |
| `preview_text` | string | Yes | generation audio text |
| `text`| string | No |`preview_text` compatibility field |
| `display_name` | string | No | voice name, list |
| `name`| string | No |`display_name` compatibility field |
| `language`| string | No | voice language,`Chinese (Mandarin)`, `English` |
| `description` | string | No | voice description |

### 7.2 Prompt recommended

recommended `prompt` description:

| | Example |
|---|---|
| language | Chinese Mandarin, English, Cantonese |
| | male, female |
| | young adult, middle-aged, elder |
| | warm, clear, soft, energetic, calm |
| scenario | product demo, customer service, audiobook, game character |
| | friendly, confident, gentle, dramatic |
| | slow, medium pace, lively |

### 7.3 Chinese

```bash
curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"prompt": "A warm, calm Chinese Mandarin female narrator voice for short product demos, clear diction, gentle confidence, studio quality.",
 "preview_text": ", YesaVoice Design. newspeechCapability. ",
 "display_name": "warm-product-narrator",
 "language": "Chinese (Mandarin)",
 "description": " andshort-video narration "}'
```

### 7.4 digital human voice

```bash
curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"prompt": "A confident Chinese Mandarin female digital human presenter voice, natural conversational tone, bright but not exaggerated, suitable for business explanation videos.",
 "preview_text": ", Yes.. ",
 "display_name": "digital-human-presenter",
 "language": "Chinese (Mandarin)",
 "description": "digital human voice"}'
```

### 7.5 customer-service broadcastvoice

```bash
curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"prompt": "A polite Chinese Mandarin customer service voice, patient, clear, stable, friendly, suitable for service notifications and call center messages.",
 "preview_text": ", processingcompleted.. ",
 "display_name": "customer-service-clear",
 "language": "Chinese (Mandarin)",
 "description": " and voice"}'
```

### 7.6 voice

```bash
curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"prompt": "A young Chinese Mandarin fantasy game character voice, playful, lively, slightly mysterious, expressive but clear.",
 "preview_text": ".. ",
 "display_name": "fantasy-guide-character",
 "language": "Chinese (Mandarin)",
 "description": " voice"}'
```

### 7.7 English voice

```bash
curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"prompt": "A modern English commercial voice, energetic, premium, confident, suitable for product launch ads and social media videos.",
 "preview_text": "Meet the new way to create, edit, and publish your ideas in minutes.",
 "display_name": "english-commercial-premium",
 "language": "English",
 "description": "English commercial voice for product ads"}'
```

### 7.8 audiobook voice

```bash
curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"prompt": "A mature Chinese Mandarin audiobook narrator voice, calm, steady, immersive, with clear pronunciation and comfortable pacing.",
 "preview_text": ". ",
 "display_name": "audiobook-calm-narrator",
 "language": "Chinese (Mandarin)",
 "description": "audiobook voice"}'
```

### 7.9 Response Examples

```json
{
  "object": "audio.voice",
  "model": "minimax-voice-design",
  "task_id": "task_437fb17536aa4ff7830ffb7a39f43a99",
  "voice_id": "ttv-voice-2026062416421526-E4jmMP8B",
  "preview_audio_url": "https://api.xxx.xx/media/design-preview.mp3",
  "voice": {
    "voice_id": "ttv-voice-2026062416421526-E4jmMP8B",
    "display_name": "warm-product-narrator",
    "language": "Chinese (Mandarin)",
    "description": " andshort-video narration ",
    "source_type": "voice_design",
    "visibility": "private",
    "status": "active",
    "compatible_models": [
      "minimax-speech-2.8-hd",
      "minimax-speech-02-hd"
    ],
    "preview_audio_url": "https://api.xxx.xx/media/design-preview.mp3",
    "created_at": "2026-06-24T08:42:23Z"
  },
  "billing_contract": {
    "billing_version": "media-v1",
    "public_model": "minimax-voice-design",
    "operation": "audio.voice_design",
    "settlement_policy": "fixed_at_estimate",
    "billing_stage": "final",
    "facts": {
      "voice_designs": 1,
      "preview_characters": 12
    }
  },
  "outputs": [
    {
      "url": "https://api.xxx.xx/media/design-preview.mp3",
      "type": "audio"
    }
  ]
}
```

## 8. voice_id speech generation

Voice CloningorVoice DesignSuccess, to changereturn `voice_id` `/v1/audio/tasks` generationspeech.

### 8.1 useVoice DesignvoicegenerationChinese

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-speech-2.8-hd",
 "text": "., fast. ",
 "voice_id": "ttv-voice-2026062416421526-E4jmMP8B",
 "speed": 1.0,
 "response_format": "url"}'
```

### 8.2 useVoice Cloningvoicegenerationcourse explanation

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "minimax-speech-02-hd",
 "text": ".. ",
 "voice_id": "VoiceClone123456",
 "speed": 0.95,
 "response_format": "url"}'
```

### 8.3 query speech generationtask

```bash
curl "https://api.xxx.xx/v1/audio/tasks/task_abc123" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### 8.4 speech generationtaskCompleted Response Example

```json
{
  "object": "audio.generation.job",
  "task_id": "task_abc123",
  "model": "minimax-speech-2.8-hd",
  "status": "completed",
  "audio_url": "https://api.xxx.xx/media/output.mp3",
  "result": {
    "audio_url": "https://api.xxx.xx/media/output.mp3",
    "outputs": [
      "https://api.xxx.xx/media/output.mp3"
    ],
    "audios": [
      {
        "url": "https://api.xxx.xx/media/output.mp3"
      }
    ]
  }
}
```

## 9. Billing Notes

 billing aijisu control andaccount. Endpoint Billing basis.

| Capability | billing detail | billing detail |
|---|---|---|
| List Voices | | billing |
| Voice Cloning | + | `voice_clones * 1.5 + preview_characters * 0.0003` |
| Voice Design | + | `voice_designs * 3 + preview_characters * 0.00003` |
| speech generation | | TTS Model billing detail Rules |

Note:

- `preview_characters` Yes text Unicode.
- Chinese, English, spaces, punctuation, line breaks, emoji.
- Yes UTF-8, Yes token.
- Voice CloningandVoice Design submit billing detail.
- If Failed, the platformFailed Rulesprocessing.

## 10. Node.js Example

### 10.1 Voice Design

```javascript
const response = await fetch("https://api.xxx.xx/v1/audio/voices/design", {method: "POST",
 headers: {"Authorization": "Bearer YOUR_API_KEY",
 "Content-Type": "application/json"},
 body: JSON.stringify({prompt: "A warm Chinese Mandarin female narrator voice, clear and calm.",
 preview_text: ", YesVoice Design. ",
 display_name: "node-design-voice",
 language: "Chinese (Mandarin)"})});

const data = await response.json();
console.log(data.voice_id);
console.log(data.preview_audio_url);
```

### 10.2 generation voice_id createspeech task

```javascript
const voiceId = "ttv-voice-2026062416421526-E4jmMP8B";

const response = await fetch("https://api.xxx.xx/v1/audio/tasks", {method: "POST",
 headers: {"Authorization": "Bearer YOUR_API_KEY",
 "Content-Type": "application/json"},
 body: JSON.stringify({model: "minimax-speech-2.8-hd",
 text: " Yesause voicegeneration speech. ",
 voice_id: voiceId,
 response_format: "url"})});

const task = await response.json();
console.log(task.task_id);
```

## 11. Python Example

### 11.1 Voice Cloning

```python
import requests

api_key = "YOUR_API_KEY"

response = requests.post("https://api.xxx.xx/v1/audio/voices/clone",
 headers={"Authorization": f"Bearer {api_key}",
 "Content-Type": "application/json"},
 json={"audio_url": "https://example.com/audio/reference-speaker.mp3",
 "text": ". ",
 "display_name": "python-clone-voice",
 "language": "Chinese (Mandarin)",
 "noise_reduction": True,
 "need_volume_normalization": True},
 timeout=180)

data = response.json()
print(data["voice_id"])
print(data.get("preview_audio_url"))
```

### 11.2 List Voices

```python
import requests

api_key = "YOUR_API_KEY"

response = requests.get("https://api.xxx.xx/v1/audio/voices",
 headers={"Authorization": f"Bearer {api_key}"},
 params={"model": "minimax-speech-2.8-hd"},
 timeout=30)

voices = response.json()["data"]
for voice in voices:
 print(voice["voice_id"], voice.get("display_name"))
```

## 12. Common Errors

### 12.1 Authentication

```json
{
  "error": {
    "message": "API key required.",
    "type": "invalid_request_error",
    "code": "api_key_required"
  }
}
```

Fix: Request headersWhether `Authorization: Bearer YOUR_API_KEY`.

### 12.2 Voice Cloning audio_url

```json
{
  "error": {
    "message": "`audio_url` is required.",
    "type": "invalid_request_error",
    "code": "invalid_request_parameter"
  }
}
```

Fix: pass in reference audio URL.

### 12.3 Voice Design prompt

```json
{
  "error": {
    "message": "`prompt` is required.",
    "type": "invalid_request_error",
    "code": "invalid_request_parameter"
  }
}
```

Fix: description, language, scenario, and.

### 12.4 Voice Design preview_text

```json
{
  "error": {
    "message": "`preview_text` is required.",
    "type": "invalid_request_error",
    "code": "invalid_request_parameter"
  }
}
```

Fix: pass in generation audio text.

### 12.5 voice_id unavailable

```json
{
  "error": {
    "message": "`voice_id` is not visible for the current client or is not compatible with this model",
    "type": "invalid_request_error",
    "code": "invalid_request_parameter"
  }
}
```

- `voice_id` Error.
- use privatevoice.
- voice compatibility TTS Model.
- voice orunavailable.

Fix:

1. call `GET /v1/audio/voices?model=...` query voice.
2. returnresult `voice_id`.
3. `voice_id` `/v1/audio/tasks`.

## 13. Details
### 13.1 Voice Cloning

 reference audio, requires, useVoice Cloning.

 scenario:

- audio.
- audio.
- TTS reference.

### 13.2 Voice Design

 reference audio, description, useVoice Design.

 scenario:

- digital human.
- video generation voice.
- generation.
- fast or voice.

### 13.3 voice recommended

recommended `display_name` usestable, name.

Example:

```markdown
brand-female-presenter
course-teacher-male
customer-service-clear
game-guide-young
english-commercial-premium
```

### 13.4 voice_id

createSuccess, Save:

- `voice_id`
- `display_name`
- `source_type`
- `preview_audio_url`
- `compatible_models`
- `created_at`

 Yes `voice_id`. TTS call requirespass `voice_id`.

### 13.5 callrecommended

- Voice CloningandVoice Design TTS, recommended.
- do not API Key.
- recommended service call aijisu API.
- `voice_id`, create voice.
- create audioand.

---

# Digital Human Video

Locale: en
URL: https://docs.uniall.ai/models/avatar/digital-human
Source: site-docs/models/avatar/digital-human.md
Description: Create Kling V3 digital-human videos from an image and audio or a UniAll voice ID.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

## Overview

Kling digital-human video uses the stable `kling-v3` model with `operation: avatar`. Provide one public image and either an audio URL or a UniAll `voice_id`; do not use the historical Kling Avatar tier model IDs.

UniAll does not currently expose Kling subject-library creation or query endpoints. Do not pass `subject_ids` as a regular public parameter.

## When To Use It

- Use `audio_url` when narration audio already exists.
- Use `voice_id` when the task should use a voice returned by the UniAll voice list or clone endpoint.
- Use `resolution: std` for the standard quality tier or `resolution: pro` for the higher quality tier.

## Endpoint

| Action | Method | Path |
| --- | --- | --- |
| Create a digital-human video task | `POST` | `/v1/videos` |
| Query a video task | `GET` | `/v1/videos/{task_id}` |
| Download a completed video | `GET` | `/v1/videos/{task_id}/content` |
| List Kling voices | `GET` | `/v1/audio/voices?model=kling-v3` |
| Clone a Kling voice | `POST` | `/v1/audio/voices/clone` |

## Authentication

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## Request Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | Use `kling-v3`. |
| `operation` | string | Yes | Use `avatar`. |
| `prompt` | string | Yes | Presentation, expression, and camera guidance required by the UniAll video interface. |
| `image` | string | Yes | Public HTTP(S) image URL for the presenter. |
| `audio_url` | string | Conditional | Public narration-audio URL. Use exactly one of `audio_url` or `voice_id`. |
| `voice_id` | string | Conditional | UniAll voice ID. Use exactly one of `voice_id` or `audio_url`. |
| `resolution` | string | No | `std` or `pro`; default `std`. |
| `watermark` | boolean | No | Whether to add an AIGC watermark. |

Do not pass a `sound` switch. `audio_url` and `voice_id` are lip-sync inputs, and the prompt describes the intended presentation style. Do not pass both voice inputs in one request.

## List Available Voices

```bash
curl "{BASE_URL}/v1/audio/voices?model=kling-v3" \
  -H "Authorization: Bearer sk-***"
```

Use the UniAll `voice_id` returned by the list response. Do not pass an upstream voice ID.

## Clone A Voice

```bash
curl -X POST "{BASE_URL}/v1/audio/voices/clone" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "voice_name": "Product narrator",
    "audio_url": "https://example.com/voice-sample.mp3",
    "text": "This is the preview text for the cloned voice."
  }'
```

Save the UniAll `voice_id` returned by a successful clone request, then pass it to the avatar task.

## Request Examples

### Use An Audio URL

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "operation": "avatar",
    "prompt": "A friendly presenter explains the product naturally in a stable front-facing shot.",
    "image": "https://example.com/presenter.png",
    "audio_url": "https://example.com/speech.mp3",
    "resolution": "pro",
    "watermark": false
  }'
```

### Use A UniAll Voice

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "operation": "avatar",
    "prompt": "A professional presenter delivers the narration with natural expression and a stable front-facing camera.",
    "image": "https://example.com/presenter.png",
    "voice_id": "voice_xxxxxxxxxxxxx",
    "resolution": "std"
  }'
```

## Response Example

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "kling-v3",
  "status": "queued",
  "progress": 0
}
```

## Task Status And Result

Save `id` or `task_id`, then follow [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared 3-to-10-second polling interval, terminal statuses, result fields, error contract, and authenticated download flow.

## Billing Notes

Digital-human video billing normally depends on `kling-v3`, `operation: avatar`, `resolution`, and the output duration. Voice cloning may be billed separately according to the current model catalog. Task submission may reserve balance; the final task settlement and consumption records are authoritative.

## Common Errors

- Using a historical digital-human tier model ID instead of `kling-v3`.
- Omitting `operation: avatar` or the required `prompt`.
- Passing both `audio_url` and `voice_id`, or passing neither.
- Passing an upstream voice ID instead of a UniAll `voice_id`.
- Passing `subject_ids` even though the public subject-library API is not available.
- Passing `sound`, `duration`, or media URLs that the service cannot access publicly.
- Resubmitting a paid task after one polling request times out instead of continuing to query the original `task_id`.

Public responses do not expose provider names, upstream task IDs, routes, credentials, or raw upstream requests.

## Related Pages

- [Kling Video](/models/video/kling)
- [Kling Image](/models/image/kling)
- [Video Generation Overview](/models/video/overview)

---

# Digital Humans Overview

Locale: en
URL: https://docs.uniall.ai/models/avatar/overview
Source: site-docs/models/avatar/overview.md
Description: UniAll digital human narration docs entry point.

This category organizes the digital-human narration workflow from the source menu and the user-supplied Kling V3 contract.

## Included Pages

- [Digital Human Video](/models/avatar/digital-human)

## Integration Guidance

Digital-human narration uses `kling-v3` with `operation: avatar`. Submit one presenter image with either an audio URL or a UniAll `voice_id`, then poll the returned `task_id` until the output video is available.

Use the Kling voice list or clone endpoint on the [Digital Human Video](/models/avatar/digital-human) page when the workflow requires a `voice_id`.

---

# Async Image Generation

Locale: en
URL: https://docs.uniall.ai/models/image/async-image-generation
Source: site-docs/models/image/async-image-generation.md
Description: Async image generation source documentation.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

Updated: 2026-04-29

This document explains how to use the async image task endpoint to call NanoBanana model and `gpt-image-2`, including request flow, Parameters, responses, billing detail rules and differences between the two model families.

## 1. Endpoint Overview

### 1.1 Submit Async Image Task

```http
POST /v1/images/tasks
```

supports:
- `task_type = text2image`
- `task_type = image2image`

### 1.2 Query Async Image Task

```http
GET /v1/images/tasks/{task_id}
```

### 1.3 Details
```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## 2. Model

### 2.1 NanoBanana

upstream Nano Model:

| Model | Note |
| --- | --- |
| `NanoBanana` | NanoBanana Model |
| `NanoBanana2-0.5K` | NanoBanana2, 0.5K |
| `NanoBanana2-1K` | NanoBanana2, 1K |
| `NanoBanana2-2K` | NanoBanana2, 2K |
| `NanoBanana2-4K` | NanoBanana2, 4K |
| `NanoBananaPro-1K` | NanoBanana Pro, 1K |
| `NanoBananaPro-2K` | NanoBanana Pro, 2K |
| `NanoBananaPro-4K` | NanoBanana Pro, 4K |
| `NanoBananaPro-8K` | NanoBanana Pro, 8K |

Note: Whether the user can call Model, the platform Whether and billing detail Model.
### 2.2 gpt-image-2

| Model | Note |
| --- | --- |
| `gpt-image-2`|`size + quality + n` Parameters billing detail image model |

## 3. Request Parameters

 These fields apply to NanoBanana and `gpt-image-2`.

| Parameters | Type | Required | Note |
| --- | --- | --- | --- |
| `model`| string | Yes | Model,`NanoBanana2-0.5K`, `gpt-image-2` |
| `prompt` | string | Yes | image generation or editing prompt |
| `task_type`| string | No |`text2image` or `image2image`. pass, Whether image |
| `image` | string / file | Required | reference. JSON pass an image URL; |
| `images` | string[] | Required | multiple reference images URL, recommended field |
| `size`| string | Model | size.`gpt-image-2` Required, supported values: see [gpt-image-2`size` options](#gpt-image-2-size-options); NanoBanana prefer using `aspect_ratio` controlRatio |
| `aspect_ratio`| string | model-dependent optional values |`NanoBanana`, `NanoBananaPro-*`, `NanoBanana2-*` supports, [NanoBanana Capability](#nanobanana-capability-options);`gpt-image-2` does not support |
| `quality`| string | No | quality.`gpt-image-2` supported values: see [gpt-image-2`quality` options](#gpt-image-2-quality-options); NanoBanana model tier |
| `n`| integer | No | generation. default `1`. `gpt-image-2` `1-8`; NanoBanana does not support|
| `output_format`| string | Optional values | control image type. Nano supported values: see [NanoBanana Capability](#nanobanana-capability-options);`gpt-image-2` supported values: see [gpt-image-2`output_format` options](#gpt-image-2-output-format-options) |


### 3.1 reference pass

 recommended Field:

```json
{
  "image": "https://example.com/input.png"
}
```

```json
{
  "images": [
    "https://example.com/a.png",
    "https://example.com/b.png"
  ]
}
```

do not reference Field. compatibility Field, reference. For new integrations, use `image` or `images`.

Task type Rules:

- image: `text2image` processing
- `image`/`images`/ multipart image file:`image2image` processing
- pass `task_type`, value

## 4. NanoBanana Parameters

NanoBanana use async image task Structure.

### 4.1 JSON

```json
{
  "model": "NanoBanana2-0.5K",
  "task_type": "text2image",
  "prompt": "A small red cube on a clean white desk, minimal product photo, soft daylight",
  "aspect_ratio": "1:1",
  "output_format": "png",
  "n": 1,
  "response_format": "url"
}
```

### 4.2 JSON

```json
{
  "model": "NanoBanana2-0.5K",
  "task_type": "image2image",
  "prompt": "Turn the reference image into a clean product render",
  "image": "https://example.com/input.png",
  "aspect_ratio": "16:9",
  "output_format": "jpeg",
  "n": 1,
  "response_format": "url"
}
```

### 4.3 Parameter Constraints

| Parameters | NanoBanana Rules |
| --- | --- |
| `model` | pass Nano Model |
| `prompt` | Required |
| `task_type`|`text2image`/`image2image`, the platform |
| `aspect_ratio`| recommended to use; control output aspect ratio. value `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, supported range upstream model |
| `output_format`| recommended to use; control image type.`NanoBanana` supports `png`/`jpeg`/`webp`; `NanoBananaPro-*`, `NanoBanana2-*` supports `png`/`jpeg` |
| `size` | NanoBanana controlParameters; pass in, upstreamcompatibilityCapabilityprocessing |
| `quality` | NanoBanana the platform billing detail; model tier |
| `n`| Optional values; default `1`. billing detail generation, value upstreamconstraints |
| `response_format`| recommended `url` |
| image Field | use for single-image input `image`, use for multi-image input `images`; multipart passfile use `image` |

###### NanoBanana capability options

### 4.4 NanoBanana Capability

| Model | `aspect_ratio`|`output_format` |
| --- | --- | --- |
| `NanoBanana`| supports | supports `png`/`jpeg`/`webp` |
| `NanoBananaPro-*`| supports | supports `png`/`jpeg` |
| `NanoBanana2-*`| supports | supports `png`/`jpeg` |

### 4.5 billing detail

NanoBanana Model billing detail, generation `n` or upstreamreturn result.

`aspect_ratio` and `output_format` controlgeneration, and the platform billing detail; Nano model tier model pricing.

 `NanoBanana2-0.5K`, the platform pricing and.

If NanoBanana Model, requires model pricing.

## 5. gpt-image-2 Parameters

`gpt-image-2` useParameters billing detail.`size` YesRequired Parameters;`quality` and `n` defaultvalue;`output_format` control image type; does not support `aspect_ratio`.

### 5.1 JSON

```json
{
  "model": "gpt-image-2",
  "task_type": "text2image",
  "prompt": "A small blue glass sphere on a clean white desk, minimal product photo, soft daylight",
  "size": "1024x768",
  "quality": "low",
  "output_format": "webp",
  "n": 1,
  "response_format": "url"
}
```

### 5.2 JSON

```json
{
  "model": "gpt-image-2",
  "task_type": "image2image",
  "prompt": "Keep the product shape, change the background to a bright studio scene",
  "image": "https://example.com/input.png",
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "png",
  "n": 1,
  "response_format": "url"
}
```

### 5.3 multipart

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
 -H "Authorization: Bearer sk-***" \
 -F "model=gpt-image-2" \
 -F "task_type=image2image" \
 -F "prompt=Keep the subject, make it a clean studio product photo" \
 -F "size=1024x1024" \
 -F "quality=medium" \
 -F "output_format=png" \
 -F "n=1" \
 -F "response_format=url" \
 -F "image=@/path/to/input.png"
```

### 5.4 Parameter Constraints

| Parameters | Rules |
| --- | --- |
| `size`| Required, must be [gpt-image-2`size` options](#gpt-image-2-size-options) value |
| `aspect_ratio`| does not support; use `size` control sizeandRatio |
| `quality`| Optional values, default `medium`, supported values: see [gpt-image-2 `quality` options](#gpt-image-2-quality-options) |
| `output_format`| Optional values, supported values: see [gpt-image-2`output_format` options](#gpt-image-2-output-format-options) |
| `n`| Optional values, default `1`, range `1-8` |
| `response_format`| recommended `url` |
| `task_type`|`text2image`/`image2image`, the platform |

###### GPT Image 2 quality options

`quality` supportsvalue:

| value | |
| --- | --- |
| `low`|`low` |
| `medium`|`medium` |
| `high`|`high` |

###### GPT Image 2 output format options

`output_format` supportsvalue:

| value |
| --- |
| `png` |
| `jpeg` |
| `webp` |

###### GPT Image 2 size options

### 5.5 gpt-image-2 `size` options

`gpt-image-2` `size` control sizeandRatio, does not support pass `aspect_ratio`. `quality` pass `low`, `medium`, `high`; `n` generation.

| Size | Ratio | Orientation | |
| --- | --- | --- | --- |
| `1024x768`|`4:3`| Landscape |`1K` |
| `768x1024`|`3:4`| Portrait |`1K` |
| `1344x1024`|`4:3`| Landscape |`1K` |
| `1024x1344`|`3:4`| Portrait |`1K` |
| `1280x1024`|`5:4`| Landscape |`1K` |
| `1024x1280`|`4:5`| Portrait |`1K` |
| `1360x768`|`16:9`| Landscape |`1K` |
| `768x1360`|`9:16`| Portrait |`1K` |
| `1536x864`|`16:9`| Landscape |`1K` |
| `864x1536`|`9:16`| Portrait |`1K` |
| `1024x1024`|`1:1`| Square |`1K` |
| `1536x1024`|`3:2`| Landscape |`1K` |
| `1024x1536`|`2:3`| Portrait |`1K` |
| `2048x1024`|`2:1`| Landscape |`1K` |
| `1024x2048`|`1:2`| Portrait |`1K` |
| `2016x864`|`21:9`| Landscape |`1K` |
| `864x2016`|`9:21`| Portrait |`1K` |
| `1920x1080`|`16:9`| Landscape |`2K` |
| `1080x1920`|`9:16`| Portrait |`2K` |
| `1536x1536`|`1:1`| Square |`2K` |
| `2048x1360`|`3:2 approximately`| Landscape |`2K` |
| `1360x2048`|`2:3 approximately`| Portrait |`2K` |
| `2048x1536`|`4:3`| Landscape |`2K` |
| `1536x2048`|`3:4`| Portrait |`2K` |
| `2160x1440`|`3:2`| Landscape |`2K` |
| `1440x2160`|`2:3`| Portrait |`2K` |
| `2048x1152`|`16:9`| Landscape |`2K` |
| `1152x2048`|`9:16`| Portrait |`2K` |
| `2688x1344`|`2:1`| Landscape |`2K` |
| `1344x2688`|`1:2`| Portrait |`2K` |
| `2688x1152`|`21:9`| Landscape |`2K` |
| `1152x2688`|`9:21`| Portrait |`2K` |
| `2560x1440`|`16:9`| Landscape |`2K` |
| `1440x2560`|`9:16`| Portrait |`2K` |
| `2048x2048`|`1:1`| Square |`4K` |
| `2560x2048`|`5:4`| Landscape |`2K` |
| `2048x2560`|`4:5`| Portrait |`2K` |
| `2880x2880`|`1:1`| Square |`4K` |
| `3264x2448`|`4:3`| Landscape |`4K` |
| `2448x3264`|`3:4`| Portrait |`4K` |
| `3504x2336`|`3:2`| Landscape |`4K` |
| `2336x3504`|`2:3`| Portrait |`4K` |
| `3840x1920`|`2:1`| Landscape |`4K` |
| `1920x3840`|`1:2`| Portrait |`4K` |
| `3840x1648`|`21:9 approximately`| Landscape |`4K` |
| `1648x3840`|`9:21 approximately`| Portrait |`4K` |
| `3840x2160`|`16:9`| Landscape |`4K` |
| `2160x3840`|`9:16`| Portrait |`4K` |

## 6. submitresponses

submitSuccess returntaskobject.

```json
{
  "task_id": "task_xxx",
  "status": "succeeded",
  "progress": "100%",
  "result_url": "https://example.com/result.png",
  "metadata": {
    "task_type": "text2image",
    "result_count": 1
  },
  "error": null
}
```

Field Reference:

| Field | Note |
| --- | --- |
| `task_id` | the platformtask ID, query |
| `status`|`queued`, `processing`, `succeeded`, `failed` |
| `progress`| task,`0%`, `50%`, `100%` |
| `result_url` | oneresult URL |
| `metadata.task_type` | Task type |
| `metadata.result_count` | result |
| `metadata.result_urls` | result return URL array |
| `error`| Failed Error, Success `null` |

## 7. queryresponses

```bash
curl "{BASE_URL}/v1/images/tasks/task_xxx" \
 -H "Authorization: Bearer sk-***"
```

Successresponses:

```json
{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxx",
    "status": "succeeded",
    "progress": "100%",
    "result_url": "https://example.com/result.png",
    "metadata": {
      "task_type": "text2image",
      "result_count": 1
    },
    "error": null
  }
}
```

recommended poll `2-5`. task `succeeded` or `failed` poll.

## 8. curl Example

### 8.1 NanoBanana

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "NanoBanana2-0.5K",
 "task_type": "text2image",
 "prompt": "A small red cube on a clean white desk, minimal product photo, soft daylight",
 "aspect_ratio": "1:1",
 "output_format": "png",
 "n": 1,
 "response_format": "url"}'
```

### 8.2 gpt-image-2

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "gpt-image-2",
 "task_type": "text2image",
 "prompt": "A small blue glass sphere on a clean white desk, minimal product photo, soft daylight",
 "size": "1024x768",
 "quality": "low",
 "output_format": "webp",
 "n": 1,
 "response_format": "url"}'
```

### 8.3 Query Task

```bash
curl "{BASE_URL}/v1/images/tasks/task_xxx" \
 -H "Authorization: Bearer sk-***"
```

## 9. NanoBanana and gpt-image-2

| | NanoBanana | `gpt-image-2` |
| --- | --- | --- |
| Modellist | Model, Pro andResolution tier | Model |
| | `NanoBanana2-0.5K`|`gpt-image-2` |
| Billing mode | Model * generation | `size + quality` Parameters billing detail *`n` |
| Ratiocontrol | supports `aspect_ratio`, `1:1`,`2:3`,`3:2`,`3:4`,`4:3`,`4:5`,`5:4`,`9:16`,`16:9`,`21:9`| does not support `aspect_ratio`; use `size`, `1024x768`, `1024x1024` |
| formatcontrol | `NanoBanana` supports `png`/`jpeg`/`webp`; `NanoBananaPro-*`, `NanoBanana2-*` supports `png`/`jpeg`| supports `png`/`jpeg`/`webp` |
| `size`| controlParameters; model tierand `aspect_ratio`| Required, [gpt-image-2`size` options](#gpt-image-2-size-options) |
| `quality`| the platform billing detail; model tier | Optional values, default `medium`, and billing detail |
| `n`| Optional values, default `1`, value upstreamconstraints | Optional values, default `1`, range `1-8` |
| `response_format`| recommended `url`| recommended `url` |
| | use for single-image input `image`, use for multi-image input `images`, passreference /editingPath | use for single-image input `image`, use for multi-image input `images`, passreference /editingPath |


## 10. Details
1. use `POST /v1/images/tasks` submit task.
2. return `task_id`.
3. use `GET /v1/images/tasks/{task_id}` polltask.
4. `status = succeeded` read `result_url`.

---

# GPT-Image-2

Locale: en
URL: https://docs.uniall.ai/models/image/gpt-image-2
Source: site-docs/models/image/gpt-image-2.md
Description: Generate or edit images with gpt-image-2 through UniAll image APIs.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

Use `gpt-image-2` for text-to-image and image editing through the OpenAI-compatible image endpoints. This model uses `size` to control both dimensions and aspect ratio. It does not support `aspect_ratio`.

## Endpoint

```http
POST /v1/images/generations
POST /v1/images/edits
```

Use `/v1/images/generations` for text-to-image. Use `/v1/images/edits` when a reference image is included.

## Authentication

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## Request Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | Use `gpt-image-2`. |
| `prompt` | string | Yes | Image generation or editing prompt. |
| `image` | string/object | Conditional | Reference image for editing. |
| `images` | array | Conditional | Multiple reference images when supported. |
| `size` | string | Yes | Output dimensions. Must be one of the supported size values. |
| `quality` | string | No | `low`, `medium`, or `high`. Default: `medium`. |
| `output_format` | string | No | `png`, `jpeg`, or `webp`. |
| `n` | integer | No | Output image count. Default: `1`; range: `1` to `8`. |
| `response_format` | string | No | Prefer `url`. |

## Supported Sizes

Common values:

| Size | Ratio | Tier |
| --- | --- | --- |
| `1024x768` | `4:3` | `1K` |
| `768x1024` | `3:4` | `1K` |
| `1024x1024` | `1:1` | `1K` |
| `1536x864` | `16:9` | `1K` |
| `864x1536` | `9:16` | `1K` |
| `1920x1080` | `16:9` | `2K` |
| `1080x1920` | `9:16` | `2K` |
| `1536x1536` | `1:1` | `2K` |
| `2048x2048` | `1:1` | `4K` |
| `3840x2160` | `16:9` | `4K` |
| `2160x3840` | `9:16` | `4K` |

Use the product model configuration as the source of truth for the complete enabled size matrix.

## Text-To-Image Example

```bash
curl -X POST "{BASE_URL}/v1/images/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A small blue glass sphere on a clean white desk, minimal product photo, soft daylight",
    "size": "1024x768",
    "quality": "low",
    "output_format": "webp",
    "n": 1,
    "response_format": "url"
  }'
```

## Image Editing Example

```bash
curl -X POST "{BASE_URL}/v1/images/edits" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Keep the product shape, change the background to a bright studio scene",
    "image": "https://example.com/input.png",
    "size": "1024x1024",
    "quality": "medium",
    "output_format": "png",
    "n": 1,
    "response_format": "url"
  }'
```

## Response Example

```json
{
  "created": 1778688000,
  "data": [
    {
      "url": "https://example.com/generated.png"
    }
  ]
}
```

## Billing Notes

`gpt-image-2` uses a parameter matrix based on `size + quality`, multiplied by `n`. `output_format` controls file type and is not a separate billing dimension in the current source scope.

## Common Errors

- Missing `size`.
- Passing `aspect_ratio`; use `size` instead.
- Passing `quality` outside `low`, `medium`, or `high`.
- Requesting `n` outside `1` to `8`.
- Using an unsupported size for the current account.

## Related Pages

- [Image Generation Overview](/models/image/overview)
- [Async Image Generation](/models/image/async-image-generation)
- [Seedream Image Generation](/models/image/seedream)

---

# GPT-Image-2.5

Locale: en
URL: https://docs.uniall.ai/models/image/gpt-image-2-5
Source: site-docs/models/image/gpt-image-2-5.md
Description: Generate or edit images with GPT Image 2.5 through UniAll synchronous image APIs.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

GPT Image 2.5 provides two public model IDs:

- `gpt-image-2.5-flare`
- `gpt-image-2.5-sunburst`

Both IDs use the same OpenAI-compatible synchronous image contract. Use `/v1/images/generations` for text-to-image requests and `/v1/images/edits` whenever the request includes reference images.

The models returned by `GET /v1/models` for your API key are the models currently available to your account.

## When To Use It

Use GPT Image 2.5 when you need:

- synchronous text-to-image generation;
- image editing with one or more reference images;
- explicit output size, quality, and format controls;
- URL or Base64 image responses.

## Endpoint

```http
GET /v1/models
POST /v1/images/generations
POST /v1/images/edits
```

The image endpoints wait for the provider result and return the generated image in the same response. They do not create a task that requires polling.

## Authentication

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

The compatibility header below can also be used for authenticated requests:

```http
x-api-key: sk-***
```

## Model Availability

```bash
curl "{BASE_URL}/v1/models" \
  -H "Authorization: Bearer sk-***"
```

A successful response includes the model IDs visible to the current API key:

```json
{
  "object": "list",
  "data": [
    {
      "id": "gpt-image-2.5-flare",
      "object": "model",
      "created": 0,
      "owned_by": "uniall"
    },
    {
      "id": "gpt-image-2.5-sunburst",
      "object": "model",
      "created": 0,
      "owned_by": "uniall"
    }
  ]
}
```

## Request Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | `gpt-image-2.5-flare` or `gpt-image-2.5-sunburst`. |
| `prompt` | string | Yes | Generation or editing instruction. Maximum length: 32,000 characters. |
| `size` | string | No | `auto` or `WIDTHxHEIGHT`. Default: `auto`. |
| `quality` | string | No | `auto`, `low`, `medium`, `high`, `xhigh`, or `max`. Default: `auto`. |
| `n` | integer | No | Number of output images. Default: `1`; range: `1` to `10`. |
| `output_format` | string | No | `png`, `jpeg`, or `webp`. Default: `png`. |
| `response_format` | string | No | `url` or `b64_json`. Default: `b64_json`. |
| `images` | array | Conditional | JSON reference images for `/v1/images/edits`. Each item uses `{"image_url":"..."}`. |
| `mask` | object | No | JSON mask for `/v1/images/edits`. Uses `{"image_url":"..."}` and applies to the first reference image. |

## Size Rules

For an explicit `WIDTHxHEIGHT` value:

- width and height must be positive multiples of `16`;
- the longest edge must not exceed `3840` pixels;
- the aspect ratio must not exceed `3:1`;
- total pixels must be between `655,360` and `8,294,400`.

Use `auto` when the output size should be selected from the request and reference-image context.

## Text-To-Image Example

```bash
curl -X POST "{BASE_URL}/v1/images/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "A red ceramic cup on a clean white table, studio product photo, no text",
    "size": "1024x1024",
    "quality": "medium",
    "output_format": "png",
    "n": 1,
    "response_format": "url"
  }'
```

## JSON Image Editing Example

Use `/v1/images/edits` when the request includes one or more reference images.

```bash
curl -X POST "{BASE_URL}/v1/images/edits" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "Keep the product shape and replace the background with a bright studio scene",
    "images": [
      {"image_url": "https://example.com/product.png"}
    ],
    "size": "auto",
    "quality": "high",
    "output_format": "png",
    "response_format": "url"
  }'
```

Each JSON reference uses an HTTP(S) image URL or a PNG, JPEG, or WebP Base64 Data URL. A request can include up to 16 reference images.

## Base64 Image Editing Example

For JSON editing requests, pass the reference image as a complete Base64 Data URL in `images[].image_url`.

```bash
curl -X POST "{BASE_URL}/v1/images/edits" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "Keep the product shape and replace the background with a bright studio scene",
    "images": [
      {
        "image_url": "data:image/png;base64,BASE64_IMAGE_DATA"
      }
    ],
    "size": "1024x1024",
    "quality": "high",
    "output_format": "png",
    "response_format": "url"
  }'
```

The Data URL must include its MIME prefix, such as `data:image/png;base64,...`, `data:image/jpeg;base64,...`, or `data:image/webp;base64,...`.

## Multipart Image Editing

Use multipart when the source image is a local file. Repeat `image[]` for multiple references.

```bash
curl -X POST "{BASE_URL}/v1/images/edits" \
  -H "Authorization: Bearer sk-***" \
  -F "model=gpt-image-2.5-sunburst" \
  -F "prompt=Keep the subject and change the background to pale blue" \
  -F "image[]=@product.png" \
  -F "response_format=url"
```

A multipart mask can be sent as `mask=@mask.png`. The mask must be a PNG with an alpha channel, smaller than 4 MB, and have the same dimensions as the first reference image.

## Response Example

```json
{
  "created": 1789121337,
  "size": "1024x1024",
  "output_format": "png",
  "data": [
    {
      "url": "https://api.uniall.ai/generated-media/example.png"
    }
  ],
  "usage": {
    "prompt_tokens": 23,
    "completion_tokens": 425,
    "total_tokens": 448,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 23,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 0
    },
    "usage_source": "upstream_response"
  }
}
```

When `response_format` is `b64_json`, each `data` item contains `b64_json` instead of `url`. The value is raw Base64 data without a `data:image/...;base64,` prefix.

## Base64 Response Example

Set `response_format` to `b64_json` when your application needs the image bytes in the JSON response.

```bash
curl -X POST "{BASE_URL}/v1/images/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "A red ceramic cup on a clean white table, studio product photo",
    "size": "1024x1024",
    "quality": "medium",
    "output_format": "png",
    "response_format": "b64_json"
  }'
```

The response contains raw Base64 data without a `data:image/...;base64,` prefix:

```json
{
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}
```

## Related Pages

- [Image Generation Overview](/models/image/overview)
- [GPT-Image-2](/models/image/gpt-image-2)
- [Models](/models)

---

# Edit Images

Locale: en
URL: https://docs.uniall.ai/models/image/gpt-image-2/openai-edit
Source: site-docs/models/image/gpt-image-2/openai-edit.md
Description: GPT-Image-2 edit images endpoint.

Public model name `gpt-image-2-auto`, billed by returned image resolution, quality, and count, API reference to the call examples below, `size` options `auto`
Billing mode: billed by the actual generated image size; async tasks reserve cost first and reconcile when results return


## `gpt-image-2-origin` supported sizes
Billing mode: billed exactly by `size`

### 1K

| Ratio | Landscape | Portrait | Orientation |
| --- | --- | --- | --- |
| `4:3 / 3:4`|`1024x768`, `1344x1024`|`768x1024`, `1024x1344` | Landscape / Portrait |
| `5:4 / 4:5`|`1280x1024`|`1024x1280` | Landscape / Portrait |
| `16:9 / 9:16`|`1360x768`, `1536x864`|`768x1360`, `864x1536` | Landscape / Portrait |
| `1:1`|`1024x1024` | - | Square |
| `3:2 / 2:3`|`1536x1024`|`1024x1536` | Landscape / Portrait |
| `2:1 / 1:2`|`2048x1024`|`1024x2048` | Landscape / Portrait |
| `21:9 / 9:21`|`2016x864`|`864x2016` | Landscape / Portrait |

### 2K

| Ratio | Landscape | Portrait | Orientation |
| --- | --- | --- | --- |
| `16:9 / 9:16`|`1920x1080`, `2048x1152`, `2560x1440`|`1080x1920`, `1152x2048`, `1440x2560` | Landscape / Portrait |
| `1:1`|`1536x1536` | - | Square |
| `3:2 / 2:3`|`2048x1360`, `2160x1440`|`1360x2048`, `1440x2160` | Landscape / Portrait |
| `4:3 / 3:4`|`2048x1536`|`1536x2048` | Landscape / Portrait |
| `2:1 / 1:2`|`2688x1344`|`1344x2688` | Landscape / Portrait |
| `21:9 / 9:21`|`2688x1152`|`1152x2688` | Landscape / Portrait |
| `5:4 / 4:5`|`2560x2048`|`2048x2560` | Landscape / Portrait |

### 4K

| Ratio | Landscape | Portrait | Orientation |
| --- | --- | --- | --- |
| `1:1`|`2048x2048`, `2880x2880` | - | Square |
| `4:3 / 3:4`|`3264x2448`|`2448x3264` | Landscape / Portrait |
| `3:2 / 2:3`|`3504x2336`|`2336x3504` | Landscape / Portrait |
| `2:1 / 1:2`|`3840x1920`|`1920x3840` | Landscape / Portrait |
| `21:9 / 9:21`|`3840x1648`|`1648x3840` | Landscape / Portrait |
| `16:9 / 9:16`|`3840x2160`|`2160x3840` | Landscape / Portrait |

## API Parameters and Examples

### Endpoint


```http
POST /v1/images/edits/
```
### Request Body Parameters

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |


### Response Fields

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |


### Response Examples

#### Example 1

```json
{
  "created": 1777107492,
  "data": [
    {
      "url": "https://xxxxx.com/xxxx.png"
    }
  ]
}
```

---

# Generate Images

Locale: en
URL: https://docs.uniall.ai/models/image/gpt-image-2/openai-generate
Source: site-docs/models/image/gpt-image-2/openai-generate.md
Description: GPT-Image-2 generate images endpoint.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

Public model name `gpt-image-2-auto`, billed by returned image resolution, quality, and count, API reference to the call examples below, `size` options `auto`
Billing mode: billed by the actual generated image size; async tasks reserve cost first and reconcile when results return


## `gpt-image-2-origin` supported sizes
Billing mode: billed exactly by `size`

### 1K

| Ratio | Landscape | Portrait | Orientation |
| --- | --- | --- | --- |
| `4:3 / 3:4`|`1024x768`, `1344x1024`|`768x1024`, `1024x1344` | Landscape / Portrait |
| `5:4 / 4:5`|`1280x1024`|`1024x1280` | Landscape / Portrait |
| `16:9 / 9:16`|`1360x768`, `1536x864`|`768x1360`, `864x1536` | Landscape / Portrait |
| `1:1`|`1024x1024` | - | Square |
| `3:2 / 2:3`|`1536x1024`|`1024x1536` | Landscape / Portrait |
| `2:1 / 1:2`|`2048x1024`|`1024x2048` | Landscape / Portrait |
| `21:9 / 9:21`|`2016x864`|`864x2016` | Landscape / Portrait |

### 2K

| Ratio | Landscape | Portrait | Orientation |
| --- | --- | --- | --- |
| `16:9 / 9:16`|`1920x1080`, `2048x1152`, `2560x1440`|`1080x1920`, `1152x2048`, `1440x2560` | Landscape / Portrait |
| `1:1`|`1536x1536` | - | Square |
| `3:2 / 2:3`|`2048x1360`, `2160x1440`|`1360x2048`, `1440x2160` | Landscape / Portrait |
| `4:3 / 3:4`|`2048x1536`|`1536x2048` | Landscape / Portrait |
| `2:1 / 1:2`|`2688x1344`|`1344x2688` | Landscape / Portrait |
| `21:9 / 9:21`|`2688x1152`|`1152x2688` | Landscape / Portrait |
| `5:4 / 4:5`|`2560x2048`|`2048x2560` | Landscape / Portrait |

### 4K

| Ratio | Landscape | Portrait | Orientation |
| --- | --- | --- | --- |
| `1:1`|`2048x2048`, `2880x2880` | - | Square |
| `4:3 / 3:4`|`3264x2448`|`2448x3264` | Landscape / Portrait |
| `3:2 / 2:3`|`3504x2336`|`2336x3504` | Landscape / Portrait |
| `2:1 / 1:2`|`3840x1920`|`1920x3840` | Landscape / Portrait |
| `21:9 / 9:21`|`3840x1648`|`1648x3840` | Landscape / Portrait |
| `16:9 / 9:16`|`3840x2160`|`2160x3840` | Landscape / Portrait |

## API Parameters and Examples

### Endpoint


```http
POST /v1/images/generations/
```
### Request Body Parameters

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `model`| string | No | | image generation Model.`gpt-image-2-origin` |
| `prompt`| string | Yes | | image text description.`gpt-image-1`32000 characters,`dall-e-2`1000 characters,`dall-e-3` 4000 characters. |
| `size` | string | No | | generation image. gpt-image-2, size must be 1024x768 (Landscape), 1024x1024 (), 1024x1536 (), 1920x1080 (Landscape), 2560x1440 (Landscape) or 3840x2160 (Landscape) one of; |
| `quality`| string | No | | generation image quality. Optional values:`low`, `medium`, `high` |
| `output_format` | string | No | | image format. Optional values:`png / jpeg / webp`, default"png" |
| `n` | string | Yes | | |

### Request Examples

#### Example

```json
{
  "model": "gpt-image-2-origin",
  "prompt": "A cute baby sea otter",
  "size": "1024x1536",
  "quality": "medium",
  "output_format": "png"
}
```

```bash
curl -X POST "{BASE_URL}/v1/images/generations/" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "gpt-image-2-origin",
 "prompt": "A cute baby sea otter",
 "size": "1024x1536",
 "quality": "medium",
 "output_format": "png"}'
```
### Response Fields

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `created` | integer | Yes | | |
| `data` | array | Yes | | |
| `usage` | object | Yes | | |

### Response Examples

#### Success Example

```json
{
  "created": 1777105463,
  "data": [
    {
      "url": "https://xxxxxx/xxx.jpg"
    }
  ]
}
```

---

# Kling

Locale: en
URL: https://docs.uniall.ai/models/image/kling
Source: site-docs/models/image/kling.md
Description: Create and edit images with Kling V3, Omni, and Image O1 through UniAll asynchronous image tasks.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

## Overview

Kling image capabilities use `POST /v1/images/tasks`. Select the workflow with `operation`, quality with the top-level `resolution` field, and output count with `num_images`.

| Model | Image capabilities | Resolution |
| --- | --- | --- |
| `kling-v3` | Text-to-image, single-image editing, outpainting, and subject completion | `1k`, `2k` |
| `kling-v3-omni` | Text-to-image, single-image editing, multi-image reference, and image series | `1k`, `2k`, `4k` |
| `kling-image-o1` | Text-to-image, single-image editing, multi-image reference, and image series | `1k`, `2k`, `4k` |

Availability depends on the model catalog, the API key's model permissions, and currently enabled routes.

## When To Use It

- Use `kling-v3` for text-to-image, single-image editing, outpainting, or completing a subject from one front-facing image.
- Use `kling-v3-omni` for up to four reference images, `4k`, or a series result.
- Use `kling-image-o1` for the same multi-image request structure in an image-only model.

## Endpoint

| Action | Method | Path |
| --- | --- | --- |
| Create an asynchronous image task | `POST` | `/v1/images/tasks` |
| Query an image task | `GET` | `/v1/images/tasks/{task_id}` |

## Authentication

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## Resolution And Ratios

Pass `resolution` at the request body's top level. Do not use `size` in its place. The default is `1k`; omit `resolution` for `outpaint` and `complete_subject`.

- V3 supports `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3`, and `21:9`.
- Omni and Image O1 support the same ratios plus `auto`.

## Operations

| `operation` | Supported models | Required input |
| --- | --- | --- |
| `text_to_image` | V3, Omni, Image O1 | No input image |
| `image_edit` | V3, Omni, Image O1 | One `image` |
| `reference_to_image` | Omni, Image O1 | `images` with two to four reference images |
| `outpaint` | V3 | One `image` and `outpaint` |
| `complete_subject` | V3 | One front-facing `image` |

`kling-v3` does not accept two original images for `reference_to_image`. Use `kling-v3-omni` or `kling-image-o1` for multi-image reference.

## Request Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | `kling-v3`, `kling-v3-omni`, or `kling-image-o1`. |
| `task_type` | string | Yes | `text2image` for text-to-image; `image2image` for other image operations. |
| `operation` | string | Yes | Workflow from the operations table. |
| `prompt` | string | Yes | Prompt required by the UniAll asynchronous image interface. |
| `image` | string | Conditional | One public image URL for single-image operations. |
| `images` | string[] | Conditional | Two to four public image URLs for multi-image reference. |
| `resolution` | string | No | `1k`, `2k`, or supported `4k`; default `1k`. Omit for outpainting and subject completion. |
| `aspect_ratio` | string | No | Output ratio; supported edit requests may use `auto`. |
| `num_images` | integer | No | Number of outputs from `1` to `9`. |
| `negative_prompt` | string | No | Negative prompt for V3 text-to-image. |
| `result_type` | string | No | `single` or `series` for Omni and Image O1. |
| `outpaint` | object | Conditional | Directional expansion ratios for `outpaint`. |
| `watermark` | boolean | No | Whether to add an AIGC watermark. |

## Request Examples

### V3 Text-To-Image

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "task_type": "text2image",
    "operation": "text_to_image",
    "prompt": "Cinematic product photography of a silver watch on a black stone pedestal.",
    "negative_prompt": "blur, deformation, text, watermark",
    "resolution": "2k",
    "aspect_ratio": "16:9",
    "num_images": 1,
    "watermark": false
  }'
```

### V3 Single-Image Editing

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "task_type": "image2image",
    "operation": "image_edit",
    "prompt": "Preserve the subject identity and replace the background with a clean photography studio.",
    "image": "https://example.com/person.png",
    "resolution": "2k",
    "aspect_ratio": "3:4",
    "num_images": 1
  }'
```

### Omni Multi-Image Reference In 4K

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-omni",
    "task_type": "image2image",
    "operation": "reference_to_image",
    "prompt": "Use the first image as the subject and the second image for clothing and color, producing one cinematic portrait.",
    "images": [
      "https://example.com/person.png",
      "https://example.com/style.png"
    ],
    "resolution": "4k",
    "aspect_ratio": "16:9",
    "num_images": 1,
    "result_type": "single"
  }'
```

Use the same multi-image structure with `kling-image-o1` by changing only `model`.

### V3 Outpainting

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "task_type": "image2image",
    "operation": "outpaint",
    "prompt": "Extend the beach and sky naturally while preserving the original lighting and perspective.",
    "image": "https://example.com/source.png",
    "outpaint": {
      "up_expansion_ratio": 0.2,
      "down_expansion_ratio": 0,
      "left_expansion_ratio": 0.1,
      "right_expansion_ratio": 0.1
    },
    "num_images": 1,
    "watermark": false
  }'
```

Each expansion ratio must be from `0` to `2`, at least one direction must be greater than `0`, and the expanded total area cannot exceed three times the original area. Do not pass `resolution` for outpainting.

### V3 Subject Completion

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "task_type": "image2image",
    "operation": "complete_subject",
    "prompt": "Complete the subject image.",
    "image": "https://example.com/front.png"
  }'
```

Subject completion accepts one front-facing image. Do not pass `resolution`, `aspect_ratio`, or `num_images`; `prompt` satisfies the common UniAll image-task requirement and does not replace the image input.

## Response Example

```json
{
  "task_id": "task_xxxxxxxxxxxxx",
  "status": "queued",
  "progress": "0%",
  "result_url": "",
  "metadata": {
    "task_type": "image2image"
  },
  "error": null
}
```

## Task Status And Result

Poll `GET /v1/images/tasks/{task_id}` every 3 to 10 seconds until the task reaches `succeeded` or `failed`. The query response uses outer `code` and `data` fields. On success, read `data.result_url`; for multiple outputs, also read `data.metadata.result_urls`.

Do not submit a duplicate paid task because one query request timed out. Continue querying the original `task_id`. See [Async Image Generation](/models/image/async-image-generation) for the common asynchronous image response flow.

## Billing Notes

Image billing normally depends on the public model, `operation`, `resolution`, input image count, and output image count. Task submission may reserve balance; the task settlement record and current model catalog price are the final billing source.

## Common Errors

- Passing `size` instead of `resolution`.
- Requesting `4k` with `kling-v3`.
- Passing two original images to `kling-v3` with `reference_to_image`.
- Mixing `image`, `images`, and `reference_image_urls` and duplicating the same input.
- Passing `resolution` to `outpaint` or `complete_subject`.
- Passing media URLs that the service cannot access publicly.
- Resubmitting after a query timeout instead of continuing to poll the original task.

Public responses do not expose provider names, upstream task IDs, routes, credentials, or raw upstream requests.

## Related Pages

- [Kling Video](/models/video/kling)
- [Async Image Generation](/models/image/async-image-generation)
- [Digital Human Video](/models/avatar/digital-human)

---

# Nano Series

Locale: en
URL: https://docs.uniall.ai/models/image/nano-series
Source: site-docs/models/image/nano-series.md
Description: Choose a Nano Banana model, resolution, and OpenAI- or Gemini-compatible image workflow.

Use Nano Series models to generate images from text or edit one or more reference images. UniAll exposes the same API key and model family through two request styles; choose one style for each integration.

## Choose An API Style

| Use case | Recommended guide | Result format |
| --- | --- | --- |
| Existing OpenAI Images client, image URLs, or asynchronous jobs | [OpenAI Images Format](./nano-series/openai-format) | URL in `data[].url` |
| Existing Gemini client or Base64 image input and output | [Gemini generateContent Format](./nano-series/gemini-format) | Base64 in `candidates[].content.parts[].inlineData.data` |

Both styles use `https://api.uniall.ai` and the same UniAll API key. Do not mix parameter names between the two formats.

## Recommended Models

| Model | Resolutions | Default | Recommended use |
| --- | --- | --- | --- |
| `nano-banana-2` | `0.5k`, `1k`, `2k`, `4k` | `1k` | General generation, editing, and fast 0.5K previews. |
| `nano-banana-pro` | `1k`, `2k`, `4k` | `1k` | Higher-detail generation and editing. |
| `nano-banana-2-lite` | `1k` | `1k` | Lightweight 1K workloads. |

Use these unified, lowercase model IDs for new integrations. Actual availability depends on the models enabled for your account.

## Supported Aspect Ratios

All three models support:

```markdown
1:1  2:3  3:2  3:4  4:3  4:5  5:4  9:16  16:9  21:9
```

The resolution field differs by API style:

| Output | OpenAI Images | Gemini generateContent |
| --- | --- | --- |
| 0.5K | `resolution: "0.5k"` | `imageSize: "512"` |
| 1K | `resolution: "1k"` | `imageSize: "1K"` |
| 2K | `resolution: "2k"` | `imageSize: "2K"` |
| 4K | `resolution: "4k"` | `imageSize: "4K"` |

0.5K is available only for `nano-banana-2`. Do not send `512K`, and do not use `0.5k` as a Gemini `imageSize`.

## Legacy Model IDs

Earlier fixed-resolution IDs such as `NanoBanana2-1K` and `NanoBananaPro-2K` may remain accepted for compatibility. They are deprecated compatibility aliases and may be removed at any time. New integrations should use a unified model ID and select the resolution in the request.

## Integration Checklist

- Keep `n` set to `1`; each request currently generates one image.
- Use a server-accessible HTTP(S) URL or a complete Data URL for OpenAI-style reference images.
- Use raw Base64 without a `data:image/...;base64,` prefix inside Gemini `inlineData.data`.
- Set synchronous client timeouts up to 600 seconds when needed.
- Do not retry immediately after a client timeout; the original generation may still complete.
- Transfer temporary result URLs to your own storage if you need permanent retention.
- Never log API keys or complete Base64 image payloads.

## Billing Notes

Billing depends on the selected model and resolution. Check the current model pricing available to your account before sending production traffic. A client timeout does not necessarily mean generation or billing stopped.

## Related Pages

- [OpenAI Images Format](./nano-series/openai-format)
- [Gemini generateContent Format](./nano-series/gemini-format)
- [Async Image Generation](/models/image/async-image-generation)

---

# Gemini generateContent Format

Locale: en
URL: https://docs.uniall.ai/models/image/nano-series/gemini-format
Source: site-docs/models/image/nano-series/gemini-format.md
Description: Generate and edit Nano Series images with the Gemini-compatible generateContent endpoint.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

Use this format with Gemini-style clients or when you need Base64 image input and output. The model is part of the URL, and image controls belong in `generationConfig.imageConfig`.

## Endpoint

```http
POST /v1beta/models/{model}:generateContent
```

Replace `{model}` with `nano-banana-2`, `nano-banana-pro`, or `nano-banana-2-lite`.

## Authentication

```http
x-api-key: sk-***
Content-Type: application/json
```

The same UniAll API key works for the OpenAI Images and Gemini formats.

## Request Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `contents` | array | Yes | Conversation content containing one user message. |
| `contents[].role` | string | Yes | Use `user`. |
| `contents[].parts[].text` | string | Yes | Generation or editing instruction. |
| `contents[].parts[].inlineData` | object | Conditional | Reference image for editing. Repeat the part for multiple images. |
| `inlineData.mimeType` | string | Conditional | Image media type, such as `image/png`. |
| `inlineData.data` | string | Conditional | Raw Base64 data without a Data URL prefix. |
| `generationConfig.responseModalities` | string[] | Yes | Use `["TEXT", "IMAGE"]` when text and image output are acceptable. |
| `generationConfig.imageConfig.imageSize` | string | No | `512`, `1K`, `2K`, or `4K`; defaults to `1K`. Model limits apply. |
| `generationConfig.imageConfig.aspectRatio` | string | No | Output ratio such as `1:1`, `3:4`, or `16:9`. |

| Model | Supported `imageSize` values |
| --- | --- |
| `nano-banana-2` | `512`, `1K`, `2K`, `4K` |
| `nano-banana-pro` | `1K`, `2K`, `4K` |
| `nano-banana-2-lite` | `1K` |

## Text-To-Image Example

```bash
curl -X POST "{BASE_URL}/v1beta/models/nano-banana-2:generateContent" \
  -H "x-api-key: sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "A cinematic product photo of a clear perfume bottle on black stone, blue mist, no text"
          }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {
        "imageSize": "512",
        "aspectRatio": "1:1"
      }
    }
  }'
```

## Image Editing Example

Encode the image as raw Base64 before building the JSON request:

```bash
IMAGE_BASE64="$(base64 < ./reference.png | tr -d '\n')"
```

```json
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Keep the subject and composition; replace the background with a rainy neon street"
        },
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "BASE64_IMAGE_DATA"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "TEXT",
      "IMAGE"
    ],
    "imageConfig": {
      "imageSize": "2K",
      "aspectRatio": "3:4"
    }
  }
}
```

Add another `inlineData` part for each additional reference image. Keep the image order consistent with the prompt.

## Response Example

```json
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Image generated."
          },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "iVBORw0KGgoAAAANSUhEUgAA..."
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ]
}
```

Find the part containing `inlineData`, Base64-decode its `data`, and save it using the returned `mimeType`. Some clients may normalize the field names to `inline_data` and `mime_type`.

## Python Example

```python
import base64
import requests

response = requests.post(
    "https://api.uniall.ai/v1beta/models/nano-banana-2:generateContent",
    headers={"x-api-key": "sk-***", "Content-Type": "application/json"},
    json={
        "contents": [{
            "role": "user",
            "parts": [{"text": "An orange cat wearing an astronaut helmet"}],
        }],
        "generationConfig": {
            "responseModalities": ["TEXT", "IMAGE"],
            "imageConfig": {"imageSize": "512", "aspectRatio": "1:1"},
        },
    },
    timeout=600,
)
response.raise_for_status()

for candidate in response.json().get("candidates", []):
    for part in candidate.get("content", {}).get("parts", []):
        image = part.get("inlineData") or part.get("inline_data")
        if image and image.get("data"):
            with open("generated.png", "wb") as output:
                output.write(base64.b64decode(image["data"]))
            raise SystemExit(0)

raise RuntimeError("response did not contain an image")
```

## Legacy Model IDs

Earlier Gemini preview IDs that encode a fixed resolution may remain accepted for compatibility. They are deprecated and may be removed at any time. New integrations should use a unified Nano model in the URL and select `imageSize` in the request.

## Billing Notes

Billing depends on the model and `imageSize`. Check the current model price available to your account. The response may be large because it contains Base64 image data.

## Common Errors

- Sending `imageSize: "0.5k"` or `"512K"`; use `"512"` for 0.5K.
- Requesting `512` from `nano-banana-pro` or `nano-banana-2-lite`.
- Including `data:image/png;base64,` in `inlineData.data`.
- Looking only at the first response part instead of finding the part with `inlineData`.
- Logging the full Base64 response or API key.

## Related Pages

- [Nano Series](../nano-series)
- [OpenAI Images Format](./openai-format)

---

# OpenAI Images Format

Locale: en
URL: https://docs.uniall.ai/models/image/nano-series/openai-format
Source: site-docs/models/image/nano-series/openai-format.md
Description: Generate and edit Nano Series images with synchronous OpenAI Images endpoints or asynchronous UniAll tasks.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

Use this format when your integration expects OpenAI-style JSON fields and image URLs. Text-to-image and image editing have synchronous endpoints; UniAll also provides an asynchronous task flow for clients that should not keep a long connection open.

## Endpoints

| Workflow | Method and path | Behavior |
| --- | --- | --- |
| Text to image | `POST /v1/images/generations` | Waits and returns the image URL. |
| Image editing | `POST /v1/images/edits` | Waits and returns the image URL. |
| Asynchronous generation or editing | `POST /v1/images/tasks` | Returns a task ID immediately. |
| Query asynchronous task | `GET /v1/images/tasks/{task_id}` | Returns status and results. |

## Authentication

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

`x-api-key: sk-***` is also accepted, but Bearer authentication is recommended for OpenAI-style clients.

## Request Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | `nano-banana-2`, `nano-banana-pro`, or `nano-banana-2-lite`. |
| `prompt` | string | Yes | Generation or editing instruction. |
| `resolution` | string | No | `0.5k`, `1k`, `2k`, or `4k`; defaults to `1k`. Model limits apply. |
| `aspect_ratio` | string | No | Output ratio such as `1:1`, `3:4`, or `16:9`. |
| `images` | string[] | Conditional | Reference image URLs or complete Data URLs for editing. |
| `n` | integer | No | Keep at `1`; each request currently generates one image. |
| `output_format` | string | No | Output format such as `png`. |
| `request_id` | string | No | Your non-sensitive correlation ID for asynchronous tasks. |

0.5K is available only for `nano-banana-2` and must be written as `resolution: "0.5k"`.

## Synchronous Text-To-Image

```bash
curl -X POST "{BASE_URL}/v1/images/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A cinematic product photo of a clear perfume bottle on black stone, blue mist, no text",
    "resolution": "0.5k",
    "aspect_ratio": "1:1",
    "n": 1,
    "output_format": "png"
  }'
```

## Synchronous Image Editing

```bash
curl -X POST "{BASE_URL}/v1/images/edits" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "Keep the subject and composition; replace the background with a rainy neon street",
    "images": ["https://example.com/reference/person.png"],
    "resolution": "2k",
    "aspect_ratio": "3:4",
    "n": 1,
    "output_format": "png"
  }'
```

Reference URLs must be directly accessible to the service. Put multiple references in `images` in the order the prompt describes them.

## Synchronous Response

```json
{
  "created": 1787366400,
  "data": [
    {
      "url": "https://media.example.com/generated/image.png",
      "width": 512,
      "height": 512
    }
  ]
}
```

Read `data[0].url` and transfer the asset if you need permanent retention.

## Asynchronous Task

Generation and editing share `POST /v1/images/tasks`. Including `images` makes the request an editing task.

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A cinematic product photo of a clear perfume bottle on black stone",
    "resolution": "0.5k",
    "aspect_ratio": "1:1",
    "n": 1,
    "output_format": "png",
    "request_id": "image-20260822-0001"
  }'
```

```json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "image.generation.job",
  "model": "nano-banana-2",
  "status": "PENDING",
  "progress": 0,
  "image_url": null
}
```

Save `task_id`; do not create a replacement merely because the task is still pending.

## Task Status And Result

```bash
curl "{BASE_URL}/v1/images/tasks/task_xxx" \
  -H "Authorization: Bearer sk-***"
```

Poll every 2 to 3 seconds initially, then back off to every 5 to 10 seconds. Use `?refresh=true` only when you need an immediate upstream refresh, not on every poll.

| Status | Meaning | Action |
| --- | --- | --- |
| `PENDING` | Waiting for processing | Continue polling. |
| `IN_PROGRESS` | Generating | Continue polling. |
| `COMPLETED` | Finished | Read `data[0].url`; fall back to `image_url`. |
| `FAILED` | Failed | Read the public error and stop. |
| `CANCELLED` | Cancelled | Stop polling. |

```json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "model": "nano-banana-2",
  "status": "COMPLETED",
  "progress": 100,
  "image_url": "https://media.example.com/generated/image.png",
  "data": [
    {
      "url": "https://media.example.com/generated/image.png",
      "width": 512,
      "height": 512
    }
  ],
  "error": null
}
```

## Legacy Model IDs

Fixed-resolution aliases such as `NanoBanana2-0.5K` and `NanoBananaPro-4K` may still work for compatibility. They are deprecated and may be removed at any time. Use a unified model ID plus `resolution` for new code.

## Billing Notes

Billing depends on the selected model and resolution. Check the current price available to your account. A disconnected synchronous request or client timeout does not guarantee that generation stopped.

## Common Errors

- Sending `resolution: "512"` or `"512K"` instead of `"0.5k"`.
- Requesting 0.5K from `nano-banana-pro` or `nano-banana-2-lite`.
- Supplying a reference URL that requires a login or temporary cookie.
- Retrying a timed-out request immediately and creating duplicate generations.
- Branching on error-message text instead of HTTP status and structured error fields.

## Related Pages

- [Nano Series](../nano-series)
- [Gemini generateContent Format](./gemini-format)
- [Async Image Generation](/models/image/async-image-generation)

---

# Image Generation Overview

Locale: en
URL: https://docs.uniall.ai/models/image/overview
Source: site-docs/models/image/overview.md
Description: UniAll image generation API category entry point.

Image generation docs cover the selected source-menu pages plus the user-supplied Kling image contract.

## Included Pages

- [Async Image Generation](/models/image/async-image-generation)
- [Seedream Image Generation](/models/image/seedream)
- [Seedream 5.0 Pro Image Generation](/models/image/seedream-5-0-pro)
- [GPT-Image-2 Image Generation](/models/image/gpt-image-2)
- [GPT-Image-2.5](/models/image/gpt-image-2-5)
- [Nano Series Image Generation](/models/image/nano-series)
- [Kling](/models/image/kling)

## Integration Guidance

Start with the async image generation page when the selected model uses a polling flow. Kling uses `/v1/images/tasks` with `operation` for text generation, editing, multi-image reference, outpainting, and subject completion. For `seedream-5.0-pro`, use `/v1/images/generations` for text-to-image requests and `/v1/images/edits` for reference-image requests.

---

# Seedream

Locale: en
URL: https://docs.uniall.ai/models/image/seedream
Source: site-docs/models/image/seedream.md
Description: Seedream image generation source documentation.

this page Seedream image generation model, image model Endpoint, Parameters, constraints, responsesandExample.

## Basic Information

### Authentication

All `/v1/*` endpoints require an API key:

```http
Authorization: Bearer <your_api_key>
```

### supports Model

| Public model | Capability | Billing basis |
|---|---|---:|
| `seedream-4.0` |, image editing | image |
| `seedream-4.5` |, image editing | image |
| `seedream-5.0-lite` |, image editing | image |

 Model name supports andimage editing:

| | OperationType |
|---|---|
| passreference | |
| pass `image`/`image_url`/`image_urls`/`images` | image editing |

> billing detail recommended: image billing detail. `custom_size`, Landscape, Portrait, Ratio billing detail.

## recommended

| scenario | Endpoint | result | return |
|---|---|---:|---|
|, synchronous | `POST /v1/images/generations`| Yes |`data[].url` |
| image editing, synchronous | `POST /v1/images/edits`| Yes |`data[].url` |

## Parameters

### supported parameters

| Parameters | Type | | Required | Note |
|---|---|---|---:|---|
| `model`| string | body | Yes |`seedream-4.0`, `seedream-4.5`, `seedream-5.0-lite` |
| `prompt` | string | body | Yes | oreditingprompt |
| `n`| integer | body | No | image,`1` `6`. OpenAI compatibility field |
| `custom_size`| object | body | No | size,`{"width": 2048, "height": 2048}` |
| `image` | string / array | body / form | required for editing | reference URL, pass or |
| `image_url`| string / object / array | body / form | required for editing | reference URL, compatibility `{"url": "..."}` |
| `image_urls` | array | body / form | required for editing | multiple reference images URL |
| `images` | array | body | required for editing | multiple reference images URL, supportsstringorobject |
| `timeout_seconds` | integer | body | No | synchronousEndpoint |

### `n`

- defaultvalue: `1`
- value: `1`
- value: `6`

Example:

```json
{
  "num_images": 3
}
```

or:

```json
{
  "n": 3
}
```

## `custom_size` sizeRules

format:

```json
{
  "custom_size": {
    "width": 2048,
    "height": 2048
  }
}
```

sizeconstraints:

| Model | | | | Whether 16 |
|---|---:|---:|---:|---:|
| `seedream-4.0`|`921600`|`16777216`|`4096` | No |
| `seedream-4.5`|`3686400`|`16777216`|`4096` | No |
| `seedream-5.0-lite`|`3686400`|`16777216`|`4096` | No |

 size:

| size | Ratio | `seedream-4.0`|`seedream-4.5`|`seedream-5.0-lite` |
|---|---|---:|---:|---:|
| `960x960`|`1:1` | | unavailable, below the minimum pixel size | unavailable, below the minimum pixel size |
| `1280x720`|`16:9` | | unavailable, below the minimum pixel size | unavailable, below the minimum pixel size |
| `720x1280`|`9:16` | | unavailable, below the minimum pixel size | unavailable, below the minimum pixel size |
| `2048x2048`|`1:1` | | | |
| `2560x1440`|`16:9` | | | |
| `1440x2560`|`9:16` | | | |
| `2304x1728`|`4:3` | | | |
| `1728x2304`|`3:4` | | | |
| `4096x4096`|`1:1` |, |, |, |

## reference

image editingmode supports URL reference. does not support pass file.:

```json
{
  "image": "https://example.com/a.png"
}
```

```json
{
  "image_url": "https://example.com/a.png"
}
```

```json
{
  "image_url": {
    "url": "https://example.com/a.png"
  }
}
```

```json
{
  "image_urls": [
    "https://example.com/a.png",
    "https://example.com/b.png"
  ]
}
```

```json
{
  "images": [
    "https://example.com/a.png",
    {
      "url": "https://example.com/b.png"
    },
    {
      "image_url": "https://example.com/c.png"
    }
  ]
}
```

editingconstraints:

| constraints | value |
|---|---:|
| reference up to | `10` |
| up to | `6` |
| + up to | `15` |

Example:

| reference | `num_images` |
|---:|---:|
| `1`|`6` |
| `5`|`6` |
| `9`|`6` |
| `10`|`5` |


## synchronous

###

```bash
curl -X POST "$BASE_URL/v1/images/generations" \
 -H "Authorization: Bearer $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "seedream-4.0",
 "prompt": "one, and "}'
```

responses:

```json
{
  "created": 1778688000,
  "data": [
    {
      "url": "https://example.com/generated-1.png"
    }
  ]
}
```

### generation 6

```bash
curl -X POST "$BASE_URL/v1/images/generations" \
 -H "Authorization: Bearer $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "seedream-4.5",
 "prompt": ", ",
 "num_images": 6,
 "custom_size": {"width": 2048,
 "height": 2048}}'
```

### 16:9 Landscape

`seedream-4.5` and `seedream-5.0-lite`, recommended `2560x1440`:

```bash
curl -X POST "$BASE_URL/v1/images/generations" \
 -H "Authorization: Bearer $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "seedream-5.0-lite",
 "prompt": "16:9, ",
 "n": 2,
 "custom_size": {"width": 2560,
 "height": 1440}}'
```

### 9:16 Portrait

```bash
curl -X POST "$BASE_URL/v1/images/generations" \
 -H "Authorization: Bearer $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "seedream-4.5",
 "prompt": "Portrait, ",
 "num_images": 1,
 "custom_size": {"width": 1440,
 "height": 2560}}'
```

### `seedream-4.0` sizeExample

`1280x720` `seedream-4.0`, `seedream-4.5` and `seedream-5.0-lite`.

```bash
curl -X POST "$BASE_URL/v1/images/generations" \
 -H "Authorization: Bearer $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "seedream-4.0",
 "prompt": "Landscape, ",
 "custom_size": {"width": 1280,
 "height": 720}}'
```

## synchronousimage editing

### JSON reference

```bash
curl -X POST "$BASE_URL/v1/images/edits" \
 -H "Authorization: Bearer $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "seedream-4.0",
 "prompt": "change image into style, reserved subject ",
 "image": "https://example.com/source.png",
 "num_images": 1,
 "custom_size": {"width": 2048,
 "height": 2048}}'
```

### JSON multiple reference images

```bash
curl -X POST "$BASE_URL/v1/images/edits" \
 -H "Authorization: Bearer $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "seedream-4.5",
 "prompt": " reference, ",
 "image_urls": ["https://example.com/product.png",
 "https://example.com/background.png"],
 "n": 3,
 "custom_size": {"width": 2560,
 "height": 1440}}'
```

### `images` arrayobject

```bash
curl -X POST "$BASE_URL/v1/images/edits" \
 -H "Authorization: Bearer $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"model": "seedream-5.0-lite",
 "prompt": "reference one and, generationone style ",
 "images": [{"url": "https://example.com/person.png"},
 {"image_url": "https://example.com/outfit.png"}],
 "num_images": 2,
 "custom_size": {"width": 2048,
 "height": 2048}}'
```

---

# Seedream 5.0 Pro

Locale: en
URL: https://docs.uniall.ai/models/image/seedream-5-0-pro
Source: site-docs/models/image/seedream-5-0-pro.md
Description: Generate or edit images with seedream-5.0-pro through the synchronous UniAll.ai image API.

Use `seedream-5.0-pro` through separate synchronous endpoints for text-to-image generation and image editing. Use `/v1/images/generations` without `image` for text-to-image generation. Use `/v1/images/edits` with one to ten reference images for image-to-image generation and editing.

This guide reflects the public contract updated on July 25, 2026.

## Overview

- Both endpoints return the final image in the same HTTP response. No task polling is required.
- Each request generates exactly one image.
- You can select a `1K` or `2K` tier with an aspect ratio, or pass exact pixel dimensions.
- Reference images can use public URLs or Base64 Data URLs.
- The response can contain a temporary image URL or raw Base64 data.

## Endpoint And Authentication

```http
POST https://api.uniall.ai/v1/images/generations
POST https://api.uniall.ai/v1/images/edits
Authorization: Bearer sk-***
Content-Type: application/json
```

- Text to image: call `/v1/images/generations` without `image`.
- Image to image or image editing: call `/v1/images/edits` and provide `image`.

The Base URL is:

```uri
https://api.uniall.ai
```

If the UniAll.ai console provides a dedicated API address for your account, use the address shown in the console.

## Quick Start

### Text To Image

```bash
curl -X POST "https://api.uniall.ai/v1/images/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro",
    "prompt": "Premium skincare advertising image, a glass bottle on light stone, soft natural light, sharp and readable brand typography",
    "size": "2K",
    "aspect_ratio": "16:9",
    "output_format": "jpeg",
    "response_format": "url"
  }'
```

### Image To Image

```bash
curl -X POST "https://api.uniall.ai/v1/images/edits" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro",
    "prompt": "Keep the product shape and label text, then replace the background with a bright studio scene.",
    "image": "https://example.com/source-product.png",
    "size": "1K",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "response_format": "url"
  }'
```

### Exact Dimensions

Pass exact dimensions through `size` when the output requires a fixed width and height. Do not pass `aspect_ratio` in the same request.

```bash
curl -X POST "https://api.uniall.ai/v1/images/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro",
    "prompt": "Wide product-launch key visual, centered technology product, clean background",
    "size": "2048x1024",
    "output_format": "jpeg",
    "response_format": "url"
  }'
```

## Request Parameters

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `model` | string | Yes | None | Must be `seedream-5.0-pro`. |
| `prompt` | string | Yes | None | Instructions for image generation or editing. |
| `image` | string / string[] | Required for image editing | None | Reference images for `/v1/images/edits`. Accepts public URLs or Base64 Data URLs. Maximum: 10 images. |
| `size` | string | No | `2K` | `1K`, `2K`, or exact `WIDTHxHEIGHT` dimensions. |
| `aspect_ratio` | string | No | Model-selected | Supported with the `1K` and `2K` tiers. Do not use with exact dimensions. |
| `output_format` | string | No | `jpeg` | `jpeg` or `png`. |
| `response_format` | string | No | `url` | `url` or `b64_json`. |
| `watermark` | boolean | No | `true` | Whether to add an "AI generated" watermark. |

The model always generates one image per request.

## Size And Aspect Ratio

Choose one of the following size modes.

### Resolution Tier And Aspect Ratio

```json
{
  "size": "2K",
  "aspect_ratio": "16:9"
}
```

`size` supports `1K` and `2K`. `aspect_ratio` supports `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, and `21:9`.

Common output dimensions are shown below. Treat `data[0].size` in the response as the final value.

| Resolution | `1:1` | `4:3` | `3:4` | `16:9` | `9:16` | `3:2` | `2:3` | `21:9` |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `1K` | `1024x1024` | `1152x864` | `864x1152` | `1424x800` | `800x1424` | `1248x832` | `832x1248` | `1568x672` |
| `2K` | `2048x2048` | `2368x1776` | `1776x2368` | `2816x1584` | `1584x2816` | `2496x1664` | `1664x2496` | `3136x1344` |

When `aspect_ratio` is omitted, the model chooses the composition from the prompt and any reference images.

### Exact Dimensions

```json
{
  "size": "2048x1024"
}
```

Exact dimensions must satisfy all of these conditions:

- `width * height` must be between `921600` and `4624220`, inclusive.
- The width-to-height ratio must be between `1/16` and `16`, inclusive.
- There is no separate 4096-pixel maximum edge. For example, `4200x1000` is valid.
- `aspect_ratio` must not be present because exact dimensions already determine the composition.

## Reference Images

All image-to-image and image-editing requests use `/v1/images/edits`.

Pass a string for one reference image or an array for multiple images:

```json
{
  "image": [
    "https://example.com/product.png",
    "data:image/png;base64,..."
  ]
}
```

Public URLs and Base64 Data URLs can be mixed in one request.

### Public URLs

- The file must be directly reachable from the public internet.
- The request must not depend on cookies, login state, or custom headers.

### Base64 Data URLs

Use the complete Data URL format:

```uri
data:image/png;base64,...
```

- The image media subtype must be lowercase. This rule does not require the Base64 payload itself to be lowercase.
- Supported formats: JPEG, PNG, WEBP, BMP, TIFF, GIF, HEIC, and HEIF.
- Each Data URL image can be up to `30 MB`.
- A request can contain at most 10 reference images in total.

## Response Formats

Input and output formats are independent. A URL input can return Base64 data, and a Base64 input can return a URL.

### URL Response

Request field:

```json
{
  "response_format": "url"
}
```

Response example:

```json
{
  "created": 1784900000,
  "data": [
    {
      "url": "https://example.com/generated.jpeg",
      "size": "2816x1584",
      "output_format": "jpeg"
    }
  ],
  "usage": {
    "generated_images": 1,
    "input_images": 0,
    "output_tokens": 17424,
    "total_tokens": 17424
  }
}
```

The returned URL may expire 24 hours after generation. Download and store the image promptly.

### Base64 Response

Request field:

```json
{
  "response_format": "b64_json"
}
```

The image item contains `b64_json` instead of `url`:

```json
{
  "data": [
    {
      "b64_json": "...",
      "size": "2048x1024",
      "output_format": "png"
    }
  ]
}
```

`b64_json` contains raw Base64 data without a Data URL prefix.

### Response Fields

| Field | Type | Description |
| --- | --- | --- |
| `created` | integer | Unix timestamp for the response. |
| `data` | array | Generated image items. The array contains one item. |
| `data[].url` | string | Temporary image URL when `response_format` is `url`. |
| `data[].b64_json` | string | Raw Base64 image data when `response_format` is `b64_json`. |
| `data[].size` | string | Final output dimensions as `WIDTHxHEIGHT`. |
| `data[].output_format` | string | Final image format. |
| `usage.generated_images` | integer | Number of generated images. |
| `usage.input_images` | integer | Number of reference images. |
| `usage.output_tokens` | integer | Output usage reported by the API. |
| `usage.total_tokens` | integer | Total usage reported by the API. |

## Prompt Positioning And Markup

Express point placement, region edits, text replacement, arrows, sketches, and annotation boxes through the reference image and `prompt`. No additional request parameter is required.

```markdown
Replace the sign inside <bbox>100 200 800 900</bbox> with "New collection"
Add a small desk lamp near <point>520 380</point>
```

Coordinates use the `0..999` range. You can also draw arrows, boxes, or other marks directly on the input image and describe the intended edit in the prompt.

## Billing Notes

- Each request produces exactly one output image.
- The number of input images may affect billing. Use the current UniAll.ai model page as the source of truth.
- Output billing is split by actual pixel count: up to `2360000` pixels, or more than `2360000` pixels.
- The `1K` and `2K` labels do not determine billing directly. The final tier is based on `width * height` from the generated image.
- Current unit prices, group multipliers, and final charges are shown on the UniAll.ai model page and in usage records.

## Common Errors

| Problem | Likely cause | Resolution |
| --- | --- | --- |
| The request uses a reference image but does not run as an edit | The request was sent to `/v1/images/generations`. | Send every request containing `image` to `/v1/images/edits`. |
| Exact dimensions are rejected | `aspect_ratio` was also provided, or the pixel and ratio limits were exceeded. | Remove `aspect_ratio` and verify the exact-size constraints. |
| Reference image is rejected | More than 10 images were provided, the URL is not publicly reachable, or the Data URL is malformed. | Reduce the image count and verify direct access or the complete Data URL format. |
| Image format is rejected | The format is unsupported or the Data URL media subtype is not lowercase. | Use a supported format and a lowercase subtype such as `image/png`. |
| The expected response field is missing | The client is reading `url` while requesting `b64_json`, or the reverse. | Read the field selected by `response_format`. |
| The client times out before receiving an image | The HTTP client timeout is too short for synchronous generation. | Increase the client timeout and wait for the original request instead of polling a task endpoint. |

## Related Pages

- [Seedream Image Generation](/models/image/seedream)
- [Image Generation Overview](/models/image/overview)
- [Models](/models)

---

# Gemini Omni Flash Preview

Locale: en
URL: https://docs.uniall.ai/models/video/gemini-omni-flash-preview
Source: site-docs/models/video/gemini-omni-flash-preview.md
Description: Generate videos with gemini-omni-flash-preview through the UniAll.ai Gemini Interactions API.

Use `gemini-omni-flash-preview` through the UniAll.ai Gemini Interactions API to generate videos from text, one image, multiple images, one video, or a supported combination of images and video.

## Base URL

All examples on this page use:

```uri
https://api.uniall.ai
```

If the UniAll.ai console provides a dedicated API address for your account, use the address shown in the console.

## Quick Start

Generate a video:

```http
POST /v1beta/interactions
```

Authenticate with:

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

Minimal text-to-video request:

```bash
curl -X POST "https://api.uniall.ai/v1beta/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": "A cinematic robot walking through rain at night.",
    "response_format": {
      "type": "video",
      "aspect_ratio": "16:9"
    },
    "generation_config": {
      "video_config": {
        "task": "text_to_video",
        "resolution": "720p",
        "duration_seconds": 4
      }
    }
  }'
```

## Supported Capabilities

| Capability | `task` | Input |
| --- | --- | --- |
| Text to video | `text_to_video` | A prompt with no image or video |
| Image to video | `image_to_video` | A prompt and exactly one image |
| Reference generation | `reference_to_video` | A prompt plus images, one video, or a supported image-and-video combination |

The following inputs and operations are not currently supported:

- audio reference assets;
- first-frame and last-frame interpolation;
- continuation or editing based on an earlier `interaction_id`;
- video extension;
- Base64, `inline_data`, or multipart file uploads;
- custom resolution, width, or height.

## Request Parameters

### Top-Level Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | Must be `gemini-omni-flash-preview`. |
| `input` | string / object / array | Yes | Prompt and optional public image or video URLs. |
| `response_format` | object | Yes | Output type and aspect ratio. |
| `generation_config` | object | Recommended | Video generation settings. Pass it explicitly for predictable results. |
| `timeout_seconds` | integer | No | Maximum time the server waits for a result. Default: `300`. This is not the video duration. |

`POST /v1beta/interactions` waits for generation to finish before returning. Set the client-side HTTP timeout higher than `timeout_seconds`; use `600` seconds or more for reference-video requests.

### `response_format`

| Parameter | Type | Required | Supported values | Default |
| --- | --- | --- | --- | --- |
| `type` | string | Yes | `video` | None |
| `aspect_ratio` | string | No | `16:9`, `9:16` | `16:9` |

- `16:9` creates a landscape video.
- `9:16` creates a portrait video.

### `generation_config.video_config`

| Parameter | Type | Required | Supported values | Description |
| --- | --- | --- | --- | --- |
| `task` | string | Recommended | `text_to_video`, `image_to_video`, `reference_to_video` | Pass explicitly so the requested input mode is unambiguous. |
| `resolution` | string | No | `720p` | The only supported resolution. Default: `720p`. |
| `duration_seconds` | integer | No | `4`, `6`, `8`, `10` | Requested duration. Default: `4`. |

When a request includes a video reference, the model may choose the final duration based on that reference. `duration_seconds` does not guarantee the exact output duration in that case. Inspect the returned video file when exact duration matters.

### Task And Asset Combinations

| `task` | Images | Videos | Allowed input |
| --- | ---: | ---: | --- |
| `text_to_video` | 0 | 0 | Prompt only |
| `image_to_video` | 1 | 0 | Exactly one image |
| `reference_to_video` | 0-7 | 0-1 | Images, multiple images, one video, or images plus one video; at least one asset is required |

If `task` is omitted, the API infers it from the supplied assets:

- no image or video: `text_to_video`;
- exactly one image: `image_to_video`;
- multiple images or any video: `reference_to_video`.

For stable production behavior, always pass `task` explicitly.

## Input Formats

### Text

For text-to-video generation, `input` can be a string:

```json
{
  "input": "A paper boat sailing through a neon city during heavy rain."
}
```

### Content Array

The array format is the clearest option and is recommended for requests with reference assets:

```json
{
  "input": [
    {
      "type": "text",
      "text": "Animate the subject with a slow cinematic camera push-in."
    },
    {
      "type": "image",
      "url": "https://example.com/subject.webp"
    },
    {
      "type": "video",
      "url": "https://example.com/motion-reference.mp4"
    }
  ]
}
```

| `type` | Field | Description |
| --- | --- | --- |
| `text` | `text` | Text prompt |
| `image` | `url` | Publicly accessible image URL |
| `video` | `url` | Publicly accessible video URL |

### Object Shorthand

You can also provide an object with URL fields:

```json
{
  "input": {
    "text": "Use the references to create one cohesive cinematic shot.",
    "image_urls": [
      "https://example.com/character.png",
      "https://example.com/environment.jpg"
    ],
    "video_urls": [
      "https://example.com/camera-motion.mp4"
    ]
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `text` | string | Prompt |
| `image_url` | string | One image URL |
| `image_urls` | string[] | Multiple image URLs |
| `video_url` | string | One video URL |
| `video_urls` | string[] | Video URL array; currently limited to one video |

## Prompt And Asset Limits

### Prompt

- Every task should include a non-empty prompt.
- The maximum prompt length is `20000` characters.
- Multiple text items are combined in order.
- Describe the subject, action, camera movement, scene, lighting, pacing, and style.
- For reference generation, explain the intended role of each asset.

Example:

```markdown
Use the first image for the character appearance, the second image for the
environment, and the video for camera motion. Create one continuous cinematic
shot with natural movement and consistent lighting.
```

### Images

- Supported formats: JPEG, PNG, and WEBP.
- Maximum size: `20 MB` per image.
- Each URL must be directly reachable from the public internet without cookies, login state, or custom headers.
- Up to seven images are allowed when no video is supplied.
- `image_to_video` requires exactly one image.

### Video

- A request can include at most one reference video.
- Maximum file size: `100 MB`.
- Maximum input duration: `30` seconds.
- MP4 is recommended for broad compatibility.
- The model uses at most the first 10 seconds of the reference.
- The URL must be directly reachable from the public internet.

### Reference Asset Quota

Each image uses one asset unit and each video uses two. The total must not exceed seven:

```uri
image count + video count * 2 <= 7
```

| Images | Videos | Allowed |
| ---: | ---: | --- |
| 7 | 0 | Yes |
| 5 | 1 | Yes |
| 6 | 1 | No |
| 0 | 1 | Yes |
| 0 | 2 | No |

## Request Examples

The following examples pass the task and video settings explicitly.

### Landscape Text To Video

```bash
curl -X POST "https://api.uniall.ai/v1beta/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": "A wide cinematic shot of an astronaut walking through a field of glowing flowers at dusk, gentle wind, slow dolly-in camera movement.",
    "response_format": {
      "type": "video",
      "aspect_ratio": "16:9"
    },
    "generation_config": {
      "video_config": {
        "task": "text_to_video",
        "resolution": "720p",
        "duration_seconds": 6
      }
    },
    "timeout_seconds": 600
  }'
```

### Portrait Text To Video

```bash
curl -X POST "https://api.uniall.ai/v1beta/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": [
      {
        "type": "text",
        "text": "Vertical fashion film, a model walking through a minimalist white gallery, soft shadows, smooth handheld camera, premium editorial style."
      }
    ],
    "response_format": {
      "type": "video",
      "aspect_ratio": "9:16"
    },
    "generation_config": {
      "video_config": {
        "task": "text_to_video",
        "resolution": "720p",
        "duration_seconds": 10
      }
    },
    "timeout_seconds": 600
  }'
```

### Image To Video

```bash
curl -X POST "https://api.uniall.ai/v1beta/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": [
      {
        "type": "image",
        "url": "https://example.com/portrait.webp"
      },
      {
        "type": "text",
        "text": "Keep the character appearance consistent. Add subtle breathing and blinking, hair moving gently in the wind, and a slow camera push-in."
      }
    ],
    "response_format": {
      "type": "video",
      "aspect_ratio": "9:16"
    },
    "generation_config": {
      "video_config": {
        "task": "image_to_video",
        "resolution": "720p",
        "duration_seconds": 4
      }
    },
    "timeout_seconds": 600
  }'
```

### Multiple Image References

```bash
curl -X POST "https://api.uniall.ai/v1beta/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": {
      "text": "Use the first image for the character, the second for clothing, and the third for the environment. Create one continuous shot of the character entering the cafe and looking toward the camera.",
      "image_urls": [
        "https://example.com/character.png",
        "https://example.com/outfit.jpg",
        "https://example.com/cafe.webp"
      ]
    },
    "response_format": {
      "type": "video",
      "aspect_ratio": "16:9"
    },
    "generation_config": {
      "video_config": {
        "task": "reference_to_video",
        "resolution": "720p",
        "duration_seconds": 8
      }
    },
    "timeout_seconds": 600
  }'
```

### One Video Reference

```bash
curl -X POST "https://api.uniall.ai/v1beta/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": [
      {
        "type": "video",
        "url": "https://example.com/dance-motion.mp4"
      },
      {
        "type": "text",
        "text": "Create a cinematic dancer performance using the reference for body movement and rhythm. Use dramatic blue stage lighting and a slowly orbiting camera."
      }
    ],
    "response_format": {
      "type": "video",
      "aspect_ratio": "16:9"
    },
    "generation_config": {
      "video_config": {
        "task": "reference_to_video",
        "resolution": "720p",
        "duration_seconds": 8
      }
    },
    "timeout_seconds": 600
  }'
```

### Mixed Image And Video References

```bash
curl -X POST "https://api.uniall.ai/v1beta/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": {
      "text": "Use the character image for appearance, the city image for the environment, and the video for camera motion. Keep the character identity and clothing consistent throughout the shot.",
      "image_urls": [
        "https://example.com/character.png",
        "https://example.com/night-city.jpg"
      ],
      "video_urls": [
        "https://example.com/camera-reference.mp4"
      ]
    },
    "response_format": {
      "type": "video",
      "aspect_ratio": "16:9"
    },
    "generation_config": {
      "video_config": {
        "task": "reference_to_video",
        "resolution": "720p",
        "duration_seconds": 10
      }
    },
    "timeout_seconds": 600
  }'
```

### Python

```python
import requests

api_url = "https://api.uniall.ai/v1beta/interactions"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "model": "gemini-omni-flash-preview",
    "input": [
        {
            "type": "image",
            "url": "https://example.com/product.png",
        },
        {
            "type": "text",
            "text": (
                "Create a premium product film with a slow 360-degree camera "
                "move, soft studio reflections, and a dark background."
            ),
        },
    ],
    "response_format": {
        "type": "video",
        "aspect_ratio": "16:9",
    },
    "generation_config": {
        "video_config": {
            "task": "image_to_video",
            "resolution": "720p",
            "duration_seconds": 6,
        }
    },
    "timeout_seconds": 600,
}

response = requests.post(
    api_url,
    headers=headers,
    json=payload,
    timeout=660,
)
response.raise_for_status()

result = response.json()
print(result["interaction_id"])
print(result["response"]["video"]["uri"])
```

### JavaScript

```javascript
const response = await fetch("https://api.uniall.ai/v1beta/interactions", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gemini-omni-flash-preview",
    input: "A tiny red train crossing a snowy mountain bridge at sunrise.",
    response_format: {
      type: "video",
      aspect_ratio: "16:9",
    },
    generation_config: {
      video_config: {
        task: "text_to_video",
        resolution: "720p",
        duration_seconds: 4,
      },
    },
    timeout_seconds: 600,
  }),
});

const result = await response.json();
if (!response.ok) {
  throw new Error(result.error?.message ?? "Video generation failed");
}

console.log(result.interaction_id);
console.log(result.response.video.uri);
```

## Success Response

A successful request returns a Gemini Interactions-style response:

```json
{
  "interaction_id": "task_xxx",
  "model": "gemini-omni-flash-preview",
  "response": {
    "video": {
      "uri": "https://api.uniall.ai/media/generated-video.mp4"
    }
  }
}
```

| Field | Description |
| --- | --- |
| `interaction_id` | Unique generation ID that can be used to query the result |
| `model` | Public model name used for the request |
| `response.video.uri` | Generated video URL |

Download and store the generated result promptly. Do not assume that the video URL remains available indefinitely.

## Task Status And Result

`POST /v1beta/interactions` normally waits for the interaction result. When a follow-up query is needed, save `interaction_id` and call `GET /v1/videos/generations/{interaction_id}` instead of the default task route. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared terminal statuses, error contract, and result fields.

## Errors And Troubleshooting

Errors use a consistent structure:

```json
{
  "error": {
    "code": 400,
    "message": "`duration_seconds` must be one of 4, 6, 8, or 10",
    "status": "INVALID_ARGUMENT"
  }
}
```

| HTTP status | `error.status` | Meaning |
| ---: | --- | --- |
| `400` | `INVALID_ARGUMENT` | Invalid parameter, asset count, or task mode |
| `400` | `FAILED_PRECONDITION` | Request did not pass safety checks |
| `401` | `UNAUTHENTICATED` | Missing or invalid API key |
| `404` | `NOT_FOUND` | Model or query ID does not exist |
| `429` | `RESOURCE_EXHAUSTED` | Request rate is too high |
| `503` | `UNAVAILABLE` | Service is temporarily unavailable |
| `504` | `DEADLINE_EXCEEDED` | No result was returned within `timeout_seconds` |

## Billing Notes

Pricing and billing rules can change. Use the current model price and usage records shown in the UniAll.ai console as the source of truth. Keep the `interaction_id` when reconciling a request or contacting support.

## Recommendations

- Pass `task`, `resolution`, `duration_seconds`, and `aspect_ratio` explicitly.
- Use HTTPS asset URLs and verify that each URL downloads without authentication.
- Set the client HTTP timeout 30-60 seconds higher than `timeout_seconds`.
- Treat the output file as the source of truth for the duration of video-reference results.
- Explain the role of every asset in the prompt for reference-generation requests.
- Retry `429` and `503` responses with exponential backoff.
- Never expose an API key in logs, frontend code, or a public repository.

---

# Grok Imagine

Locale: en
URL: https://docs.uniall.ai/models/video/grok-imagine
Source: site-docs/models/video/grok-imagine.md
Description: Grok Imagine video source documentation.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

Updated: 2026-06-03

This document explains how to call Grok Imagine video model. user requires using this sitestable model and OpenAI compatibilityvideo task endpoint.

## 1. Model

| Model | scenario | Billing basis |
| --- | --- | --- |
| `grok-imagine` | text-to-video, image-to-video, reference-image-to-video, video editing, video extension | capability type, /Output video duration billing detail; image-to-video input image |

For new integrations, use `grok-imagine`, input form and `extra_body.operation` Capability. this site's model list Model do not call.

## 2. Endpoint Overview

### 2.1 recommended: OpenAI compatibilityvideo task endpoint

```http
POST /v1/videos
GET /v1/videos/{task_id}
GET /v1/videos/{task_id}/content
```

`POST /v1/videos` submit task, return video task ID. poll `GET /v1/videos/{task_id}` Status. task completed, read response URL,`/v1/videos/{task_id}/content` Get Video File.

### 2.2 compatibility: video task endpoint

```http
POST /v1/videos/generations
GET /v1/videos/generations/{task_id}

POST /v1/video/generations
GET /v1/video/generations/{task_id}
```

 Endpoint, new recommended `/v1/videos`.

### 2.3 Details
```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## 3. fast

| | recommendedModel | | Capability |
| --- | --- | --- | --- |
| promptgenerate video | `grok-imagine`|`prompt`+`duration` | |
| oneimage | `grok-imagine`|`prompt`+`image`+`duration` | |
| multiple reference imagesgenerate video | `grok-imagine`|`prompt`+`images`+`duration` | |
| editing video | `grok-imagine`|`prompt`+`video`+`extra_body.operation=edit_video`, recommended `extra_body.input_video_seconds`|`edit_video` |
| video | `grok-imagine`|`prompt`+`video`+`duration`+`extra_body.operation=video_extend`, recommended `extra_body.input_video_seconds`|`video_extend` |

Note: `extra_body.operation` Yesthis sitestableCapability. input form the platform; video editingand pass `video`, recommended pass `extra_body.operation`.

## 4. Parameter Reference

| Parameters | Type | Required | Note |
| --- | --- | --- | --- |
| `model`| string | Yes | always pass `grok-imagine` |
| `prompt` | string | Yes | video generation, editingor prompt |
| `image`| string/object | image-to-videoRequired | single image URL; supports `{"url": "..."}` |
| `images` | string[] | multiple reference imagesRequired | multiple reference images URL |
| `image_url`/`image_urls` | string/string[] | No | image compatibility field |
| `video`| string/object | editing/ Required | video URL; supports `{"url": "..."}` |
| `videos` | string[] | No | reference video URL array, reference video Capability |
| `size`| string | No |,`480p`, `720p`; video extension does not support Parameters |
| `aspect_ratio`| string | No | output aspect ratio; text-to-video `16:9`, `1:1`, `9:16`, single-image-to-video `auto` |
| `duration` | integer/string | Conditional | duration., multiple reference images and use; video editing do not pass Field |
| `seconds`| string | Conditional | OpenAI compatibilitydurationField; pass `duration` pass `seconds`, do notand `duration` pass both |
| `extra_body.operation`| string | No | stableCapability:`text_to_video`, `image_to_video`, `reference_to_video`, `edit_video`, `video_extend` |
| `extra_body.input_video_seconds` | integer | editing/ recommended to pass | video billing detail duration, passpositive integer. video duration recommended to pass; pass the platform oruse value |

## 5. duration rules, multiple reference images and pass duration. video editing do not pass duration.

| scenario | durationField | supports value | video duration |
| --- | --- | --- | --- |
| text-to-video | `duration` or `seconds`|`1-15` integer seconds | requires |
| single-image-to-video | `duration` or `seconds`|`1-15` integer seconds | requires |
| reference-image-to-video | `duration` or `seconds`|`1-10` integer seconds | requires |
| video editing | pass `duration`/`seconds`| | recommended to pass `extra_body.input_video_seconds` |
| video extension | `duration` or `seconds`|`2-10` integer seconds | recommended to pass `extra_body.input_video_seconds` |

Note:

- recommended to use `duration`, `"duration": 6`.
- If can onlyuse OpenAI compatibility field, pass `seconds`, `"seconds": "6"`.
- `duration` and `seconds` one of two required, do not pass both.
- video editingand `extra_body.input_video_seconds` Yes video duration, Yes duration.
- If video duration, pass `extra_body.input_video_seconds`; the platform video, billing detail duration.
- billing detail userpass, Yes task / duration.

## 6. Capability Rules

 requires pass `extra_body.operation`:

- imageandvideo: text-to-video.
- one `image`: image-to-video.
- `images`: reference-image-to-video.
- `video`: recommended pass `edit_video` or `video_extend`.

 editing video:

```json
{
  "extra_body": {
    "operation": "edit_video",
    "input_video_seconds": 8
  }
}
```

 video:

```json
{
  "duration": 6,
  "extra_body": {
    "operation": "video_extend",
    "input_video_seconds": 8
  }
}
```

## 7. Request Examples

### 7.1 text-to-video

```bash
curl -X POST "{BASE_URL}/v1/videos" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "grok-imagine",
 "prompt": " camera, fast, camera. ",
 "size": "720p",
 "aspect_ratio": "16:9",
 "duration": 6}'
```

 submitresponses:

```json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video",
  "model": "grok-imagine",
  "status": "queued",
  "progress": 0,
  "created_at": 1773980459,
  "seconds": "6"
}
```

### 7.2 single-image-to-video

```bash
curl -X POST "{BASE_URL}/v1/videos" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "grok-imagine",
 "prompt": " camera, camera. ",
 "image": "https://example.com/portrait.png",
 "size": "480p",
 "aspect_ratio": "auto",
 "duration": 10}'
```

### 7.3 reference-image-to-video

```bash
curl -X POST "{BASE_URL}/v1/videos" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "grok-imagine",
 "prompt": " @Image1 @Image2, slow camera push-in. ",
 "images": ["https://example.com/person.png",
 "https://example.com/street.png"],
 "size": "720p",
 "aspect_ratio": "4:3",
 "duration": 10}'
```

### 7.4 video editing

```bash
curl -X POST "{BASE_URL}/v1/videos" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "grok-imagine",
 "prompt": "to change videointo, reserved action and. ",
 "video": "https://example.com/source.mp4",
 "size": "720p",
 "extra_body": {"operation": "edit_video",
 "input_video_seconds": 8}}'
```

video editing do not pass `duration`/`seconds`. If video duration, recommended to pass `extra_body.input_video_seconds`, and; pass the platform oruse value.

### 7.5 video extension

```bash
curl -X POST "{BASE_URL}/v1/videos" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "grok-imagine",
 "prompt": " camera, video and Orientation. ",
 "video": "https://example.com/source.mp4",
 "duration": 6,
 "extra_body": {"operation": "video_extend",
 "input_video_seconds": 8}}'
```

video extension `duration` duration, supports `2-10`. If video duration, recommended to pass both `extra_body.input_video_seconds`.

## 8. Task Status And Result

After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow.

## 9. Billing Notes

Grok video this siteuse billing detail, publicpricing Model.

| scenario | billing detail |
| --- | --- |
| text-to-video | Resolution tier, Output video duration |
| single-image-to-video | Resolution tier, Output video duration |
| reference-image-to-video | Resolution tier, Output video duration |
| video editing | Resolution tier, video duration, Output video duration |
| video extension | video duration, Output video duration |

public " Parameters "and,:

- video:
- video 480P:
- video 720P:

image-to-videoand reference-image-to-video Input image facts, Grok videoRules to change.

submit. tasksubmit balance, Yesto change value public.

## 10. Common Errors

### to changevideo model imageEndpoint

`grok-imagine` call `/v1/videos`, do not `/v1/images/generations`.

### editingand only pass `video`. editingpass:

---

# Grok Imagine Image

Locale: en
URL: https://docs.uniall.ai/models/video/grok/grok-imagine-image
Source: site-docs/models/video/grok/grok-imagine-image.md
Description: Grok Imagine image source documentation.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

Updated: 2026-05-29

This document explains how to call Grok Imagine image model. user requires using this sitestable model and OpenAI compatible image endpoint.

## 1. Model

| Model | scenario | Billing basis |
| --- | --- | --- |
| `grok-imagine-image` | standard, image editing | image, Input image billing detail |
| `grok-imagine-image-quality` | quality, image editing | quality, image billing detail |

recommended generate and editing use `grok-imagine-image`. requires quality or resolution use `grok-imagine-image-quality`.

## 2. Endpoint Overview

### 2.1 recommended: async image task

```http
POST /v1/images/tasks
GET /v1/images/tasks/{task_id}
```

async task Grok generation. supports, pass through this site supports Parameters, `resolution`, `aspect_ratio`, `output_format`, `num_images`.

### 2.2 compatibility: OpenAI imageEndpoint

```http
POST /v1/images/generations
POST /v1/images/edits
```

 Endpoint OpenAI image format. `/v1/images/edits` supports JSON image URL, supports `multipart/form-data` pass image file.

### 2.3 Details
 Endpoint use Bearer Token:

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## 3. fast

### 3.1 async

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "grok-imagine-image",
 "task_type": "text2image",
 "prompt": ", and ",
 "aspect_ratio": "1:1",
 "resolution": "1k",
 "output_format": "jpeg",
 "num_images": 1,
 "response_format": "url"}'
```

submitSuccess returntask ID:

```json
{
  "task_id": "task_xxx",
  "status": "queued",
  "progress": "0%",
  "result_url": "",
  "metadata": {
    "task_type": "text2image"
  },
  "error": null
}
```

Query Task:

```bash
curl "{BASE_URL}/v1/images/tasks/task_xxx" \
 -H "Authorization: Bearer sk-***"
```

completed responses:

```json
{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxx",
    "status": "succeeded",
    "progress": "100%",
    "result_url": "https://example.com/result-1.jpeg",
    "metadata": {
      "task_type": "text2image",
      "result_count": 1,
      "result_urls": [
        "https://example.com/result-1.jpeg"
      ]
    },
    "error": null
  }
}
```

### 3.2 async image editing

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "grok-imagine-image-quality",
 "task_type": "image2image",
 "prompt": " subject structure, to change into style, ",
 "image": "https://example.com/source-watch.png",
 "aspect_ratio": "auto",
 "resolution": "2k",
 "output_format": "webp",
 "num_images": 2,
 "response_format": "url"}'
```

### 3.3 multiple reference imagesediting

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "grok-imagine-image-quality",
 "task_type": "image2image",
 "prompt": "to change one, Ratioand, style",
 "images": ["https://example.com/product.png",
 "https://example.com/stage.png"],
 "aspect_ratio": "16:9",
 "resolution": "2k",
 "output_format": "png",
 "num_images": 1,
 "response_format": "url"}'
```

### 3.4 synchronous compatibilitycall

```bash
curl -X POST "{BASE_URL}/v1/images/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "grok-imagine-image",
 "prompt": "one, ",
 "n": 1,
 "response_format": "url"}'
```

 responses:

```json
{
  "created": 1773980459,
  "data": [
    {
      "url": "https://example.com/image.png",
      "revised_prompt": ""
    }
  ]
}
```

### 3.5 synchronousimage editingcompatibilitycall

JSON image URL:

```bash
curl -X POST "{BASE_URL}/v1/images/edits" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "grok-imagine-image",
 "prompt": "reserved, to change, ",
 "image": "https://example.com/person.png",
 "n": 1,
 "response_format": "url"}'
```

multipart file pass:

```bash
curl -X POST "{BASE_URL}/v1/images/edits" \
 -H "Authorization: Bearer sk-***" \
 -F "model=grok-imagine-image" \
 -F "prompt=reserved subject, into " \
 -F "n=1" \
 -F "response_format=url" \
 -F "image=@/path/to/source.png"
```

## 4. Parameter Reference

| Parameters | Type | Required | Note |
| --- | --- | --- | --- |
| `model`| string | Yes |`grok-imagine-image` or `grok-imagine-image-quality` |
| `prompt` | string | Yes | generation or editing prompt |
| `task_type`| string | No | async taskuse,`text2image` or `image2image`; pass the platform Whether image |
| `image` | string | Required | Input image URL; synchronouseditingandasyncediting supports |
| `images` | string[] | editingRequired | multiple reference images URL; recommendedFor new integrations, use Field |
| `image_url` | string | No | URL compatibility field |
| `image_urls` | string[] | No | URL compatibility field |
| `aspect_ratio`| string | No | output aspect ratio;`1:1`, `16:9`, `9:16`, `4:3`, `3:4`, image editing `auto` |
| `resolution`| string | No | Resolution tier,`1k`, `2k`; recommended `/v1/images/tasks` use |
| `output_format`| string | No |`jpeg`, `png`, `webp` |
| `num_images`| integer | No | Generate Images,`1-4`; async taskrecommended to use |
| `n`| integer | No | OpenAI compatibility Field, default `1` |
| `response_format`| string | No | recommended `url` |

 recommended:

- use for single-image input `image`.
- use for multi-image input `images`.
- do not `image`, `image_url`, `images`, `image_urls`.

## 5. Billing Notes

Grok image this siteuse billing detail, publicpricing Model.

| scenario | billing detail |
| --- | --- |
| | image, Resolution tier, quality |
| image editing | Input image, image, Resolution tier, quality |

publicpricing Model, " image / ""Input image / "" image / ". submit, Yestask andbalance, public.

## 6. Common Errors

### to changevideo model imageEndpoint

`grok-imagine` Yesvideo model, call `/v1/videos` orcompatibilityvideo task endpoint.

### image editing do not pass image

`/v1/images/edits` and `task_type=image2image` pass `image` or `images`.

### pass `aspect_ratio=auto`

`auto` image editing. recommended pass `1:1`, `16:9`, `9:16` Ratio.

### synchronousEndpointandasyncEndpoint Field

If required `resolution`, `num_images` Grok Parameters, prefer using `/v1/images/tasks`. synchronouscompatibilityEndpoint OpenAI image.

---

# Grok Video 1.5

Locale: en
URL: https://docs.uniall.ai/models/video/grok/grok-video-1-5
Source: site-docs/models/video/grok/grok-video-1-5.md
Description: Create text-to-video, single-image, and multi-reference video tasks with Grok Video 1.5 through the UniAll async video API.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

Updated: 2026-08-03

Use the public model `grok-video-1.5` for text-to-video, single-image animation, and multi-image reference generation. Submit a task through the UniAll async video API, then poll the task until it completes or fails.

## 1. Capability Scope

| Mode | Image Input | Prompt | Maximum Resolution |
| --- | --- | --- | --- |
| Text-to-video | No image field | Required | `1080p` |
| Single-image-to-video | One `image` or `image_url` | Optional | `1080p` |
| Reference-to-video | 1 to 7 `reference_images` or `reference_image_urls` | Required | `720p` |

The model also supports:

- durations from `1` to `15` seconds, defaulting to `8` seconds;
- `480p`, `720p`, and `1080p` output, defaulting to `480p`;
- `auto`, `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, and `2:3` aspect ratios;
- HTTP(S) image URLs and complete image Data URLs.

This public model does not support reference audio, source-video editing, or video extension. Use the existing Grok Imagine video models for edit and extend workflows.

## 2. When To Use It

Use `grok-video-1.5` when you need to:

- create a video directly from a text prompt;
- animate one source image, with or without an additional prompt;
- keep a character, product, or visual style consistent across 1 to 7 reference images;
- request up to `1080p` for text-to-video or single-image generation.

Do not use this model for first-and-last-frame generation, reference audio, video editing, or video extension.

## 3. Endpoint And Authentication

Use the primary endpoints for new integrations:

| Purpose | Method | Path |
| --- | --- | --- |
| Create a video task | `POST` | `/v1/videos` |
| Query a video task | `GET` | `/v1/videos/{task_id}` |

The compatible `/v1/videos/generations` create and query paths remain available.

Every request requires a Bearer token:

```http
Authorization: Bearer sk-***
```

Task creation also requires:

```http
Content-Type: application/json
```

## 4. Request Body Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | Must be `grok-video-1.5`. |
| `prompt` | string | Conditional | Required for text and reference generation; optional for single-image generation. |
| `duration` | integer or integer string | No | `1` to `15`. Defaults to `8`. |
| `seconds` | integer or integer string | No | Compatible alias for `duration`. If both are present, their values must match. |
| `resolution` | string | No | `480p`, `720p`, or `1080p`. Defaults to `480p`. Reference generation supports up to `720p`. |
| `size` | string | No | Compatible alias for `resolution`. If both are present, their values must match. |
| `aspect_ratio` | string | No | `auto`, `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, or `2:3`. |
| `image` | object | No | One structured image in the form `{"url":"..."}`. |
| `image_url` | string | No | Compatible single-image field. |
| `reference_images` | object[] | No | 1 to 7 structured images in the form `[{"url":"..."}]`. |
| `reference_image_urls` | string[] | No | Compatible array containing 1 to 7 image URLs or Data URLs. |

Prefer `duration` over `seconds`, `resolution` over `size`, and the structured `image` or `reference_images` fields in new integrations.

### Image Field Selection

The four image fields are mutually exclusive. Choose exactly one field for an image-based request:

| Input Shape | Use |
| --- | --- |
| One structured image | `image: {"url":"..."}` |
| One compatible string field | `image_url: "..."` |
| Multiple structured references | `reference_images: [{"url":"..."}]` |
| Multiple compatible string references | `reference_image_urls: ["..."]` |

Do not combine single-image fields with reference-image fields in the same request.

### Supported Image Values

Every image value must be either:

- a server-accessible `http://` or `https://` URL; or
- a complete image Data URL such as `data:image/png;base64,...`.

Bare Base64 strings, local file paths, browser-session URLs, `images`, `image_urls`, and every form of `file_id` are rejected.

## 5. Request Examples

### 5.1 Text-To-Video

This request uses `1080p` and the default 8-second duration:

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-video-1.5",
    "prompt": "A quiet mountain lake at sunrise, gentle camera movement, realistic reflections.",
    "resolution": "1080p",
    "aspect_ratio": "16:9"
  }'
```

### 5.2 Single Image From An HTTP URL

The prompt is optional for single-image generation:

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-video-1.5",
    "image": {
      "url": "https://example.com/product.jpg"
    },
    "duration": 6,
    "resolution": "720p"
  }'
```

### 5.3 Single Image From A Data URL

Pass the complete Data URL, including its media type and Base64 prefix:

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-video-1.5",
    "prompt": "Subtle camera push-in and natural fabric movement.",
    "image_url": "data:image/png;base64,iVBORw0KGgo...",
    "duration": 5,
    "size": "480p",
    "aspect_ratio": "9:16"
  }'
```

### 5.4 Multiple Reference Images

Reference generation accepts 1 to 7 images and is limited to `480p` or `720p`:

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-video-1.5",
    "prompt": "Keep the character identity and clothing consistent while the character turns toward the camera.",
    "reference_images": [
      {"url": "https://example.com/character-front.jpg"},
      {"url": "https://example.com/character-side.jpg"}
    ],
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "9:16"
  }'
```

## 6. Response Examples

### Task Created

Save `id` or the compatible `task_id` value for polling.

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "grok-video-1.5",
  "status": "queued",
  "raw_status": "PENDING",
  "progress": 0,
  "created_at": 1785715200,
  "video_url": null
}
```

## 7. Task Status And Result

After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow.

## 8. Aspect Ratio Behavior

- If text-to-video omits `aspect_ratio`, the effective default is normally `16:9`.
- If single-image generation omits it, output normally follows the source image ratio.
- `auto` is accepted as a compatibility value.
- For predictable framing, prepare source and reference images in the desired output orientation.

## 9. Billing Notes

This page does not define an exact user price. The normalized duration, resolution, and number of input images affect billing:

- omitted duration is billed using the 8-second default;
- text-to-video has no input-image charge dimension;
- single-image generation counts one input image;
- reference generation counts every supplied reference image;
- higher resolution generally costs more.

Check current pricing in the UniAll console and review account usage after task creation. Wait for the original task's terminal state before retrying it.

## 10. Common Errors

### Missing `prompt`

`prompt` is required for text-to-video and reference-to-video. It may be omitted only for a single-image request.

### Conflicting Image Fields

Do not combine `image`, `image_url`, `reference_images`, or `reference_image_urls`. Choose one field only.

### Invalid Image Encoding

Use an HTTP(S) URL or a complete Data URL. A bare Base64 string such as `iVBORw0KGgo...` is invalid.

### Reference Generation At `1080p`

Reference generation supports at most `720p`. Use `480p` or `720p`, or switch to text or single-image generation for `1080p`.

### Too Many Reference Images

`reference_images` and `reference_image_urls` accept 1 to 7 images. An empty array or more than 7 images is invalid.

### Unsupported Fields

Do not pass `file_id`, `reference_audios`, `reference_audio_urls`, `voice_id`, `output`, `storage_options`, or `user`. Do not place them inside `extra_body`.

### Unsupported Video Operations

Reference audio, first-and-last-frame generation, video editing, and video extension are not part of `grok-video-1.5`.

## 11. Migration From The Previous Contract

| Item | Previous Contract | Current Contract |
| --- | --- | --- |
| Generation modes | Single-image only | Text, single-image, and 1-to-7-image reference generation |
| Image fields | `image_url` only | Structured `image` / `reference_images` plus compatible URL fields |
| Image values | HTTP(S) URL only | HTTP(S) URL or complete image Data URL |
| Single-image prompt | Required | Optional |
| Duration | Required integer `duration` | `duration` or `seconds`, `1..15`, default `8` |
| Resolution | `480p` or `720p` | Also `1080p` for text and single-image generation |
| Aspect ratio | Six values plus `auto` | Adds `4:3` and `3:4` |

Do not migrate to provider-native model names or file IDs. Keep using the stable public model `grok-video-1.5` and the UniAll task endpoints.

## 12. Related Pages

- [Query Balance](/balance)
- [Grok Imagine Video Generation](/models/video/grok-imagine)
- [Grok Imagine Image Generation](/models/video/grok/grok-imagine-image)

---

# Hailuo

Locale: en
URL: https://docs.uniall.ai/models/video/hailuo
Source: site-docs/models/video/hailuo.md
Description: Create text, single-image, and first-and-last-frame videos with the Hailuo series through the UniAll video task API.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

Updated: 2026-08-04

## Overview

UniAll provides three stable public Hailuo models through the OpenAI-compatible asynchronous video task API.

| Model | Text To Video | Single Image | First And Last Frame |
| --- | --- | --- | --- |
| `hailuo-02` | Supported | Supported | Supported |
| `hailuo-2.3` | Supported | Supported | Not supported |
| `hailuo-2.3-fast` | Not supported | Supported | Not supported |

All three models use the same create, query, and content-download endpoints. The request shape determines the generation mode.

## When To Use It

Use the Hailuo series when you need to:

- create a 6-second or 10-second video from a prompt;
- animate one publicly accessible source image;
- generate a first-and-last-frame transition with `hailuo-02`;
- choose between `768p` and `1080p` output.

The public Hailuo contract does not support audio, multiple reference images, reference videos, aspect-ratio controls, or video editing.

## Limits

- `duration` must be `6` or `10` seconds.
- `resolution` must be `768p` or `1080p`.
- `1080p` only supports a 6-second duration.
- Input images must be publicly accessible HTTP(S) URLs.
- Prompts can contain up to 2,000 characters.

## Endpoints

| Purpose | Method | Path |
| --- | --- | --- |
| Create a video task | `POST` | `/v1/videos` |
| Query a video task | `GET` | `/v1/videos/{task_id}` |
| Download the video | `GET` | `/v1/videos/{task_id}/content` |

## Authentication

Every request requires a UniAll Bearer token:

```http
Authorization: Bearer sk-***
```

Task creation also requires:

```http
Content-Type: application/json
```

## Request Body Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | `hailuo-02`, `hailuo-2.3`, or `hailuo-2.3-fast`. |
| `prompt` | string | Yes | Video description with a maximum length of 2,000 characters. |
| `image` | string | Conditional | Public HTTP(S) URL for single-image generation or the first frame. |
| `last_image` | string | Conditional | Public HTTP(S) URL for the last frame; only supported by `hailuo-02` and requires `image`. |
| `duration` | integer | Yes | `6` or `10`. |
| `resolution` | string | Yes | `768p` or `1080p`; `1080p` only supports 6 seconds. |
| `prompt_optimizer` | boolean | No | Whether to optimize the prompt before generation. |
| `fast_pretreatment` | boolean | No | Whether to use fast preprocessing; do not set it to `true` for first-and-last-frame generation. |
| `watermark` | boolean | No | Whether to add an AIGC watermark. |

Choose input fields according to the generation mode:

| Mode | Model | Input Fields |
| --- | --- | --- |
| Text to video | `hailuo-02` or `hailuo-2.3` | `prompt` |
| Single image | Any Hailuo model | `prompt` + `image` |
| First and last frame | `hailuo-02` | `prompt` + `image` + `last_image` |

Follow these validation rules:

- Do not pass `image` or `last_image` for text-to-video requests.
- `hailuo-2.3-fast` only supports single-image generation and therefore requires `image`.
- Do not pass `last_image` without `image`.
- Use `last_image` only with `hailuo-02`.
- Pass all supported parameters at the top level of the request body.
- Do not send audio, reference-image arrays, reference videos, aspect ratios, or video-editing fields.

## Request Examples

### Text To Video

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo-2.3",
    "prompt": "A cinematic train passes through a snowy mountain canyon while morning mist drifts slowly and the camera moves forward.",
    "duration": 6,
    "resolution": "1080p",
    "prompt_optimizer": true,
    "watermark": false
  }'
```

### Single Image To Video

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo-2.3-fast",
    "prompt": "The person naturally raises their head and looks at the camera while face and clothing remain consistent.",
    "image": "https://example.com/source.png",
    "duration": 6,
    "resolution": "768p",
    "fast_pretreatment": true,
    "watermark": false
  }'
```

### First And Last Frame

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo-02",
    "prompt": "Transition naturally from day to night while the building structure remains stable and the motion stays smooth.",
    "image": "https://example.com/first.png",
    "last_image": "https://example.com/last.png",
    "duration": 6,
    "resolution": "1080p",
    "prompt_optimizer": true,
    "watermark": false
  }'
```

## Response Examples

### Task Created

Save the returned `id` for later queries:

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "object": "video",
  "model": "hailuo-2.3",
  "status": "queued",
  "progress": 0,
  "created_at": 1785772800
}
```

## Task Status And Result

After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow.

## Billing Notes

The selected model, `duration`, and `resolution` affect billing. A 10-second request is not available at `1080p`. Check the UniAll model page and consumption log for current pricing and final settlement.

## Common Errors

Requests are rejected when they:

- use a model that does not support the requested generation mode;
- pass a `duration` other than `6` or `10`;
- request a 10-second video at `1080p`;
- omit `image` for `hailuo-2.3-fast`;
- pass `last_image` without `image`, or use `last_image` with a model other than `hailuo-02`;
- use an image URL that the service cannot access publicly;
- request audio, reference videos, multiple reference images, aspect-ratio control, or video editing.

Set `watermark` to `false` to request output without an AIGC watermark. Final watermark behavior can also depend on platform availability and model policy. Contact UniAll support when a completed result still contains a watermark unexpectedly.

## Related Pages

- [Video Generation Overview](/models/video/overview)
- [Models](/models)

---

# Happy Horse

Locale: en
URL: https://docs.uniall.ai/models/video/happy-horse
Source: site-docs/models/video/happy-horse.md
Description: Create text, image, multi-reference, and video-editing tasks with the unified Happy Horse model through UniAll.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

Updated: 2026-08-10

## Overview

UniAll exposes one stable Happy Horse public model: `happy-horse`. The current public contract provides Happy Horse 1.0 capabilities. Select the generation mode and output tier with request parameters instead of using separate model names.

| Operation | `operation` | Required media | Resolution |
| --- | --- | --- | --- |
| Text-to-video | `text_to_video` | None | `720p`, `1080p` |
| Image-to-video | `image_to_video` | Exactly one image | `720p`, `1080p` |
| Multi-reference video | `reference_to_video` | 1 to 9 images | `720p`, `1080p` |
| Video editing | `edit_video` | Exactly one video; up to 5 optional images | `720p`, `1080p` |

Previous tier-specific model IDs are not supported. Always send `model: "happy-horse"` together with `operation` and `resolution`.

The public HappyHorse 1.0 contract does not offer `480p`. A request using that
resolution is rejected before a task is created.

## When To Use It

Use `happy-horse` to:

- generate a video from a text prompt;
- animate one source image while preserving its composition;
- keep characters, products, or styles consistent across multiple reference images;
- edit a source video while preserving or automatically handling its original audio.

## Endpoint

Use the primary endpoints for new integrations:

| Purpose | Method | Path |
| --- | --- | --- |
| Create a video task | `POST` | `/v1/videos` |
| Query a video task | `GET` | `/v1/videos/{task_id}` |
| Retrieve the completed video | `GET` | `/v1/videos/{task_id}/content` |

The compatible `/v1/videos/generations` and `/v1/video/generations` create and query paths remain available. New clients should use `/v1/videos`.

## Authentication

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## Quick Request Example

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse",
    "operation": "text_to_video",
    "resolution": "1080p",
    "prompt": "A white horse runs across a misty grassland at sunrise, cinematic camera movement.",
    "duration": 7,
    "aspect_ratio": "16:9",
    "seed": 12345,
    "watermark": false
  }'
```

The create response contains `id` and the compatible `task_id` field. Store either value and poll the task endpoint.

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "happy-horse",
  "status": "queued",
  "progress": 0,
  "created_at": 1785801600,
  "video_url": null
}
```

## Task Status And Result

After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow.

## Billing Notes

- Generation tasks are billed by operation, selected resolution tier, and generated duration.
- Video editing is finally settled using the actual input and output video durations, so the final charge may differ from the initial estimate.
- `resolution` selects a public service tier, not a guaranteed exact pixel width and height. Inspect the returned media metadata when exact dimensions matter.
- Use the current UniAll pricing page and task settlement record as the final price source.

## Common Errors

- Using a removed tier-specific model ID instead of `happy-horse`.
- Omitting the required `operation` or `resolution` parameter.
- Sending `resolution: "480p"`; use `720p` or `1080p`.
- Sending `size`; Happy Horse uses `resolution` and rejects `size`.
- Sending `duration` or `aspect_ratio` for `edit_video`.
- Sending `aspect_ratio` for `image_to_video`; this mode follows the source image.
- Using private, expired, or otherwise unreachable media URLs.

## Related Pages

- [Create a Happy Horse Task](/models/video/happy-horse/create-task)
- [Video Generation Overview](/models/video/overview)

---

# Create a Happy Horse Video Task

Locale: en
URL: https://docs.uniall.ai/models/video/happy-horse/create-task
Source: site-docs/models/video/happy-horse/create-task.md
Description: Create text, image, multi-reference, and video-editing tasks with the unified happy-horse model.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

Updated: 2026-08-10

## Overview

Use the single public model `happy-horse`. Select text generation, image animation, multi-reference generation, or video editing through `operation`, and select the output tier through `resolution`.

Do not use the removed tier-specific model IDs. They are intentionally incompatible with the current public contract.

## Endpoint

```http
POST /v1/videos
```

Compatible create paths:

```http
POST /v1/videos/generations
POST /v1/video/generations
```

New integrations should use `/v1/videos`.

## Authentication

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## Operation Matrix

| `operation` | Prompt | Image input | Video input | Resolution | `duration` | `aspect_ratio` |
| --- | --- | --- | --- | --- | --- | --- |
| `text_to_video` | Required | None | None | `720p`, `1080p` | Optional, default `5` | Optional, default `16:9` |
| `image_to_video` | Optional | Exactly 1 | None | `720p`, `1080p` | Optional, default `5` | Not supported |
| `reference_to_video` | Required | 1 to 9 | None | `720p`, `1080p` | Optional, default `5` | Optional, default `16:9` |
| `edit_video` | Required | 0 to 5 | Exactly 1 | `720p`, `1080p` | Not supported | Not supported |

## Request Body Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | Must be `happy-horse`. |
| `operation` | string | Yes | `text_to_video`, `image_to_video`, `reference_to_video`, or `edit_video`. |
| `resolution` | string | Yes | `720p` or `1080p` for every operation. |
| `prompt` | string | Conditional | Required except for `image_to_video`; maximum `2500` characters. |
| `duration` | integer | No | Generation only. `3` to `15`, default `5`. Do not send it for editing. |
| `aspect_ratio` | string | No | Text and multi-reference generation only. Do not send it for image animation or editing. |
| `image` | string | Conditional | Recommended field for the one HTTP(S) image used by `image_to_video`. |
| `images` | string[] | Conditional | 1 to 9 HTTP(S) images for `reference_to_video`. |
| `reference_image_urls` | string[] | No | Alias for multi-reference images; also supports up to 5 edit reference images. |
| `video` | string | Conditional | One HTTP(S) source video for `edit_video`. |
| `seed` | integer | No | Random seed from `0` to `2147483647`. |
| `watermark` | boolean | No | Whether to add a watermark. Default `false`. |
| `audio_setting` | string | No | Editing only: `auto` or `origin`. Default `auto`. |

Supported `aspect_ratio` values for text and multi-reference generation:

- `16:9`
- `9:16`
- `1:1`
- `4:3`
- `3:4`
- `4:5`
- `5:4`
- `9:21`
- `21:9`

`size` and `enable_safety_checker` are not Happy Horse public parameters and are rejected.

`480p` is not available for the public HappyHorse 1.0 contract. Requests that set
`resolution` to `480p` are rejected before a task is created.

## Input Rules

| Mode | Valid media fields |
| --- | --- |
| Text-to-video | No image or video field |
| Image-to-video | `image`, or one item through a supported image alias |
| Multi-reference video | `images` or `reference_image_urls`, with 1 to 9 URLs |
| Video editing | `video`, plus up to 5 optional `reference_image_urls` |

All media inputs must be complete public HTTP or HTTPS URLs. File uploads, bare Base64 values, and Data URLs are not accepted by this model contract.

## Request Examples

### Text-to-video

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse",
    "operation": "text_to_video",
    "resolution": "1080p",
    "prompt": "A white horse runs across a misty grassland at sunrise, realistic movement and soft rim light.",
    "duration": 7,
    "aspect_ratio": "21:9",
    "seed": 12345,
    "watermark": false
  }'
```

### Image-to-video

The output composition follows the source image, so do not send `aspect_ratio`.

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse",
    "operation": "image_to_video",
    "resolution": "720p",
    "image": "https://example.com/source-frame.png",
    "prompt": "The subject walks forward naturally while the camera slowly pushes in.",
    "duration": 5,
    "seed": 67890,
    "watermark": false
  }'
```

The prompt may be omitted for `image_to_video`.

### Multi-reference video

Use `character1` through `character9` in the prompt to refer to images in array order.

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse",
    "operation": "reference_to_video",
    "resolution": "720p",
    "prompt": "character1 drives character2 across the lunar surface while both identities remain consistent.",
    "reference_image_urls": [
      "https://example.com/character.png",
      "https://example.com/vehicle.png"
    ],
    "duration": 8,
    "aspect_ratio": "16:9",
    "seed": 24680,
    "watermark": false
  }'
```

### Video editing

Editing follows the source video duration and does not accept `duration` or `aspect_ratio`.

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse",
    "operation": "edit_video",
    "resolution": "1080p",
    "prompt": "Replace the jacket with the referenced red jacket while preserving identity, motion, camera movement, and background.",
    "video": "https://example.com/source-video.mp4",
    "reference_image_urls": [
      "https://example.com/red-jacket.png"
    ],
    "audio_setting": "origin",
    "seed": 13579,
    "watermark": false
  }'
```

Use `audio_setting: "origin"` to preserve the original audio. Use `auto` to let the service choose the audio handling behavior.

## `extra_body` Compatibility

Top-level parameters are recommended. `operation`, `resolution`, `seed`, `watermark`, and `audio_setting` may also be placed in `extra_body` for compatible clients. Do not send conflicting top-level and nested values.

```json
{
  "model": "happy-horse",
  "prompt": "Turn the room into a warm wooden studio.",
  "video": "https://example.com/source-video.mp4",
  "extra_body": {
    "operation": "edit_video",
    "resolution": "720p",
    "audio_setting": "auto",
    "watermark": false
  }
}
```

## Response Examples

### Task accepted

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "happy-horse",
  "status": "queued",
  "progress": 0,
  "created_at": 1785801600,
  "video_url": null
}
```

## Task Status And Result

After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow.

For final-settlement operations such as video editing, read `billing_contract` again after completion.

## Media Constraints

### Image-to-video source image

- Formats: JPEG, JPG, PNG, BMP, or WebP.
- Minimum dimensions: `300px`.
- Aspect ratio: from `1:2.5` through `2.5:1`.
- Maximum file size: `10MB`.

### Multi-reference images

- Formats: JPEG, JPG, PNG, or WebP.
- Count: 1 to 9.
- Minimum short edge: `400px`; 720p or higher is recommended.
- Maximum file size: `10MB` per image.

### Video-editing source

- Formats: MP4 or MOV; H.264 is recommended.
- Input duration: 3 to 60 seconds; the editing service processes at most 15 seconds.
- Dimensions: long edge up to `2160px`, short edge at least `320px`.
- Aspect ratio: from `1:2.5` through `2.5:1`.
- Frame rate: greater than `8fps`.
- Maximum file size: `100MB`.

Edit reference images support JPEG, JPG, PNG, or WebP, must be at least `300px`, and are limited to `10MB` each.

## Billing Notes

- Text, image, and multi-reference generation use the requested output duration and resolution tier for settlement.
- Editing is finally settled from the actual input and output video durations. The final charge can differ from the initial estimate.
- `resolution` is a service tier and does not guarantee one exact pixel dimension for every aspect ratio or source image.
- Refer to the current UniAll pricing page and task settlement record for the final amount.

## Common Errors

| Error | Cause | Fix |
| --- | --- | --- |
| Invalid model | A removed tier-specific model ID was used | Set `model` to `happy-horse` |
| Missing parameter | `operation` or `resolution` is absent | Send both parameters explicitly |
| Unsupported parameter | `size` or `enable_safety_checker` was sent | Remove the unsupported field |
| Invalid media count | The selected operation received the wrong number of images or videos | Follow the operation matrix |
| Invalid resolution | `resolution` is `480p` or another unsupported value | Use `720p` or `1080p` |
| Invalid edit options | Editing includes `duration` or `aspect_ratio` | Remove the unsupported fields |
| Media download failed | A media URL is private, expired, redirected incorrectly, or unreachable | Use a stable public HTTPS URL |

## Related Pages

- [Happy Horse Video Generation](/models/video/happy-horse)
- [Video Generation Overview](/models/video/overview)

---

# Kling

Locale: en
URL: https://docs.uniall.ai/models/video/kling
Source: site-docs/models/video/kling.md
Description: Create Kling text, image, reference, motion-control, and video-editing tasks through UniAll.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

## Overview

Kling video capabilities use stable version-level model IDs. Select quality with the top-level `resolution` field and select the workflow with `operation`; do not encode quality, audio, or an upstream route in the model name.

| Model | Video capabilities | Resolution |
| --- | --- | --- |
| `kling-v3-turbo` | Text-to-video and single-first-frame image-to-video | `720p`, `1080p` |
| `kling-v3` | Text-to-video, image-to-video, first-last-frame, motion control, and digital human | `std`, `pro` |
| `kling-v3-omni` | Text-to-video, image-to-video, first-last-frame, multimodal reference, and video editing | `std`, `pro` |
| `kling-o1` | Text-to-video, image-to-video, first-last-frame, multimodal reference, and video editing | `std`, `pro` |

Availability depends on the model catalog, the API key's model permissions, and currently enabled routes. Historical quality, audio, silent, and digital-human tier model IDs are no longer accepted and are not converted automatically.

## When To Use It

- Use `kling-v3-turbo` for fast text or single-image video generation with `720p` or `1080p` output.
- Use `kling-v3` for first-last-frame generation, motion control, or digital-human video.
- Use `kling-v3-omni` for multimodal references and video editing with up to four reference images.
- Use `kling-o1` for the same reference and editing request shape with a `3` to `10` second generation range.

## Endpoint

| Action | Method | Path |
| --- | --- | --- |
| Create a video task | `POST` | `/v1/videos` |
| Query a video task | `GET` | `/v1/videos/{task_id}` |
| Download a completed video | `GET` | `/v1/videos/{task_id}/content` |

`POST /v1/videos/generations` and `POST /v1/video/generations` remain compatible creation paths. New integrations should use `POST /v1/videos`.

## Authentication

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## Resolution And Audio

Pass `resolution` at the request body's top level. Do not use `size` in its place. When omitted, Turbo defaults to `720p`; the other Kling video models default to `std`. Pass it explicitly when predictable output and billing records matter.

Kling video requests do not accept a `sound` switch. Describe dialogue, music, ambient sound, or silence in `prompt`. The `audio_url` and `voice_id` fields used by digital-human tasks are lip-sync inputs, not sound switches.

## Operations

| `operation` | Supported models | Required input |
| --- | --- | --- |
| `text_to_video` | Turbo, V3, Omni, O1 | `prompt` |
| `image_to_video` | Turbo, V3, Omni, O1 | `prompt` and `image` |
| `first_last_frame` | V3, Omni, O1 | `prompt`, `image`, and `last_image` |
| `reference_to_video` | Omni, O1 | `prompt` and image or video references |
| `edit_video` | Omni, O1 | `prompt` and `video_url`; reference images are optional |
| `motion_control` | V3 | `prompt`, `image`, `video`, and `character_orientation` |
| `avatar` | V3 | See [Digital Human Video](/models/avatar/digital-human) |

Duration rules:

- Turbo and V3 generation operations accept `3` to `15` seconds.
- Omni text-to-video, image-to-video, and first-last-frame operations accept `3` to `15` seconds; `reference_to_video` accepts `3` to `10` seconds.
- O1 generation operations accept `3` to `10` seconds.
- Motion control, digital human, and video editing use the duration rules of their operation; omit `duration` unless the operation explicitly accepts it.
- Turbo text-to-video accepts `aspect_ratio`; Turbo image-to-video does not.

## Request Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | Stable Kling video model ID. |
| `prompt` | string | Yes | Prompt required by the UniAll video task interface. |
| `operation` | string | Recommended | Workflow from the operations table. |
| `resolution` | string | No | Model-specific quality value; defaults are described above. |
| `duration` | integer | Conditional | Output duration for operations that accept it. |
| `aspect_ratio` | string | Conditional | `16:9`, `9:16`, or `1:1`. |
| `image` | string | Conditional | Public HTTP(S) image URL for image-to-video or the first frame. |
| `last_image` | string | Conditional | Last-frame image URL; use it together with `image`. |
| `reference_image_urls` | string[] | No | Up to four reference-image URLs for multimodal reference or editing. |
| `video_url` | string | Conditional | Base video URL for reference or editing operations. |
| `video` | string | Conditional | Motion-reference video URL for `motion_control`. |
| `keep_original_sound` | string | No | `yes` or `no` for multimodal reference and video editing. |
| `character_orientation` | string | Conditional | `image` or `video` for `motion_control`. |
| `watermark` | boolean | No | Whether to add an AIGC watermark. |

## Request Examples

### Turbo Text-To-Video

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-turbo",
    "operation": "text_to_video",
    "prompt": "A paper airplane crosses a quiet city street at dawn, cinematic camera movement, soft ambient sound.",
    "duration": 3,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "watermark": false
  }'
```

### Turbo Image-To-Video

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-turbo",
    "operation": "image_to_video",
    "prompt": "The paper airplane glides steadily forward while the camera follows slowly.",
    "image": "https://example.com/plane.png",
    "duration": 5,
    "resolution": "1080p"
  }'
```

Do not pass `aspect_ratio` for Turbo image-to-video.

### V3 First-Last-Frame

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "operation": "first_last_frame",
    "prompt": "The subject turns naturally toward the camera with a continuous, smooth transition.",
    "image": "https://example.com/first.png",
    "last_image": "https://example.com/last.png",
    "duration": 5,
    "resolution": "pro"
  }'
```

### V3 Motion Control

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "operation": "motion_control",
    "prompt": "Preserve the subject identity and clothing while reproducing the motion from the reference video.",
    "image": "https://example.com/person.png",
    "video": "https://example.com/motion.mp4",
    "resolution": "pro",
    "character_orientation": "image"
  }'
```

### Omni Multimodal Reference

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-omni",
    "operation": "reference_to_video",
    "prompt": "Preserve the subject and clothing while applying the referenced motion to the base video.",
    "reference_image_urls": [
      "https://example.com/person.png",
      "https://example.com/clothes.png"
    ],
    "video_url": "https://example.com/base.mp4",
    "duration": 8,
    "resolution": "pro",
    "keep_original_sound": "yes"
  }'
```

### Omni Video Editing

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-omni",
    "operation": "edit_video",
    "prompt": "Keep the subject motion unchanged and replace the background with a city street at night.",
    "video_url": "https://example.com/source.mp4",
    "reference_image_urls": [
      "https://example.com/city-style.png"
    ],
    "resolution": "pro",
    "keep_original_sound": "yes"
  }'
```

Use the same text, image, first-last-frame, reference, and editing request shape with `kling-o1`; its generation duration range is `3` to `10` seconds.

## Response Example

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "kling-v3",
  "status": "queued",
  "progress": 0
}
```

## Task Status And Result

Save `id` or `task_id`, then follow [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared 3-to-10-second polling interval, terminal statuses, result fields, error contract, and authenticated download flow.

## Billing Notes

Video billing normally depends on the public model, `operation`, `resolution`, and actual output duration. Task submission may reserve balance; the task settlement record and current model catalog price are the final billing source.

## Common Errors

- Using a historical quality, audio, silent, or digital-human tier model ID instead of one of the version-level IDs above.
- Passing `size` instead of `resolution`, or passing `sound` to a video request.
- Passing `aspect_ratio` to Turbo image-to-video.
- Requesting a duration outside the selected model and operation range.
- Mixing `image`, `reference_image_urls`, and video inputs in a way that duplicates the same reference.
- Passing image or video URLs that the service cannot access publicly.
- Resubmitting a paid task after one polling request times out instead of continuing to query the original `task_id`.

Public responses do not expose provider names, upstream task IDs, routes, credentials, or raw upstream requests.

## Related Pages

- [Kling Image](/models/image/kling)
- [Digital Human Video](/models/avatar/digital-human)
- [Video Generation Overview](/models/video/overview)

---

# Video Generation Overview

Locale: en
URL: https://docs.uniall.ai/models/video/overview
Source: site-docs/models/video/overview.md
Description: Create, poll, and retrieve UniAll video generation tasks through one shared lifecycle.

UniAll video models share one default asynchronous task lifecycle. Use each model page for model IDs, input fields, and capability limits; use this page for task polling, status handling, errors, and result retrieval.

## Models

- [Happy Horse](/models/video/happy-horse)
- [Seedance 2.0](/models/video/seedance-2-0)
- [Seedance 2.5](/models/video/seedance-2-5)
- [Grok Video 1.5](/models/video/grok/grok-video-1-5)
- [Grok Imagine](/models/video/grok-imagine)
- [Veo 3.1](/models/video/veo-3-1)
- [Gemini Omni Flash Preview](/models/video/gemini-omni-flash-preview)
- [Vidu Q3](/models/video/vidu)
- [Hailuo](/models/video/hailuo)
- [Kling](/models/video/kling)
- [Wan 2.6](/models/video/wan-2-6)
- [Sora 2](/models/video/sora-2)

## Default Endpoints

`{BASE_URL}` is `https://api.uniall.ai`.

| Action | Method | Endpoint |
| --- | --- | --- |
| Create a task | `POST` | `/v1/videos` |
| Query status and result | `GET` | `/v1/videos/{task_id}` |
| Download completed content | `GET` | `/v1/videos/{task_id}/content` |

Send `Authorization: Bearer sk-***` on every request. A model page may document a compatible creation path or a protocol-specific exception; its model IDs and request body still come from that model page.

## Video Task Lifecycle

### 1. Save The Task ID

A successful create request returns a public `id`. Some responses also include the same value as `task_id` for compatibility. Store either value before leaving the request flow.

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "model-name",
  "status": "queued",
  "progress": 0,
  "created_at": 1785801600
}
```

### 2. Poll The Task

Query the task every 3 to 10 seconds:

```bash
curl "{BASE_URL}/v1/videos/task_xxxxxxxxxxxxx" \
  -H "Authorization: Bearer sk-***"
```

Stop only when `status` becomes `completed` or `failed`. Do not create a duplicate task only because the current task remains `queued` or `in_progress`.

| Status | Terminal | Meaning |
| --- | --- | --- |
| `queued` | No | The task was accepted and is waiting for processing. |
| `in_progress` | No | Generation or result processing is still running. |
| `completed` | Yes | The final result is ready. |
| `failed` | Yes | The task ended without a result; inspect `error`. |

### 3. Read The Result

A completed task returns the public result in `video_url`, `result.video_url`, or `result.outputs[0]`. These fields can point to the same video.

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "model-name",
  "status": "completed",
  "progress": 100,
  "video_url": "https://example.com/generated-video.mp4",
  "result": {
    "video_url": "https://example.com/generated-video.mp4",
    "outputs": [
      "https://example.com/generated-video.mp4"
    ]
  },
  "error": null
}
```

Use the authenticated content endpoint when you need the finalized file:

```bash
curl -L "{BASE_URL}/v1/videos/task_xxxxxxxxxxxxx/content" \
  -H "Authorization: Bearer sk-***" \
  -o output.mp4
```

Do not call the content endpoint before completion. Download generated media promptly instead of treating a result URL as permanent storage.

### 4. Handle Failure

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "model-name",
  "status": "failed",
  "progress": 100,
  "result": null,
  "error": {
    "code": "task_failed",
    "message": "Video generation failed"
  }
}
```

Fix invalid inputs before creating a new task. Retry transient service errors with backoff, but do not repeatedly resubmit the same request while the original task is still active.

## Shared Response Fields

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Public task ID used for polling. |
| `task_id` | string | Compatible alias of `id` when present. |
| `object` | string | Task object type, commonly `video.generation.job`. |
| `model` | string | Public model ID used for creation. |
| `status` | string | `queued`, `in_progress`, `completed`, or `failed`. |
| `progress` | integer | Progress from `0` to `100` when available; it does not replace `status`. |
| `video_url` | string or null | Public result URL after completion. |
| `result` | object or null | Completed output details, including `video_url` or `outputs`. |
| `error` | object or null | Public `code` and `message` for a failed task. |
| `created_at` | integer | Unix creation timestamp when available. |
| `completed_at` | integer | Unix completion timestamp when available. |

## Model-Specific Exceptions

Gemini Omni Flash Preview creates requests through `POST /v1beta/interactions`. When a follow-up query is needed, use the returned `interaction_id` with `GET /v1/videos/generations/{interaction_id}`. Its terminal statuses, error handling, and result fields follow the same rules above.

Protocol-specific pages such as Sora 2 Native OpenAI Format may stream their own response instead of returning a standard video task. Follow the response flow documented on that page.

---

# Seedance 2.0

Locale: en
URL: https://docs.uniall.ai/models/video/seedance-2-0
Source: site-docs/models/video/seedance-2-0.md
Description: Generate videos with Seedance 2.0 models through UniAll video APIs.

Seedance 2.0 supports text-to-video, image-to-video, first-and-last-frame generation, multimodal references, video editing, and video extension. Start with the [Seedance 2.0 Series Guide](/models/video/seedance-2-0/series-guide) for new integrations. Use the [Seedance 2.0 Material Library](/models/video/seedance-2-0/material-library) to prepare reusable image, video, and audio inputs.

## Supported Models

| Model | Supported Resolutions | Recommended Use |
| --- | --- | --- |
| `seedance2.0` | `480p`, `720p`, `1080p`, `4k` | Full capabilities with quality prioritized. |
| `seedance2.0-fast` | `480p`, `720p` | Faster generation. |
| `seedance2.0-mini` | `480p`, `720p` | Lightweight and speed-focused tasks. |

## Endpoint

```http
POST /v1/videos
GET  /v1/videos/{task_id}
GET  /v1/videos/{task_id}/content
```

The older `/v1/videos/generations` and `/v1/video/generations` creation endpoints remain available for compatible clients.

## Authentication

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## Request Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | `seedance2.0`, `seedance2.0-fast`, or `seedance2.0-mini`. |
| `resolution` | string | Yes | A resolution supported by the selected model. |
| `prompt` | string | Conditional | Video prompt. Use a `type=text` item for `content[]` requests. |
| `duration` | integer/string | Yes | Output duration from `4` to `15` seconds. |
| `aspect_ratio` | string | No | Output aspect ratio; `ratio` is the compatibility alias. |
| `content` | object[] | No | Multimodal text, image, video, and audio inputs with explicit roles. |
| `operation` | string | Conditional | `reference_to_video`, `edit_video`, or `extend_video`. |
| `generate_audio` | boolean | No | Whether to generate a video with audio. |
| `return_last_frame` | boolean | No | Whether to return the generated video's last frame. |

## Request Example

```bash
curl -X POST "https://api.uniall.ai/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0",
    "prompt": "A clean commercial product video with slow camera movement, soft reflections, and realistic lighting.",
    "resolution": "720p",
    "duration": 8,
    "aspect_ratio": "16:9",
    "generate_audio": false,
    "seed": 42,
    "watermark": false
  }'
```

## Multi-Reference Example

```bash
curl -X POST "https://api.uniall.ai/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0-fast",
    "resolution": "720p",
    "duration": 6,
    "aspect_ratio": "9:16",
    "operation": "reference_to_video",
    "content": [
      {
        "type": "text",
        "text": "Create a fast fashion lookbook clip while preserving the product identity."
      },
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/model.png"},
        "role": "reference_image"
      },
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/outfit.png"},
        "role": "reference_image"
      }
    ],
    "generate_audio": true
  }'
```

## Task Status And Result

After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow.

## Common Errors

- Using an old create task interface for a new integration.
- Sending more than `9` reference images.
- Sending more than `3` reference videos or reference videos whose total duration exceeds `15` seconds.
- Using a `duration` outside `4` to `15`.
- Passing incompatible operation hints together with the new input format.

## Related Pages

- [Seedance 2.0 Series Guide](/models/video/seedance-2-0/series-guide)
- [Seedance 2.0 Material Library](/models/video/seedance-2-0/material-library)
- [Video Generation Overview](/models/video/overview)

---

# Seedance 2.0 Material Library

Locale: en
URL: https://docs.uniall.ai/models/video/seedance-2-0/material-library
Source: site-docs/models/video/seedance-2-0/material-library.md
Description: Create, verify, query, list, use, and delete reusable Seedance 2.0 materials through the UniAll.ai API.

The material library lets you prepare reusable images, videos, and audio files before submitting Seedance 2.0 video tasks. The API manages materials by UniAll.ai user: clients use only their UniAll.ai API key, a local `mat_*` material ID, and the returned `asset://` URI.

This guide reflects the public contract updated on July 29, 2026.

## Overview

The shortest integration flow is:

1. Create a material with a public HTTP(S) URL and an `Idempotency-Key`.
2. Poll the returned `mat_*` ID until `status` is `available`.
3. Read the `asset://` value from `uri`.
4. Put that URI in a structured image, video, or audio field in the Seedance request.
5. Delete the material when it is no longer needed, or let it expire automatically.

The first API version accepts public HTTP(S) URLs only. Direct file upload is not supported.

## Base URL And Endpoints

All examples use this Base URL:

```uri
https://api.uniall.ai
```

| Operation | Endpoint | Result |
| --- | --- | --- |
| Create a material | `POST /v1/materials` | Starts processing and returns a local `mat_*` ID. |
| Get a material | `GET /v1/materials/{material_id}` | Returns current status and the usable URI when available. |
| List materials | `GET /v1/materials` | Returns the current user's visible materials. |
| Delete a material | `DELETE /v1/materials/{material_id}` | Cancels or deletes the material workflow. |

## Authentication And Idempotency

All material endpoints use the same UniAll.ai API key as video requests:

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

Material creation also requires an idempotency key:

```http
Idempotency-Key: material-order-20260729-0001
```

The key must contain 1 to 200 visible ASCII characters, with no spaces or control characters.

- Retrying the same normalized request with the same key returns the same local material workflow.
- Reusing a key for a different request returns `material_idempotency_conflict`.
- After a timeout or uncertain network result, retry with the original key. Do not generate a new key.
- Use a new key when intentionally creating a new material.

## Input URL Requirements

The source URL must:

- use `http://` or `https://`;
- remain directly reachable while the material is processing;
- work without login, cookies, browser state, custom headers, or private network access;
- return media that matches the declared `type`;
- remain accessible until the material reaches a terminal status.

## Quick Start

### 1. Create A Material

```bash
curl -X POST "https://api.uniall.ai/v1/materials" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: material-order-20260729-0001" \
  -d '{
    "url": "https://cdn.example.com/product.png",
    "type": "image",
    "name": "Product reference"
  }'
```

The API returns HTTP `202` and a local material record:

```json
{
  "id": "mat_xxxxxxxxxxxxx",
  "object": "material",
  "name": "Product reference",
  "type": "image",
  "status": "processing",
  "uri": null,
  "preview_url": null,
  "created_at": "2026-07-29T10:00:00Z",
  "available_at": null,
  "expires_at": null
}
```

### 2. Wait Until Available

```bash
curl "https://api.uniall.ai/v1/materials/mat_xxxxxxxxxxxxx" \
  -H "Authorization: Bearer sk-***"
```

Poll every 3 to 5 seconds. Do not use `uri` until `status` is `available`:

```json
{
  "id": "mat_xxxxxxxxxxxxx",
  "object": "material",
  "name": "Product reference",
  "type": "image",
  "status": "available",
  "uri": "asset://asset-xxxxxxxxxxxxx",
  "preview_url": "https://example.com/short-lived-preview.jpg",
  "created_at": "2026-07-29T10:00:00Z",
  "available_at": "2026-07-29T10:01:00Z",
  "expires_at": "2026-07-29T12:01:00Z"
}
```

### 3. Use The URI In Seedance

Copy the returned `uri` into the matching structured media field:

```bash
curl -X POST "https://api.uniall.ai/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0",
    "resolution": "720p",
    "duration": 6,
    "content": [
      {
        "type": "text",
        "text": "Keep the product appearance consistent and use a slow cinematic camera move."
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "asset://asset-xxxxxxxxxxxxx"
        },
        "role": "reference_image"
      }
    ]
  }'
```

Do not put an `asset://` URI in `prompt` or another plain-text field. UniAll.ai checks ownership, status, and expiry before the media is submitted for generation. Unknown, expired, deleted, or another user's material is rejected. Regular HTTP(S) media inputs continue to work as documented in the series guide.

## Create Materials

```http
POST /v1/materials
```

### Request Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | Yes | Public HTTP(S) image, video, or audio URL. |
| `type` | string | Yes | `image`, `video`, or `audio`. |
| `name` | string | No | User-facing material name. |
| `real_person` | object | No | Required declaration and callback settings for a real-person image or video. |
| `real_person.consent_confirmed` | boolean | Yes with `real_person` | Must be the JSON boolean `true`, confirming that separate consent was obtained. |
| `real_person.callback_url` | string | Yes with `real_person` | Browser redirect after visual verification. Production URLs must use HTTPS. |

### Real-Person Materials

Real-person images and videos require an explicit consent declaration and browser-based liveness verification. Real-person audio is not supported.

```bash
curl -X POST "https://api.uniall.ai/v1/materials" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: real-person-material-20260729-0001" \
  -d '{
    "url": "https://cdn.example.com/person.jpg",
    "type": "image",
    "name": "Authorized portrait",
    "real_person": {
      "consent_confirmed": true,
      "callback_url": "https://client.example.com/material-complete"
    }
  }'
```

HTTP `202` can return `verification_pending` with a temporary `verification_url`:

```json
{
  "id": "mat_xxxxxxxxxxxxx",
  "object": "material",
  "name": "Authorized portrait",
  "type": "image",
  "status": "verification_pending",
  "uri": null,
  "preview_url": null,
  "verification_url": "https://example.com/temporary-h5-token",
  "created_at": "2026-07-29T10:00:00Z",
  "available_at": null,
  "expires_at": null,
  "verification_expires_at": "2026-07-29T10:30:00Z"
}
```

Have the person open `verification_url` in a browser and complete the H5 liveness flow. After successful verification, UniAll.ai submits the actual material automatically. Do not call `POST /v1/materials` again.

The browser then redirects to `real_person.callback_url` with only these query parameters:

```uri
material_id=mat_xxxxxxxxxxxxx&material_status=processing
```

The callback status can be `creating`, `processing`, `available`, or a verification failure status. The redirect confirms that the verification result was received; it does not guarantee that the material is already available. Continue querying the material record. Background recovery can continue the workflow if the browser callback is lost.

`verification_url` appears only in the create response or an idempotent replay of that response. Get, list, and delete responses never include it.

## Get A Material

```http
GET /v1/materials/{material_id}
```

Only the user associated with the current API key can retrieve the material. The response does not expose the original input URL, visual-verification identifiers, internal material identifiers, routing details, credentials, temporary H5 tokens, or callback verification state.

Materials are currently valid for two hours after becoming available. At `expires_at`, the record is archived as `deleted`; subsequent user detail requests return `404 material_not_found`.

## List Materials

```http
GET /v1/materials
```

| Query parameter | Required | Description |
| --- | --- | --- |
| `type` | No | `image`, `video`, or `audio`. |
| `status` | No | `creating`, `verification_pending`, `processing`, `available`, or `delete_pending`. |
| `limit` | No | Page size from 1 to 100. Default: `50`. |
| `after` | No | Opaque cursor returned by the previous page. |

```bash
curl "https://api.uniall.ai/v1/materials?type=image&status=available&limit=20" \
  -H "Authorization: Bearer sk-***"
```

```json
{
  "object": "material.list",
  "data": [
    {
      "id": "mat_xxxxxxxxxxxxx",
      "object": "material",
      "name": "Product reference",
      "type": "image",
      "status": "available",
      "uri": "asset://asset-xxxxxxxxxxxxx",
      "preview_url": "https://example.com/short-lived-preview.jpg",
      "created_at": "2026-07-29T10:00:00Z",
      "available_at": "2026-07-29T10:01:00Z",
      "expires_at": "2026-07-29T12:01:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "opaque-cursor-value"
}
```

Pass `next_cursor` unchanged as `after` to request the next page. Do not parse or construct cursor values.

The user list excludes failed, verification-failed, verification-expired, deleted, historical expired, and already expired records awaiting archival. These records can remain available to administrators for audit and troubleshooting.

## Delete A Material

```http
DELETE /v1/materials/{material_id}
```

```bash
curl -X DELETE "https://api.uniall.ai/v1/materials/mat_xxxxxxxxxxxxx" \
  -H "Authorization: Bearer sk-***"
```

- HTTP `200` with `status=deleted` means deletion is complete.
- HTTP `202` with `status=delete_pending` means deletion was accepted and is still processing.
- Deleting a material whose real-person verification is incomplete cancels the local workflow.
- Delete is idempotent. A deleted material cannot be used for generation.

Both successful status codes return the full material object used by the detail endpoint.

## Material Statuses

| Status | Meaning |
| --- | --- |
| `creating` | UniAll.ai is initializing the material workflow. |
| `verification_pending` | Waiting for real-person H5 verification. |
| `verification_failed` | Verification failed or the session creation result is uncertain. |
| `verification_expired` | The verification session expired. |
| `processing` | The media was submitted and is being processed. |
| `available` | The material can be used in a generation request. |
| `failed` | Material creation or processing failed. |
| `delete_pending` | Deletion was submitted and is still processing. |
| `deleted` | Deletion is complete. This status can appear in a delete response but not in get or list results. |

`verification_failed`, `verification_expired`, and `failed` are terminal failure states. Replaying the original creation key returns the original failed workflow; use a new `Idempotency-Key` to create a new material.

## Security And Lifecycle Notes

- Treat `verification_url` as a secret because it contains a temporary H5 token. Do not write it to application logs, analytics events, support messages, or public pages.
- Do not log complete real-person callback URLs, query parameters, or callback verification state.
- `preview_url` is short-lived. Do not treat it as permanent storage or distribute it as a stable public link.
- Do not depend on the original input URL being returned by get or list endpoints.
- Use only the `asset://` URI returned for a currently `available` material owned by the same user.

## Common Errors

Errors use an OpenAI-compatible structure:

```json
{
  "error": {
    "message": "The material is not available.",
    "type": "invalid_request_error",
    "code": "material_not_available"
  }
}
```

| Error code | Meaning |
| --- | --- |
| `invalid_idempotency_key` | `Idempotency-Key` is missing or invalid. |
| `invalid_material_request` | A URL, type, name, or query parameter is invalid. |
| `invalid_material_cursor` | `after` is not a cursor returned by this endpoint. |
| `material_channel_unavailable` | The material service is temporarily unavailable or the current model does not support material input. |
| `material_idempotency_conflict` | The same idempotency key was used for a different request. |
| `material_not_found` | The material does not exist, belongs to another user, or has expired and been archived. |
| `material_not_available` | The material is not available, has expired, or was deleted. |
| `material_not_managed` | The `asset://` URI is not registered in the current user's UniAll.ai material library. |
| `visual_verification_consent_required` | Consent was not explicitly confirmed for a real-person material. |
| `invalid_visual_verification_request` | The real-person media type or callback URL is invalid. |
| `visual_verification_create_outcome_uncertain` | The first verification-session creation result is uncertain; a duplicate session is not created automatically. |
| `material_create_outcome_uncertain` | The material creation result is uncertain while UniAll.ai performs background reconciliation. |

Error messages contain only public information and do not expose upstream errors, internal routing, or credentials.

## Related Pages

- [Seedance 2.0 Series Guide](/models/video/seedance-2-0/series-guide)
- [Seedance 2.0 Video Generation](/models/video/seedance-2-0)

---

# Seedance 2.0 Series Guide

Locale: en
URL: https://docs.uniall.ai/models/video/seedance-2-0/series-guide
Source: site-docs/models/video/seedance-2-0/series-guide.md
Description: Use Seedance 2.0, Seedance 2.0 Fast, and Seedance 2.0 Mini through UniAll with multimodal input, video editing, extension, and task polling.

Updated: 2026-07-29

Use the Seedance 2.0 series through UniAll. New integrations should use one of the three stable public model IDs and select the resolution and generation capability through request parameters.

## 1. Choose a Model

| Public Model | Supported Resolutions | Recommended Use |
| --- | --- | --- |
| `seedance2.0` | `480p`, `720p`, `1080p`, `4k` | Full capabilities with quality prioritized |
| `seedance2.0-fast` | `480p`, `720p` | Faster generation |
| `seedance2.0-mini` | `480p`, `720p` | Lightweight and speed-focused tasks |

All three models support:

- text-to-video;
- single-image-to-video;
- first-and-last-frame generation;
- multimodal image, video, and audio references;
- video editing and extension;
- generated audio, watermarks, and random seeds;
- web search for text-only requests;
- returning the generated video's last frame;
- existing `asset://` asset IDs.

## 2. Endpoints and Authentication

Use the OpenAI-compatible video task endpoints:

```http
POST /v1/videos
GET  /v1/videos/{task_id}
GET  /v1/videos/{task_id}/content
```

Request headers:

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

Use this value for `{BASE_URL}` in the examples:

```uri
https://api.uniall.ai
```

The following compatibility endpoints remain available:

```http
POST /v1/videos/generations
GET  /v1/videos/generations/{task_id}

POST /v1/video/generations
GET  /v1/video/generations/{task_id}
```

New integrations should use `/v1/videos` consistently.

## 3. Common Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | One of the three public models, or a fixed-resolution model ID during the compatibility period. |
| `prompt` | string | Conditional | Video prompt. When using `content[]`, include at least one `type=text` item instead. |
| `resolution` | string | Yes for new public models | Output resolution from the selected model's supported values. |
| `size` | string | No | Compatibility alias for `resolution`. |
| `duration` | integer/string | Yes | Output duration from `4` to `15` seconds. The compatible value `auto` is accepted, but an explicit integer is recommended. |
| `aspect_ratio` | string | No | `auto`, `21:9`, `16:9`, `4:3`, `3:2`, `2:3`, `1:1`, `3:4`, or `9:16`. |
| `ratio` | string | No | Compatibility alias for `aspect_ratio`; `adaptive` is equivalent to `auto`. |
| `content` | object[] | No | Recommended multimodal input format described in the next section. |
| `operation` | string | Required for specific capabilities | `reference_to_video`, `edit_video`, or `extend_video`. |
| `generate_audio` | boolean | No | Whether to generate a video with audio. |
| `watermark` | boolean | No | Whether to add a watermark. |
| `seed` | integer | No | Random seed. |
| `return_last_frame` | boolean | No | Whether to return a last-frame URL in the completed result. |
| `tools` | object[] | No | Currently supports only `[{"type":"web_search"}]`. |

Compatibility rules:

- `resolution` and `size` must match when both are present.
- `aspect_ratio` and `ratio` must express the same ratio when both are present.
- `ratio: "adaptive"` is equivalent to `aspect_ratio: "auto"`.
- `operation`, `generate_audio`, `watermark`, `seed`, `return_last_frame`, and `tools` may also be placed inside `extra_body`. Do not repeat the same parameter at the top level and in `extra_body`.
- `draft`, `frames`, `camera_fixed`, and `service_tier: "flex"` are outside the current public contract.

## 4. Multimodal `content[]` Format

Use `content[]` for complex inputs:

```json
{
  "content": [
    {
      "type": "text",
      "text": "Video prompt"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/image.png"
      },
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/video.mp4"
      },
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": {
        "url": "https://example.com/audio.mp3"
      },
      "role": "reference_audio"
    }
  ]
}
```

Supported types and roles:

| `type` | `role` | Meaning |
| --- | --- | --- |
| `text` | None | One or more prompt items. |
| `image_url` | `image` | Input image for single-image-to-video. |
| `image_url` | `reference_image` | Reference image. |
| `image_url` | `first_frame` | First-frame image. |
| `image_url` | `last_frame` | Last-frame image. |
| `video_url` | `source_video` | Source video for editing or extension. |
| `video_url` | `reference_video` | Reference video. |
| `audio_url` | `reference_audio` | Reference audio. |

Input constraints:

- `content[]` must contain at least one non-empty text item.
- Use no more than 9 images, 3 videos, and 3 audio files.
- `first_frame` and `last_frame` must be provided together, with one image for each role.
- First-and-last-frame mode cannot include videos, audio, or other images.
- Do not mix the `image` and `reference_image` roles in one request.
- Use no more than one `source_video`.
- Reference audio requires at least one image or video. Audio-only and text-plus-audio requests are not accepted.
- With multiple reference assets, use `@Image1`, `@Video1`, and `@Audio1` in the prompt to identify assets by order.

Simple requests remain compatible with `image`, `images`, `last_image`, `video`, `videos`, and `audios`. Use `content[]` for new capabilities and multimodal combinations so each input role is explicit.

## 5. Request Examples

### 5.1 Text-to-Video

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0",
    "prompt": "A futuristic city street after rain, neon reflections, and a slow cinematic camera push forward.",
    "resolution": "1080p",
    "duration": 5,
    "ratio": "16:9",
    "generate_audio": true
  }'
```

### 5.2 Single-Image-to-Video

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0-fast",
    "resolution": "720p",
    "duration": 6,
    "content": [
      {
        "type": "text",
        "text": "The person turns naturally toward the camera, clothing moves gently in the wind, and identity remains consistent."
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/person.png"
        },
        "role": "image"
      }
    ]
  }'
```

### 5.3 First-and-Last-Frame Video

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0",
    "resolution": "720p",
    "duration": 6,
    "content": [
      {
        "type": "text",
        "text": "Transition naturally from day to night with continuous motion and stable building structure."
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/first.png"
        },
        "role": "first_frame"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/last.png"
        },
        "role": "last_frame"
      }
    ]
  }'
```

### 5.4 Multimodal Reference-to-Video

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0-mini",
    "resolution": "720p",
    "duration": 8,
    "operation": "reference_to_video",
    "content": [
      {
        "type": "text",
        "text": "Show the product from @Image1 with the camera motion from @Video1 and the rhythm from @Audio1."
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/product.png"
        },
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": {
          "url": "https://example.com/motion.mp4"
        },
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": {
          "url": "https://example.com/music.mp3"
        },
        "role": "reference_audio"
      }
    ]
  }'
```

### 5.5 Video Editing

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0",
    "resolution": "720p",
    "duration": 6,
    "operation": "edit_video",
    "content": [
      {
        "type": "text",
        "text": "Replace the background with a neon street at night while preserving the person's motion and identity."
      },
      {
        "type": "video_url",
        "video_url": {
          "url": "https://example.com/source.mp4"
        },
        "role": "source_video"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/style.png"
        },
        "role": "reference_image"
      }
    ]
  }'
```

### 5.6 Video Extension

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0-fast",
    "resolution": "720p",
    "duration": 5,
    "operation": "extend_video",
    "content": [
      {
        "type": "text",
        "text": "Continue the camera motion as the person walks forward, preserving the lighting and scene."
      },
      {
        "type": "video_url",
        "video_url": {
          "url": "https://example.com/source.mp4"
        },
        "role": "source_video"
      }
    ]
  }'
```

### 5.7 Text-Only Web Search

Web search works only with text input. Do not include images, video, or audio in the same request.

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0-mini",
    "prompt": "Create a concise news video from today's publicly available technology news without showing brand logos.",
    "resolution": "720p",
    "duration": 5,
    "tools": [
      {
        "type": "web_search"
      }
    ]
  }'
```

`web_search` allows the model to retrieve public information, but it does not guarantee that every generation will perform a search.

### 5.8 Return the Last Frame

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0",
    "prompt": "A paper boat slowly stops beside a stone bridge, with a stable final frame.",
    "resolution": "720p",
    "duration": 5,
    "return_last_frame": true
  }'
```

When the task completes, the last frame is returned as `result.last_frame_url` and is not mixed into the video `outputs` array.

### 5.9 Use A Managed Material

Create and query reusable inputs through the [Seedance 2.0 Material Library](/models/video/seedance-2-0/material-library). When the material reaches `status=available`, replace a regular media URL with the returned `uri`:

```json
{
  "type": "video_url",
  "video_url": {
    "url": "asset://asset-xxxxxxxxxxxxx"
  },
  "role": "source_video"
}
```

Use the URI only in the matching structured image, video, or audio field. Do not put it in the prompt. UniAll.ai verifies the current user's ownership, material status, and expiry before creating the video task.

## 6. Task Status And Result

A successful create request returns an asynchronous task:

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "seedance2.0",
  "status": "queued",
  "progress": 0,
  "created_at": 1784640000
}
```

After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow.

When a Seedance request produces a last frame, the completed response may also include `result.last_frame_url`.

## 7. Fixed-Resolution Model Compatibility

Existing clients may continue using fixed-resolution model IDs:

| Model Series | Compatible Model IDs |
| --- | --- |
| Standard | `seedance2.0-480p`, `seedance2.0-720p`, `seedance2.0-1080p`, `seedance2.0-4k` |
| Fast | `seedance2.0-fast-480p`, `seedance2.0-fast-720p` |
| Mini | `seedance2.0-mini-480p`, `seedance2.0-mini-720p` |

The following earlier IDs also remain compatible:

- `seedance2.0-video-480p`
- `seedance2.0-video-720p`
- `seedance2.0-fast-video-480p`
- `seedance2.0-fast-video-720p`

Fixed-resolution model IDs determine the resolution and do not require an additional `resolution` field. They support the same parameters and capabilities as the corresponding public model. If `resolution` or `size` is still present, its value must match the resolution in the model ID.

New projects should migrate to the three public model IDs so output resolution can be changed through a request parameter.

## 8. Common Errors

| Scenario | Result | Fix |
| --- | --- | --- |
| New public model is missing `resolution`/`size` | HTTP `400` | Pass a supported resolution. |
| `resolution` and `size` differ | HTTP `400` | Pass one field, or make both values identical. |
| `aspect_ratio` and `ratio` conflict | HTTP `400` | Pass one field, or make both express the same ratio. |
| Missing `duration` | HTTP `400` | Pass an integer from `4` to `15`. |
| `content[]` has no text item | HTTP `400` | Add a non-empty `type=text` item. |
| First and last frames are not paired | HTTP `400` | Pass both `first_frame` and `last_frame`. |
| Audio-only or text-plus-audio input | HTTP `400` | Add at least one image or video. |
| Web-search request contains media | HTTP `400` | Keep only text input in a search request. |
| Too many images, videos, or audio files | HTTP `400` | Keep the counts at or below 9, 3, and 3. |
| `draft`, `frames`, `camera_fixed`, or `service_tier=flex` is used | HTTP `400` | Remove the unsupported parameter. |

For safety-review, media-format, or parameter errors, fix the input and create a new task instead of repeatedly submitting the same invalid request.

## 9. Related Pages

- [Seedance 2.0](/models/video/seedance-2-0)
- [Seedance 2.0 Material Library](/models/video/seedance-2-0/material-library)
- [Video Generation Overview](/models/video/overview#video-task-lifecycle)

---

# Seedance 2.5

Locale: en
URL: https://docs.uniall.ai/models/video/seedance-2-5
Source: site-docs/models/video/seedance-2-5.md
Description: Create text, image, multimodal-reference, editing, and extension video tasks with Seedance 2.5 through UniAll.

`{BASE_URL}` is `https://api.uniall.ai` throughout this page.

Updated: 2026-08-12

## Overview

UniAll exposes Seedance 2.5 through one stable public model ID: `seedance2.5`. It supports text-to-video, first-frame and first-and-last-frame generation, multimodal references, video editing, video extension, reusable `asset://` media, and optional web search.

| Capability | Required input | Key rule |
| --- | --- | --- |
| Text-to-video | Prompt | Set `resolution` and `duration`. |
| First-frame video | One first-frame image | Omit `aspect_ratio` or use `auto`. |
| First-and-last-frame video | One first-frame and one last-frame image | Omit `aspect_ratio` or use `auto`. |
| Multimodal reference | Images, videos, or audio | Text is optional; audio-only reference requests are allowed. |
| Video editing | Prompt and one video | Set `operation: "edit_video"` and `duration: "auto"`. |
| Video extension | Prompt and one video | Set `operation: "extend_video"` explicitly. |

## Endpoints And Authentication

| Action | Method | Path |
| --- | --- | --- |
| Create task | `POST` | `/v1/videos` |
| Query task | `GET` | `/v1/videos/{task_id}` |
| Download completed video | `GET` | `/v1/videos/{task_id}/content` |

Compatible creation and query aliases remain available to existing clients:

```http
POST /v1/videos/generations
POST /v1/video/generations
GET  /v1/videos/generations/{task_id}
GET  /v1/video/generations/{task_id}
```

New integrations should use `/v1/videos` and `/v1/videos/{task_id}`.

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## Request Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | Must be `seedance2.5`. |
| `resolution` | string | Yes | `480p` or `720p`. |
| `size` | string | No | Compatibility alias for `resolution`. If both are present, they must match. |
| `duration` | integer/string | Yes | Integer from `4` through `30`, or `auto`. Operation-specific rules apply. |
| `prompt` | string | Conditional | Text instruction. Required for text generation, editing, and extension; optional for media-only reference requests. |
| `aspect_ratio` | string | No | `auto`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, or `9:16`. |
| `ratio` | string | No | Compatibility alias for `aspect_ratio`; `adaptive` is normalized to `auto`. |
| `output_format` | string | No | `mp4` or `mov`; default `mp4`. Compatible clients may use `extra_body.output_format`. |
| `content` | object[] | No | Multimodal image, video, and audio items with explicit roles. |
| `operation` | string | Conditional | Explicitly required for `edit_video` and `extend_video`; use `reference_to_video` for multimodal reference generation when an operation is sent. |
| `generate_audio` | boolean | No | Whether the task should generate audio. |
| `seed` | integer | No | Random seed for reproducible variation where supported. |
| `watermark` | boolean | No | Whether to add a watermark. |
| `return_last_frame` | boolean | No | Whether to return the final generated frame when available. |
| `tools` | object[] | No | Only `[{"type":"web_search"}]` is accepted. |

The following fields are not part of the public Seedance 2.5 contract and are rejected: `draft`, `frames`, `camera_fixed`, and `service_tier: "flex"`.

## Minimal Text-To-Video Request

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.5",
    "prompt": "A cinematic city street after rain",
    "resolution": "720p",
    "duration": 8,
    "aspect_ratio": "16:9",
    "output_format": "mp4"
  }'
```

## Media Inputs

Use `content[]` for new multimodal integrations. Each item carries one media type and an explicit role.

| Item type | URL field | Supported roles |
| --- | --- | --- |
| `image_url` | `image_url.url` | `first_frame`, `last_frame`, `reference_image` |
| `video_url` | `video_url.url` | `reference_video` |
| `audio_url` | `audio_url.url` | `reference_audio` |

Media URLs may be public HTTP(S) URLs or valid `asset://` references. HTTP(S) media must remain reachable by the UniAll service without cookies or custom request headers. See the [Seedance Material Library](/models/video/seedance-2-0/material-library) for creating reusable `asset://` inputs.

The compatibility fields `image`, `images`, `video`, `videos`, `audios`, and `last_image` remain accepted. Do not send conflicting values through both `content[]` and compatibility fields.

### Media Limits

- Up to `30` images.
- Up to `10` videos.
- Up to `10` audio files.
- Up to `50` media items in total.
- A multimodal request may omit text.
- An audio-only reference request is valid.

## Operation Rules

| Mode | `operation` | `duration` | `aspect_ratio` |
| --- | --- | --- | --- |
| Text-to-video | Omit | `auto` or integer `4..30` | Any supported value |
| First-frame video | Omit | `auto` or integer `4..30` | Omit or `auto` |
| First-and-last-frame video | Omit | `auto` or integer `4..30` | Omit or `auto` |
| Multimodal reference | `reference_to_video` when specified | `auto` or integer `4..30` | Follow the media mode; frame inputs require `auto` |
| Video editing | `edit_video` required | `auto` only | Omit or `auto` |
| Video extension | `extend_video` required | `auto` or integer `4..30` | Omit or `auto` |

Do not rely on prompt keywords to select editing or extension. Those requests must carry an explicit `operation`.

## Request Examples

### First-And-Last-Frame Video

```json
{
  "model": "seedance2.5",
  "prompt": "Move naturally from the first composition to the last while preserving the subject.",
  "resolution": "720p",
  "duration": 10,
  "aspect_ratio": "auto",
  "content": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/first.png"
      },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/last.png"
      },
      "role": "last_frame"
    }
  ]
}
```

For a single first frame, send only the `first_frame` item. In both frame modes, fixed aspect ratios are rejected because the source frame determines the composition.

### Multimodal Reference

```json
{
  "model": "seedance2.5",
  "operation": "reference_to_video",
  "resolution": "720p",
  "duration": 12,
  "content": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/product.png"
      },
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/motion.mp4"
      },
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": {
        "url": "https://example.com/music.mp3"
      },
      "role": "reference_audio"
    }
  ]
}
```

### Video Editing

```json
{
  "model": "seedance2.5",
  "prompt": "Replace the sky and preserve the subject",
  "video": "https://example.com/source.mp4",
  "operation": "edit_video",
  "resolution": "720p",
  "duration": "auto",
  "aspect_ratio": "auto"
}
```

### Video Extension

```json
{
  "model": "seedance2.5",
  "prompt": "Continue the camera movement into the illuminated square.",
  "video": "asset://mat_xxxxxxxxxxxxx",
  "operation": "extend_video",
  "resolution": "720p",
  "duration": 8,
  "aspect_ratio": "auto",
  "output_format": "mov"
}
```

### Web Search

```json
{
  "model": "seedance2.5",
  "prompt": "Create a concise visual recap of the latest public spaceflight milestone.",
  "resolution": "720p",
  "duration": 8,
  "tools": [
    {
      "type": "web_search"
    }
  ]
}
```

Web search can be combined with media inputs. No other `tools` shape is accepted.

## Create Response And Task Lifecycle

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "seedance2.5",
  "status": "queued",
  "progress": 0,
  "created_at": 1786492800
}
```

Store the public `id` or `task_id`. Poll `GET /v1/videos/{task_id}` every 2 to 5 seconds and stop when `status` is `completed` or `failed`. A completed task returns a public result URL; you can also retrieve the file through the authenticated `/v1/videos/{task_id}/content` endpoint.

See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for public status fields, completed and failed response examples, and download handling. Client applications should use only the public task ID, status, result, usage, and error fields documented by UniAll.

## Billing Notes

Seedance 2.5 is settled by valid completion Token usage after the task finishes. Any pre-deduction is an estimate; use the completed task's effective `usage` and settlement record as the final amount.

| Input type | Reference base rate per 1 million completion Tokens |
| --- | --- |
| Request without video input | About `$10.294117647` (`70 CNY / 6.8`) |
| Request containing video input | About `$6.176470588` (`42 CNY / 6.8`) |

- `480p` and `720p` use the same Token unit rate.
- These values are completion-Token reference rates, not fixed per-second prices.
- Account and pricing-group rules can change the final user price. Use the current UniAll pricing page and task settlement record as the authoritative source.

## Common Errors

| Error | Cause | Fix |
| --- | --- | --- |
| Missing parameter | `resolution` or `duration` is absent | Send both required fields. |
| Invalid resolution | `1080p`, `4k`, or another unsupported value was sent | Use `480p` or `720p`. |
| Conflicting aliases | `resolution` and `size` contain different values | Remove `size` or make the values identical. |
| Invalid edit duration | `edit_video` uses an integer duration | Set `duration` to `auto`. |
| Invalid aspect ratio | A frame, edit, or extension request uses a fixed ratio | Omit `aspect_ratio` or set it to `auto`. |
| Media limit exceeded | Per-type or total media limits were exceeded | Reduce media to the documented limits. |
| Media unavailable | A URL is private, expired, or unreachable from the public internet | Use a stable public URL or an available `asset://` material. |
| Invalid tools | `tools` is not exactly the supported web-search structure | Send `[{"type":"web_search"}]` or omit `tools`. |
| Unsupported field | `draft`, `frames`, `camera_fixed`, or `service_tier: "flex"` was sent | Remove the unsupported field. |

## Related Pages

- [Video Generation Overview](/models/video/overview)
- [Seedance 2.0](/models/video/seedance-2-0)
- [Seedance Material Library](/models/video/seedance-2-0/material-library)
- [Models](/models)

---

# Sora 2

Locale: en
URL: https://docs.uniall.ai/models/video/sora-2
Source: site-docs/models/video/sora-2.md
Description: Generate videos with Sora 2 models through UniAll video APIs.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

Sora 2 supports prompt-based video generation with optional reference image input. The source scope includes the UniAll video generation endpoint and an OpenAI-native compatibility page.

## Supported Models

| Model | Notes |
| --- | --- |
| `sora2-landscape-4s` | Landscape output, 4 seconds. |
| `sora2-landscape-8s` | Landscape output, 8 seconds. |
| `sora2-landscape-12s` | Landscape output, 12 seconds. |
| `sora2-portrait-4s` | Portrait output, 4 seconds. |
| `sora2-portrait-8s` | Portrait output, 8 seconds. |
| `sora2-portrait-12s` | Portrait output, 12 seconds. |
| `sora2-pro-720p` | Pro public model, 720p. |
| `sora2-pro-1080p` | Pro public model, 1080p. |
| `sora2-pro-true-1080p` | Pro true-1080p model when enabled. |

## Endpoint

```http
POST /v1/video/generations
GET  /v1/videos/{task_id}
```

The source also includes a native OpenAI-format page for clients that need OpenAI-compatible request formatting.

## Authentication

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## Request Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | Sora 2 model ID. |
| `prompt` | string | Yes | Video prompt. |
| `image_url` | string | No | Public reference image URL. |
| `aspect_ratio` | string | No | `16:9` or `9:16`. |
| `duration` | integer/string | No | Source description lists `4`, `8`, `12`, `16`, or `20`. Model names may already encode duration. |

## Request Example

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora2-portrait-12s",
    "prompt": "A cat running through grass",
    "image_url": "https://example.com/image.jpg"
  }'
```

## Submit Response

```json
{
  "id": "gen_xxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "sora2",
  "status": "queued",
  "progress": 0,
  "created_at": 1770405483,
  "seconds": "12"
}
```

## Task Status And Result

After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow.

## Billing Notes

Sora 2 billing depends on model, duration, orientation, resolution, and whether a Pro model is selected. Use the current model pricing surface and task settlement record as the source of truth.

## Common Errors

- Passing an unsupported Sora 2 model ID.
- Sending a private or expired `image_url`.
- Passing an `aspect_ratio` that conflicts with a landscape or portrait model name.
- Treating a queued task as complete before polling finishes.
- Mixing UniAll task format and native OpenAI format in one request.

## Related Pages

- [Video Generation Overview](/models/video/overview)
- [Wan 2.6 Video Generation](/models/video/wan-2-6)
- [Models](/models)

---

# Create Video Generation Task

Locale: en
URL: https://docs.uniall.ai/models/video/sora-2/create-task
Source: site-docs/models/video/sora-2/create-task.md
Description: Sora 2 create video generation task endpoint.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

## Overview

new sora2 Pro Public Models `sora2-pro-720p`,`sora2-pro-1080p`,`sora2-pro-true-1080p`

## Endpoint


```http
POST /v1/video/generations
```
## Header Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No | | Bearer &#123;your_token&#125; |
## Request Body Parameters

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `model` | string | Yes | Model name | Optional values: sora2-landscape-4s, sora2-landscape-8s, sora2-landscape-12s, sora2-portrait-4s, sora2-portrait-8s, sora2-portrait-12s, sora2-pro-720p, sora2-pro-1080p |
| `prompt` | string | Yes | prompt | |
| `image_url` | string | Yes | reference URL | must be public URLimage URL |
| `aspect_ratio` | string | No | Ratio | "16:9", "9:16" |
| `duration` | string | No | description | 4, 8, 12, 16, 20 |

## Request Examples

### Example 1

```json
{"model": "sora2-portrait-12s",
 "prompt": " ",
 "image_url": "https://example.com/image.jpg" // Optional values}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "sora2-portrait-12s",
 "prompt": " ",
 "image_url": "https://example.com/image.jpg" // Optional values}'
```
## Response Fields

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `id` | string | Yes | task ID | |
| `object` | string | Yes | Task type | |
| `model` | string | Yes | Model name | |
| `status` | string | Yes | Status | |
| `progress` | string | Yes | | |
| `created_at` | string | Yes | Created time | |
| `seconds` | string | Yes | duration | |

## Response Examples

### Example 1

```json
{
  "id": "gen_xxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "sora2",
  "status": "queued",
  "progress": 0,
  "created_at": 1770405483,
  "seconds": "12"
}
```

## Task Status And Result

After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow.

---

# Native OpenAI Format

Locale: en
URL: https://docs.uniall.ai/models/video/sora-2/openai-format
Source: site-docs/models/video/sora-2/openai-format.md
Description: Sora 2 native OpenAI format endpoint.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

## Endpoint


```http
POST /v1/chat/completions
```
## Header Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No | | Bearer &#123;your_token&#125; |
## Request Body Parameters

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `model` | string | Yes | Model name | Optional values: sora2-landscape-4s, sora2-landscape-8s, sora2-landscape-12s, sora2-portrait-4s, sora2-portrait-8s, sora2-portrait-12s |

## Request Examples

### Example 1

```json
// text-to-video
{"model": "sora2-landscape-4s",
 "messages": [{"role": "user",
 "content": " "}],
 "stream": true}
// image-to-video
{"model": "sora2-landscape-4s",
 "messages": [{"role": "user",
 "content": [{"type": "text",
 "text": " "},
 {"type": "image_url",
 "image_url": {"url": "https://example.com/portrait.jpg"}}]}],
 "stream": true}
```

```bash
curl -X POST "{BASE_URL}/v1/chat/completions" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '// text-to-video
{"model": "sora2-landscape-4s",
 "messages": [{"role": "user",
 "content": " "}],
 "stream": true}
// image-to-video
{"model": "sora2-landscape-4s",
 "messages": [{"role": "user",
 "content": [{"type": "text",
 "text": " "},
 {"type": "image_url",
 "image_url": {"url": "https://example.com/portrait.jpg"}}]}],
 "stream": true}'
```
## Response Fields

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |


## Response Examples

### Example 1

```json
{
  "id": "xxxxxxxxxxxxxxxxxxxxx",
  "object": "chat.completion.chunk",
  "created": 1770408254,
  "model": "sora2",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "\n\n✅ **video generation completed! **\n\n**video URL**: https://xxxx.xxxx.cn/xxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.mp4\n**task **: 127 \n"
      },
      "finish_reason": null
    }
  ]
}
```
### Example 2

```json
{
  "id": "chatcmpl-b5e9c8b352cc4dcc81815884ab943",
  "object": "chat.completion.chunk",
  "created": 1770408254,
  "model": "sora2",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "\n🖼️ processing. (50%)"
      },
      "finish_reason": null
    }
  ]
}
```

---

# Veo 3.1

Locale: en
URL: https://docs.uniall.ai/models/video/veo-3-1
Source: site-docs/models/video/veo-3-1.md
Description: Generate videos with Veo 3.1 models through UniAll video APIs.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

Veo 3.1 supports text-to-video, image-to-video, first-last-frame generation, multi-image reference generation, and video extension. Use the public model name to select the resolution and speed tier.

## Supported Models

| Model | Tier |
| --- | --- |
| `veo3.1-video-720p` | Standard 720p. |
| `veo3.1-video-1080p` | Standard 1080p. |
| `veo3.1-video-4k` | Standard 4K. |
| `veo3.1-fast-video-720p` | Fast 720p. |
| `veo3.1-fast-video-1080p` | Fast 1080p. |
| `veo3.1-fast-video-4k` | Fast 4K. |

## Endpoint

```http
POST /v1/video/generations
GET  /v1/videos/{task_id}
```

## Authentication

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## Request Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | Veo 3.1 public model ID. |
| `prompt` | string | Strongly recommended | Main prompt. The schema is lenient, but production requests should include it. |
| `image` | string | Conditional | Single source image URL for image-to-video. |
| `images` | string[] | Conditional | `2` to `3` reference image URLs for multi-image reference generation. |
| `last_image` | string | Conditional | Target last-frame image URL; use with `image`. |
| `video` | string | Conditional | Source video URL for extension. |
| `size` | string | Recommended | Resolution hint, aligned to the selected model tier. |
| `aspect_ratio` | string | No | Text-to-video accepts `16:9` or `9:16`. Image-to-video and extension may not honor it. |
| `duration` | integer | Conditional | Output seconds. Allowed values: `4`, `6`, or `8`. Not used for video extension. |
| `extra_body.generate_audio` | boolean | No | Whether to generate audio; upstream usually defaults to `true`. |
| `extra_body.negative_prompt` | string | No | Content to avoid. |
| `extra_body.seed` | integer | No | Random seed for reproducibility. |

## Text-To-Video Example

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-video-1080p",
    "prompt": "A golden-hour street interview shot, slight handheld movement, natural city ambience, realistic human speech.",
    "size": "1080p",
    "aspect_ratio": "16:9",
    "duration": 8,
    "extra_body": {
      "generate_audio": true,
      "negative_prompt": "watermark, blur",
      "seed": 7
    }
  }'
```

## Image-To-Video Example

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-video-720p",
    "prompt": "A product slowly rotates on a clean studio desk with soft reflected light.",
    "image": "https://example.com/keyframe.png",
    "size": "720p",
    "aspect_ratio": "16:9",
    "duration": 6,
    "extra_body": {
      "generate_audio": false,
      "negative_prompt": "artifacts, camera shake"
    }
  }'
```

## First-Last-Frame Example

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-fast-video-1080p",
    "prompt": "Transition naturally from the first frame to the last frame, preserving subject identity and camera continuity.",
    "image": "https://example.com/start-frame.png",
    "last_image": "https://example.com/end-frame.png",
    "size": "1080p",
    "aspect_ratio": "16:9",
    "duration": 6
  }'
```

## Task Status And Result

After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow.

## Billing Notes

Veo billing depends on model tier, speed tier, resolution, output duration, and audio generation. Use task settlement and current product pricing as the final source.

## Common Errors

- Passing `duration` outside `4`, `6`, or `8`.
- Mismatching `size` with the selected model tier.
- Expecting `aspect_ratio` to be honored for image-to-video or extension requests.
- Sending more than `3` reference images.
- Passing `video` without clarifying the extension use case in the prompt or extra body.

## Related Pages

- [Video Generation Overview](/models/video/overview)
- [Kling Video Generation](/models/video/kling)
- [Vidu Video Generation](/models/video/vidu)

---

# Create Video Generation Task

Locale: en
URL: https://docs.uniall.ai/models/video/veo-3-1/create-task
Source: site-docs/models/video/veo-3-1/create-task.md
Description: Veo 3.1 create video generation task endpoint.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

## Overview

| Public model name | Currently supported video capabilities |
|---|---|
| `veo3.1-video-720p` | text-to-video, single-image-to-video, first-and-last-frame, multi-image-reference video generation, video extension |
| `veo3.1-video-1080p` | text-to-video, single-image-to-video, first-and-last-frame, multi-image-reference video generation, video extension |
| `veo3.1-video-4k` | text-to-video, single-image-to-video, first-and-last-frame, multi-image-reference video generation, video extension |
| `veo3.1-fast-video-720p` | text-to-video, single-image-to-video, first-and-last-frame, video extension |
| `veo3.1-fast-video-1080p` | text-to-video, single-image-to-video, first-and-last-frame, video extension |
| `veo3.1-fast-video-4k` | text-to-video, single-image-to-video, first-and-last-frame, video extension |

## Endpoint


```http
POST /v1/video/generations
```
## Query Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No | | Bearer &#123;your_token&#125; |
## Request Body Parameters

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `model` | string | Yes | Public model name | |
| `prompt` | string | Yes | prompt | Structure Yes Required, recommended to pass |
| `image` | string | Yes | single source image URL | image-to-video |
| `images` | string | Yes | multiple reference images URL list | 2 3 multi-image-reference video generation |
| `last_image` | string | Yes | URL | first-and-last-frame, andimage use |
| `video` | string | Yes | video UR | video extension |
| `size` | string | Yes | resolution | and Public Models |
| `aspect_ratio`| string | Yes | output aspect ratio | text-to-videoallowed values:`16:9`, `9:16`; image-to-video, video extension use, pass |
| `duration`| string | Yes |, | allowed values:`4`, `6`, `8`; video extension use |
| `extra_body` | object | Yes | Field | |

## Request Examples

### text-to-video

```json
{
  "model": "veo3.1-video-1080p",
  "prompt": " camera, camera. ",
  "size": "1080p",
  "aspect_ratio": "16:9",
  "duration": 8,
  "extra_body": {
    "generate_audio": true,
    "negative_prompt": ", blur",
    "seed": 7
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "veo3.1-video-1080p",
 "prompt": " camera, camera. ",
 "size": "1080p",
 "aspect_ratio": "16:9",
 "duration": 8,
 "extra_body": {"generate_audio": true,
 "negative_prompt": ", blur",
 "seed": 7}}'
```
### single-image-to-video

```json
{
  "model": "veo3.1-video-720p",
  "prompt": ", and. ",
  "image": "https://example.com/keyframe.png",
  "size": "720p",
  "aspect_ratio": "16:9",
  "duration": 6,
  "extra_body": {
    "generate_audio": false,
    "negative_prompt": "artifacts, "
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "veo3.1-video-720p",
 "prompt": ", and. ",
 "image": "https://example.com/keyframe.png",
 "size": "720p",
 "aspect_ratio": "16:9",
 "duration": 6,
 "extra_body": {"generate_audio": false,
 "negative_prompt": "artifacts, "}}'
```
### first-and-last-frame

```json
{
  "model": "veo3.1-fast-video-1080p",
  "prompt": ", subject, cameralanguage. ",
  "image": "https://example.com/start-frame.png",
  "last_image": "https://example.com/end-frame.png",
  "size": "1080p",
  "aspect_ratio": "16:9",
  "duration": 6,
  "extra_body": {
    "generate_audio": true
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "veo3.1-fast-video-1080p",
 "prompt": ", subject, cameralanguage. ",
 "image": "https://example.com/start-frame.png",
 "last_image": "https://example.com/end-frame.png",
 "size": "1080p",
 "aspect_ratio": "16:9",
 "duration": 6,
 "extra_body": {"generate_audio": true}}'
```
### reference video

```json
{
  "model": "veo3.1-video-1080p",
  "prompt": ", and. ",
  "images": [
    "https://example.com/ref-1.png",
    "https://example.com/ref-2.png"
  ],
  "size": "1080p",
  "aspect_ratio": "9:16",
  "duration": 6,
  "extra_body": {
    "generate_audio": true,
    "seed": 11
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "veo3.1-video-1080p",
 "prompt": ", and. ",
 "images": ["https://example.com/ref-1.png",
 "https://example.com/ref-2.png"],
 "size": "1080p",
 "aspect_ratio": "9:16",
 "duration": 6,
 "extra_body": {"generate_audio": true,
 "seed": 11}}'
```
### video extension

```json
{
  "model": "veo3.1-video-720p",
  "prompt": " video action, scenariostyle. ",
  "video": "https://example.com/source.mp4",
  "size": "720p",
  "duration": 6,
  "extra_body": {
    "negative_prompt": ", ",
    "seed": 9
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "veo3.1-video-720p",
 "prompt": " video action, scenariostyle. ",
 "video": "https://example.com/source.mp4",
 "size": "720p",
 "duration": 6,
 "extra_body": {"negative_prompt": ", ",
 "seed": 9}}'
```
## Response Fields

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |


## Response Examples

### Example 1

```json
{}
```

## Task Status And Result

After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow.

---

# Vidu Q3

Locale: en
URL: https://docs.uniall.ai/models/video/vidu
Source: site-docs/models/video/vidu.md
Description: Create text, single-image, first-and-last-frame, and multi-reference videos with the Vidu Q3 series through UniAll.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

Updated: 2026-08-04

## Overview

Use the Vidu Q3 series through two stable public model IDs. Select the output resolution with the top-level `resolution` parameter instead of encoding it in the model name.

| Public Model | Series | Text To Video | Single Image | First And Last Frame | Multiple References |
| --- | --- | --- | --- | --- | --- |
| `viduq3p` | Q3 Pro | Supported | Supported | Supported | 1 to 4 images |
| `viduq3t` | Q3 Turbo | Supported | Supported | Supported | 1 to 4 images |

Both models support `540p`, `720p`, and `1080p`. These are the only public Vidu Q3 model IDs.

## When To Use It

Use Vidu Q3 when you need to:

- create a video from a text prompt;
- animate one publicly accessible image;
- interpolate between a first frame and a last frame;
- guide generation with 1 to 4 reference images.

Clients only select a public model and request parameters. Do not send channel names, upstream model IDs, upstream task fields, or routing controls.

## Endpoints

Use these endpoints for new integrations:

| Purpose | Method | Path |
| --- | --- | --- |
| Create a video task | `POST` | `/v1/videos` |
| Query a video task | `GET` | `/v1/videos/{task_id}` |
| Download the video | `GET` | `/v1/videos/{task_id}/content` |

The following compatibility endpoints remain available:

| Purpose | Method | Path |
| --- | --- | --- |
| Create a video task | `POST` | `/v1/videos/generations` |
| Query a video task | `GET` | `/v1/videos/generations/{task_id}` |
| Create a video task | `POST` | `/v1/video/generations` |
| Query a video task | `GET` | `/v1/video/generations/{task_id}` |

Prefer `/v1/videos` for all new integrations.

## Authentication

Every request requires a UniAll Bearer token:

```http
Authorization: Bearer sk-***
```

Task creation also requires:

```http
Content-Type: application/json
```

## Request Body Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | `viduq3p` or `viduq3t`. |
| `prompt` | string | Yes | Video generation prompt. |
| `duration` | integer | Yes | Output duration from `1` to `16` seconds. |
| `aspect_ratio` | string | No | `16:9`, `9:16`, `3:4`, `4:3`, or `1:1`. |
| `image` | string | Conditional | Public HTTP(S) URL for a single image or the first frame. |
| `last_image` | string | Conditional | Public HTTP(S) URL for the last frame; requires `image`. |
| `reference_image_urls` | string[] | Conditional | 1 to 4 public HTTP(S) image URLs for reference generation. |
| `resolution` | string | Yes | `540p`, `720p`, or `1080p`. |
| `audio` | boolean | No | Whether to generate audio. |
| `bgm` | boolean | No | Background music control for text-to-video generation. |
| `seed` | integer | No | Random seed. |

Choose input fields according to the generation mode:

| Mode | Input Fields |
| --- | --- |
| Text to video | `prompt` |
| Single image | `prompt` + `image` |
| First and last frame | `prompt` + `image` + `last_image` |
| Multiple references | `prompt` + `reference_image_urls` |

Follow these validation rules:

- Pass top-level `resolution` on every request.
- Do not combine `image` with `reference_image_urls`.
- Do not pass `last_image` without `image`.
- Do not use `images` or `image_urls` for first-and-last-frame or reference generation.
- Pass `resolution`, `audio`, `bgm`, and `seed` at the top level, not inside `extra_body`.
- `size` is not an alias for `resolution`.

## Request Examples

### Text To Video

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3p",
    "prompt": "A cinematic aerial shot over a futuristic coastal city at sunrise, soft light, slow camera push-in.",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "audio": false,
    "bgm": false,
    "seed": 42
  }'
```

### Single Image To Video

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3t",
    "prompt": "The person slowly raises their head and looks at the camera while the camera gently moves forward.",
    "image": "https://example.com/source.png",
    "duration": 5,
    "aspect_ratio": "9:16",
    "resolution": "540p",
    "audio": false,
    "seed": 42
  }'
```

### First And Last Frame

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3p",
    "prompt": "The person turns naturally from a front view to a side view while identity and motion remain consistent.",
    "image": "https://example.com/head.png",
    "last_image": "https://example.com/tail.png",
    "duration": 6,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "audio": false,
    "seed": 42
  }'
```

### Multiple Reference Images

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3p",
    "prompt": "A @Image1 walking through a beach in the visual style of @Image2",
    "reference_image_urls": [
      "https://example.com/ref-1.png",
      "https://example.com/ref-2.png"
    ],
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "audio": false,
    "seed": 42
  }'
```

Both public models accept `reference_image_urls`. Reference prompts can use `@Image1`, `@Image2`, and subsequent markers in array order.

## Response Examples

### Task Created

Save `id` or the compatible `task_id` value for later queries:

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "viduq3p",
  "status": "queued",
  "progress": 0,
  "created_at": 1785772800
}
```

Public responses do not include channel identifiers, upstream task IDs, credentials, or raw upstream payloads.

## Task Status And Result

After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow.

## Billing Notes

Billing depends on the public model, requested `resolution`, and actual output duration. The model ID does not carry a resolution or time-based billing tier.

The current Baidu VOD/BV channel reference for normal-time text-to-video, single-image-to-video, and first-and-last-frame requests is:

| Public Model | `540p` | `720p` | `1080p` |
| --- | ---: | ---: | ---: |
| `viduq3p` (Q3 Pro) | CNY 0.28125/second | CNY 0.625/second | CNY 0.75/second |
| `viduq3t` (Q3 Turbo) | CNY 0.21875/second | CNY 0.375/second | CNY 0.40625/second |

Total channel consumption is the rate multiplied by the actual output duration. Reference-image requests may use a different eligible route. Treat these values as the current channel reference, and use the UniAll model page and consumption log as the source of the final user-facing price and settlement.

## Common Errors

Requests are rejected before task creation when they:

- use a model ID other than `viduq3p` or `viduq3t`;
- omit `resolution` or pass a value other than `540p`, `720p`, or `1080p`;
- use `size` instead of `resolution`;
- omit `duration` or pass a value outside `1` to `16`;
- use an unsupported aspect ratio such as `21:9` or `1920x1080`;
- pass an empty `reference_image_urls` array or more than 4 references;
- combine `image` with `reference_image_urls`, or pass `last_image` alone;
- use an image URL that the service cannot access publicly;
- place supported top-level controls inside `extra_body`.

## Related Pages

- [Video Generation Overview](/models/video/overview)
- [Models](/models)

---

# Wan 2.6

Locale: en
URL: https://docs.uniall.ai/models/video/wan-2-6
Source: site-docs/models/video/wan-2-6.md
Description: Generate videos with Wan 2.6 models through UniAll video APIs.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

Wan 2.6 covers text-to-video, image-to-video, and reference-to-video model families. The source scope also includes a duration reference table for the Wan 2.6 public models.

## Supported Models

| Model | Type | Duration rules |
| --- | --- | --- |
| `wan2.6-video-720p` | Text-to-video / image-to-video | Required; `5`, `10`, or `15`. |
| `wan2.6-video-1080p` | Text-to-video / image-to-video | Required; `5`, `10`, or `15`. |
| `wan2.6-i2v-flash-720p-audio` | Image-to-video with audio | Required; any integer from `5` to `15`. |
| `wan2.6-i2v-flash-720p-silent` | Image-to-video silent | Required; any integer from `5` to `15`. |
| `wan2.6-i2v-flash-1080p-audio` | Image-to-video with audio | Required; any integer from `5` to `15`. |
| `wan2.6-i2v-flash-1080p-silent` | Image-to-video silent | Required; any integer from `5` to `15`. |
| `wan2.6-r2v-720p` | Reference-to-video | Required; see account model configuration. |
| `wan2.6-r2v-1080p` | Reference-to-video | Required; see account model configuration. |
| `wan2.6-r2v-flash-720p-audio` | Reference-to-video with audio | Required; see account model configuration. |
| `wan2.6-r2v-flash-720p-silent` | Reference-to-video silent | Required; see account model configuration. |
| `wan2.6-r2v-flash-1080p-audio` | Reference-to-video with audio | Required; see account model configuration. |
| `wan2.6-r2v-flash-1080p-silent` | Reference-to-video silent | Required; see account model configuration. |

## Endpoint

```http
POST /v1/video/generations
GET  /v1/videos/{task_id}
```

## Authentication

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## Request Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | Wan 2.6 model ID. |
| `prompt` | string | Yes | Prompt. |
| `image` | string | Conditional | Reference image for image-to-video. |
| `images` | string[] | Conditional | Reference images for R2V models. |
| `videos` | string[] | Conditional | Reference videos for R2V models. |
| `duration` | integer | Yes | See the supported model table. |
| `size` | string | No | Output size. Text-to-video can use this to choose landscape or portrait. Image-to-video follows the reference image orientation. |
| `extra_body.negative_prompt` | string | No | Content to avoid. |
| `extra_body.shot_type` | string | No | `single` or `multi`. |
| `extra_body.seed` | integer | No | `-1` for random; fixed value for reproducibility. |
| `extra_body.audio` | string | No | Public audio URL. |
| `extra_body.enable_prompt_expansion` | boolean | No | Prompt expansion switch for R2V models. |

Common `size` values include `1280*720`, `720*1280`, `1920*1080`, and `1080*1920`.

## Text-To-Video Example

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-video-1080p",
    "prompt": "sunrise",
    "duration": 5,
    "size": "1080*1920",
    "extra_body": {
      "negative_prompt": "blur, watermark",
      "shot_type": "multi",
      "seed": -1
    }
  }'
```

## Reference Video Example

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-r2v-flash-720p-audio",
    "prompt": "Keep the same subject identity and cinematic style, generate a faster-paced new shot.",
    "videos": [
      "https://example.com/reference-shot-1.mp4"
    ],
    "size": "1280*720",
    "duration": 5,
    "extra_body": {
      "negative_prompt": "watermark, blur, flicker",
      "audio": "https://example.com/guide-audio.mp3",
      "shot_type": "single",
      "enable_prompt_expansion": false,
      "seed": -1
    }
  }'
```

## Multi-Image Reference Example

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-r2v-flash-1080p-silent",
    "prompt": "Keep the same product identity and style, generate a clean marketing video.",
    "images": [
      "https://example.com/ref-1.png",
      "https://example.com/ref-2.png"
    ],
    "size": "1920*1080",
    "duration": 10,
    "extra_body": {
      "negative_prompt": "watermark, blur",
      "shot_type": "multi",
      "enable_prompt_expansion": true,
      "seed": 42
    }
  }'
```

## Task Status And Result

After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow.

## Billing Notes

Wan 2.6 billing depends on model family, output resolution, duration, audio mode, and whether the task is text/image/video reference generation. Use settlement records for final accounting.

## Common Errors

- Using a duration value outside the selected model's allowed range.
- Expecting `size` to control portrait or landscape for image-to-video; image orientation follows the reference image.
- Passing private media URLs.
- Using R2V fields with a non-R2V model.
- Using `audio` with a silent model.

## Related Pages

- [Video Generation Overview](/models/video/overview)
- [Vidu Video Generation](/models/video/vidu)
- [Sora 2 Video Generation](/models/video/sora-2)

---

# Create Video Generation Task

Locale: en
URL: https://docs.uniall.ai/models/video/wan-2-6/create-task
Source: site-docs/models/video/wan-2-6/create-task.md
Description: Wan 2.6 create video generation task endpoint.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

## Endpoint


```http
POST /v1/video/generations
```
## Header Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No | | Bearer &#123;your_token&#125; |
## Request Body Parameters

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `model` | string | Yes | Model name | "wan2.6-video-720p", "wan2.6-video-1080p" |
| `prompt` | string | Yes | prompt | |
| `image` | string | Yes | reference | |
| `duration` | string | Yes | duration | |
| `size` | string | Yes | videosize | "1280*720", "720*1280", "1920*1080", "1080*1920", Note: text-to-video Optional valuessizecontrolLandscape Portrait, image-to-video sizeParameters, pass in, Yes videoLandscape Portrait reference |
| `extra_body` | object | Yes | | |

## Request Examples

### Example 1

```json
{
  "model": "wan2.6-video-1080p",
  "prompt": " ",
  "duration": 5,
  "size": "1080*1920",
  "extra_body": {
    "negative_prompt": "do not blur, do not ",
    "shot_type": "multi",
    "seed": -1
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "wan2.6-video-1080p",
 "prompt": " ",
 "duration": 5,
 "size": "1080*1920",
 "extra_body": {"negative_prompt": "do not blur, do not ",
 "shot_type": "multi",
 "seed": -1}}'
```
## Response Fields

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |


## Response Examples

### Success

```json
{
  "id": "task_xxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "wan2.6-video-1080p",
  "status": "in_progress",
  "progress": 5,
  "created_at": 1773984104
}
```

## Task Status And Result

After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow.

---

# Wan Model Duration Reference

Locale: en
URL: https://docs.uniall.ai/models/video/wan-2-6/duration-table
Source: site-docs/models/video/wan-2-6/duration-table.md
Description: Wan model duration source reference.

## WAN 2.6

| Public Models | Type | duration | allowed values |
|---|---|---|---|
| `wan2.6-video-720p`| text-to-video / image-to-video | Required |`5`, `10`, `15` |
| `wan2.6-video-1080p`| text-to-video / image-to-video | Required |`5`, `10`, `15` |
| `wan2.6-i2v-flash-720p-audio`| image-to-video audio | Required |`5` `15` any integer |
| `wan2.6-i2v-flash-720p-silent`| image-to-video silent | Required |`5` `15` any integer |
| `wan2.6-i2v-flash-1080p-audio`| image-to-video audio | Required |`5` `15` any integer |
| `wan2.6-i2v-flash-1080p-silent`| image-to-video silent | Required |`5` `15` any integer |
| `wan2.6-r2v-720p`| reference video | Required |`5`, `10` |
| `wan2.6-r2v-1080p`| reference video | Required |`5`, `10` |
| `wan2.6-r2v-flash-720p-audio`| reference video audio | Required |`5`, `10` |
| `wan2.6-r2v-flash-720p-silent`| reference video silent | Required |`5`, `10` |
| `wan2.6-r2v-flash-1080p-audio`| reference video audio | Required |`5`, `10` |
| `wan2.6-r2v-flash-1080p-silent`| reference video silent | Required |`5`, `10` |


##

- `wan2.6-video-*`: `5 / 10 / 15`
- `wan2.6-i2v-flash-*`: `5~15` any integer
- `wan2.6-r2v-*`: `5 / 10`
- `wan2.6-r2v-flash-*`: `5 / 10`

---

# Wan 2.6 R2V Create Video Task

Locale: en
URL: https://docs.uniall.ai/models/video/wan-2-6/r2v-create-task
Source: site-docs/models/video/wan-2-6/r2v-create-task.md
Description: Wan 2.6 R2V create video task endpoint.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

## Endpoint


```http
POST /v1/video/generations
```
## Request Body Parameters

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `model` | string | No | Example field | Appears in a request example; no separate field description is provided. |
| `prompt` | string | No | Example field | Appears in a request example; no separate field description is provided. |
| `videos` | array | No | Example field | Appears in a request example; no separate field description is provided. |
| `size` | string | No | Example field | Appears in a request example; no separate field description is provided. |
| `duration` | number | No | Example field | Appears in a request example; no separate field description is provided. |
| `extra_body` | object | No | Example field | Appears in a request example; no separate field description is provided. |
| `images` | array | No | Example field | Appears in a request example; no separate field description is provided. |

## Request Examples

### Example 1: videoreference

```json
{
  "model": "wan2.6-r2v-flash-720p-audio",
  "prompt": " subject and style, generate a newcamera. ",
  "videos": [
    "https://example.com/reference-shot-1.mp4"
  ],
  "size": "1280*720",
  "duration": 5,
  "extra_body": {
    "negative_prompt": "watermark, blur, flicker",
    "audio": "https://example.com/guide-audio.mp3",
    "shot_type": "single",
    "enable_prompt_expansion": false,
    "seed": -1
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "wan2.6-r2v-flash-720p-audio",
 "prompt": " subject and style, generate a newcamera. ",
 "videos": ["https://example.com/reference-shot-1.mp4"],
 "size": "1280*720",
 "duration": 5,
 "extra_body": {"negative_prompt": "watermark, blur, flicker",
 "audio": "https://example.com/guide-audio.mp3",
 "shot_type": "single",
 "enable_prompt_expansion": false,
 "seed": -1}}'
```
### Example 2: reference

```json
{
  "model": "wan2.6-r2v-flash-1080p-silent",
  "prompt": " andstyle, generate a video. ",
  "images": [
    "https://example.com/ref-1.png",
    "https://example.com/ref-2.png"
  ],
  "size": "1920*1080",
  "duration": 10,
  "extra_body": {
    "negative_prompt": "watermark, blur",
    "shot_type": "multi",
    "enable_prompt_expansion": true,
    "seed": 42
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "wan2.6-r2v-flash-1080p-silent",
 "prompt": " andstyle, generate a video. ",
 "images": ["https://example.com/ref-1.png",
 "https://example.com/ref-2.png"],
 "size": "1920*1080",
 "duration": 10,
 "extra_body": {"negative_prompt": "watermark, blur",
 "shot_type": "multi",
 "enable_prompt_expansion": true,
 "seed": 42}}'
```
## Response Fields

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |


## Response Examples

### Example 1

```json
{}
```

## Task Status And Result

After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow.

---

# Wan 2.2 Animate Video Editing

Locale: en
URL: https://docs.uniall.ai/models/video/wan-2-6/wan-2-2-animate
Source: site-docs/models/video/wan-2-6/wan-2-2-animate.md
Description: Wan 2.2 Animate video editing endpoint.

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

## Overview

 supports mode:

- `animate`
 - video action, Input image orsubject
- `replace`
 - Input image orsubject, video subject:

- `animate` "action / action "
- `replace` "video / "

## Endpoint


```http
POST /v1/video/generations
```
## Header Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No | | Bearer &#123;your_token&#125; |
## Request Body Parameters

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `model`| string | Yes | Public model name | use `wan2.2-animate-480p` or `wan2.2-animate-720p` |
| `prompt` | string | Yes | prompt | Optional values, recommended style, scenario, camera |
| `image` | string | Yes | reference URL | Recommended \| image \| can onlyone |
| `video` | string | Yes | video URL | Recommended \| actionor video \| can onlya |
| `duration` | string | Yes |, | Required |
| `mode`| string | Yes | mode | allowed values:`animate`, `replace` (Field, not inextra_body pass) |
| `seed` | string | Yes | random seed | random seed, (Field, not inextra_body pass) |
| `extra_body` | object | Yes | | |

## Request Examples

### Example

```json
{
  "model": "string",
  "prompt": "string",
  "image": "string",
  "video": "string",
  "duration": "string",
  "mode": "string",
  "seed": "string",
  "extra_body": {
    "mode": "string",
    "seed": "string"
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "string",
 "prompt": "string",
 "image": "string",
 "video": "string",
 "duration": "string",
 "mode": "string",
 "seed": "string",
 "extra_body": {"mode": "string",
 "seed": "string"}}'
```
## Response Fields

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |


## Response Examples

### Example 1

```json
{}
```

## Task Status And Result

After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow.

---

# 文档概览

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/overview.md
Description: UniAll 开发者文档范围、API 风格和选定模型文档结构。

UniAll Docs 是从当前 Apifox 文档范围中选定 API 和模型页面后整理出的开发者参考。来源菜单只作为内容清单使用，新站点会统一名称、路由、示例和页面结构，让文档呈现为一个完整的 UniAll 产品文档体系。

当前公开文档会保持收敛，只覆盖已确认范围内的余额、模型列表、图像、视频、语音音乐和数字人页面。独立的快速开始、认证说明、完整计费政策、错误码全集、更新日志和自动生成 API Reference 不属于本阶段。

## 当前包含的文档

| 范围 | 当前页面 | 主要用途 |
| --- | --- | --- |
| 账户 | [查询余额](/zh-CN/balance) | 在提交任务前确认账户和 API Key 额度。 |
| 模型索引 | [模型列表](/zh-CN/models) | 按能力组织模型文档，并说明模型列表接口。 |
| 图像生成 | [通用异步图像生成](/zh-CN/models/image/async-image-generation)、Seedream、GPT-Image-2、Nano 系列 | 按模型页面选择异步任务或同步图像接口。 |
| 视频生成 | Happy-Horse、Seedance 2.0、[Grok Imagine](/zh-CN/models/video/grok-imagine)、Veo 3.1、Vidu、Kling、Wan 2.6、Sora 2 | 提交视频任务、查询状态并获取完成后的视频。 |
| 语音与音乐 | 音乐生成、语音合成 | 使用模型专属字段生成音乐或语音。 |
| 数字人 | 数字人口播 | 生成数字人口播视频。 |

## API 风格

大多数模型页面使用任务流程：

1. 使用 `Authorization: Bearer sk-***` 提交任务。
2. 保存返回的任务 ID。
3. 每 2 到 5 秒轮询任务状态。
4. 当任务进入 `succeeded`、`completed` 或 `failed` 等终态时停止轮询。
5. 使用返回的结果 URL 或内容接口下载最终资产。

余额和模型列表属于同步 API 概念页，会立即返回结果，不需要轮询。

## 通用约定

| 约定 | 规则 |
| --- | --- |
| Base URL | `https://api.uniall.ai`；示例中的 `{BASE_URL}` 均表示该地址。 |
| 认证 | 除非页面说明兼容格式专属 Header，否则使用 `Authorization: Bearer sk-***`。 |
| 请求示例 | 优先使用 `curl`。 |
| 模型 ID | JSON 中使用精确模型 ID，例如 `grok-imagine` 和 `gpt-image-2`。 |
| 结果 URL | 返回的 URL 视为生成资产，除非产品协议另有说明，不应默认永久有效。 |
| 计费 | 页面内说明影响费用的维度，精确价格以当前产品价格页为准。 |

## 语言和 AI 可读文档

英文是默认语言，路径为 `/`。中文路径为 `/zh-CN/`。代码示例、JSON key、接口路径和模型 ID 在两种语言中保持一致。

站点同时发布 AI 可读索引：

- [`/llms.txt`](/llms.txt)
- [`/llms-full.txt`](/llms-full.txt)

当 agent 或外部 AI 工具需要快速理解当前文档范围时，可以使用这两个文件。

## 相关页面

- [查询余额](/zh-CN/balance)
- [模型列表](/zh-CN/models)
- [通用异步图像生成](/zh-CN/models/image/async-image-generation)
- [Grok Imagine 视频生成](/zh-CN/models/video/grok-imagine)

---

# 查询余额

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/balance
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/balance.md
Description: 查询账户余额和额度使用情况。

## 1. 接口说明

该接口用于通过普通 API Key 查询：

- 当前 API Key 所属的用户 ID
- 用户账户余额
- 用户余额按站点配置换算后的展示金额
- 当前这把 API Key 的额度信息

该接口使用普通 `sk-...` API Key 调用，不需要用户登录态。

---

## 2. 请求信息

| 项目 | 内容 |
| --- | --- |
| 请求方法 | `GET` |
| 请求路径 | `/api/usage/balance` |
| 鉴权方式 | `Authorization: Bearer sk-xxx` |
| Content-Type | 无请求体，可不传 |

---

## 3. 请求示例

```bash
curl -X GET "https://api.aijisu.cn/api/usage/balance" \
  -H "Authorization: Bearer sk-your-api-key"
```

---

## 4. 成功响应示例

```json
{
  "success": true,
  "message": "",
  "data": {
    "object": "api_key_balance",
    "user_id": 1,
    "balance": {
      "quota": 1000000,
      "amount": 14.6,
      "display_amount": "¥14.60",
      "quota_per_unit": 500000,
      "quota_display_type": "CNY",
      "currency_symbol": "¥",
      "exchange_rate": 7.3
    },
    "token": {
      "id": 12,
      "name": "my-key",
      "remain_quota": 100000,
      "used_quota": 5000,
      "total_quota": 105000,
      "unlimited_quota": false,
      "expired_time": -1,
      "status": 1,
      "model_limits_enabled": false,
      "model_limits": {}
    }
  }
}
```

---

## 5. 响应参数说明

### 5.1 顶层参数

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `success` | boolean | 请求是否成功 |
| `message` | string | 响应消息，成功时通常为空字符串 |
| `data` | object | 响应数据 |

### 5.2 `data` 参数

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `data.object` | string | 对象类型，固定为 `api_key_balance` |
| `data.user_id` | number | 当前 API Key 所属的用户 ID |
| `data.balance` | object | 用户账户余额信息 |
| `data.token` | object | 当前 API Key 的额度信息 |

### 5.3 `data.balance` 参数

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `data.balance.quota` | number | 用户账户原始额度，系统内部额度单位 |
| `data.balance.amount` | number | 按站点展示配置换算后的余额金额 |
| `data.balance.display_amount` | string | 格式化后的展示金额，通常包含货币符号 |
| `data.balance.quota_per_unit` | number | 额度换算单位，例如 `500000` 表示 `500000 quota = 1 USD` |
| `data.balance.quota_display_type` | string | 余额展示类型，可能值：`USD`、`CNY`、`CUSTOM`、`TOKENS` |
| `data.balance.currency_symbol` | string | 当前展示货币符号，例如 `$`、`¥`；当展示类型为 `TOKENS` 时为空字符串 |
| `data.balance.exchange_rate` | number | 当前展示币种使用的汇率；`USD` 通常为 `1`，`CNY` 为人民币汇率，`CUSTOM` 为自定义汇率 |

### 5.4 `data.token` 参数

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `data.token.id` | number | 当前 API Key 的 ID |
| `data.token.name` | string | 当前 API Key 的名称 |
| `data.token.remain_quota` | number | 当前 API Key 剩余额度 |
| `data.token.used_quota` | number | 当前 API Key 已使用额度 |
| `data.token.total_quota` | number | 当前 API Key 总额度，计算方式为 `remain_quota + used_quota` |
| `data.token.unlimited_quota` | boolean | 当前 API Key 是否为无限额度 |
| `data.token.expired_time` | number | 当前 API Key 过期时间戳；`-1` 表示不过期 |
| `data.token.status` | number | 当前 API Key 状态；`1` 表示启用 |
| `data.token.model_limits_enabled` | boolean | 当前 API Key 是否启用模型限制 |
| `data.token.model_limits` | object | 当前 API Key 的模型限制配置；未限制时通常为空对象 `{}` |

---

---

## 6. 错误响应

### 6.1 未传 API Key

HTTP 状态码：`401`

```json
{
  "success": false,
  "message": "Token not provided"
}
```

### 6.2 API Key 不存在或无效

HTTP 状态码：`401`

```json
{
  "success": false,
  "message": "Invalid token"
}
```

### 6.3 API Key 已禁用

HTTP 状态码：`403`

```json
{
  "success": false,
  "message": "Token invalid"
}
```

---

## 7. 调用注意事项

- 必须使用 `Authorization: Bearer sk-xxx` 传入 API Key。
- 返回的是 API Key 所属用户的账户余额，不是上游渠道余额。
- 接口不会返回原始 API Key 字符串。
- 已禁用的 API Key 不能查询余额。
- API Key 已过期或额度耗尽时，仍可查询余额，只要 Key 未禁用且用户未被封禁。
- `amount` 和 `display_amount` 会根据站点当前余额展示配置动态变化。

---

# 模型列表

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/index.md
Description: 按能力分类的 UniAll 模型文档入口，并说明模型列表接口。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

模型列表是当前 UniAll 选定模型文档的统一入口。这里按能力组织页面，而不是沿用原始 Apifox 菜单顺序。

当客户端需要在运行时发现当前 API Key 可用的模型时，可以调用模型列表接口。

## 能力分类

| 分类 | 页面 | 常用接口 |
| --- | --- | --- |
| 图像生成 | 通用异步图像生成、Seedream、Seedream 5.0 Pro、GPT-Image-2、GPT-Image-2.5、Nano 系列、Kling | `POST /v1/images/tasks`、`POST /v1/images/generations` 或 `POST /v1/images/edits` |
| 视频生成 | Happy Horse、Seedance 2.0、Seedance 2.5、Grok Imagine、Veo 3.1、Gemini Omni Flash Preview、Vidu Q3、Hailuo、Kling、Wan 2.6、Sora 2 | `POST /v1/video/generations`、`POST /v1/videos` 或 `POST /v1beta/interactions` |
| 语音与音乐 | 音乐生成、语音合成 | 模型专属音频接口 |
| 数字人 | 数字人口播 | 模型专属数字人视频接口 |

## Model List Endpoint

```http
GET /v1/models
```

该接口返回当前模型列表。UniAll 会根据请求 Header 返回不同兼容格式：

| 请求风格 | 判断规则 | 响应格式 |
| --- | --- | --- |
| OpenAI 兼容 | 默认请求风格 | OpenAI 模型列表 |
| Anthropic 兼容 | 同时包含 `x-api-key` 和 `anthropic-version` | Anthropic 风格模型列表 |
| Gemini 兼容 | 包含 `x-goog-api-key` Header 或 `key` 查询参数 | Gemini 风格模型列表 |

在当前文档范围内，规范化页面重点覆盖已选定的图像、视频、语音音乐和数字人能力。

## Required Headers

```http
Authorization: Bearer sk-***
```

兼容格式客户端可以在对应格式文档允许时使用原生认证 Header。

## Request Example

```bash
curl "{BASE_URL}/v1/models" \
  -H "Authorization: Bearer sk-***"
```

## Response Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "grok-imagine",
      "object": "model",
      "created": 0,
      "owned_by": "uniall"
    },
    {
      "id": "gpt-image-2.5-flare",
      "object": "model",
      "created": 0,
      "owned_by": "uniall"
    },
    {
      "id": "gpt-image-2",
      "object": "model",
      "created": 0,
      "owned_by": "uniall"
    }
  ]
}
```

## Response Fields

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `object` | string | 列表对象标记。 |
| `data` | array | 可用模型记录。 |
| `data[].id` | string | API 请求中使用的模型 ID。 |
| `data[].object` | string | 模型记录对象类型。 |
| `data[].created` | number | 创建时间戳。部分兼容响应可能使用 `0`。 |
| `data[].owned_by` | string | 所属方或供应商标签。 |

## Selection Guidance

- 图像生成或图像编辑任务使用 [通用异步图像生成](/zh-CN/models/image/async-image-generation)。
- 使用 [GPT-Image-2.5](/zh-CN/models/image/gpt-image-2-5) 调用 GPT Image 2.5 的同步生成和编辑接口。
- 当模型 ID 为 `seedream-5.0-pro` 时，使用 [Seedream 5.0 Pro 图像生成](/zh-CN/models/image/seedream-5-0-pro)。
- 当模型 ID 为 `seedance2.5` 时，使用 [Seedance 2.5](/zh-CN/models/video/seedance-2-5)。
- 当模型 ID 为 `grok-imagine` 时，使用 [Grok Imagine 视频生成](/zh-CN/models/video/grok-imagine)。
- 当模型 ID 为 `gemini-omni-flash-preview` 时，使用 [Gemini Omni Flash Preview 视频生成](/zh-CN/models/video/gemini-omni-flash-preview)。
- 当模型 ID 为 `hailuo-02`、`hailuo-2.3` 或 `hailuo-2.3-fast` 时，使用 [Hailuo 视频生成](/zh-CN/models/video/hailuo)。
- 使用 [Kling 图片](/zh-CN/models/image/kling)调用 `kling-v3`、`kling-v3-omni` 或 `kling-image-o1` 图片任务。
- 使用 [Kling 视频](/zh-CN/models/video/kling)调用版本级可灵视频模型；`operation: avatar` 使用[数字人口播](/zh-CN/models/avatar/digital-human)。
- 能力专属页面会说明模型字段、计费说明和任务生命周期。
- `/v1/models` 适合运行时发现模型，不应作为唯一集成规则来源。

## Common Errors

| HTTP 状态 | 含义 |
| --- | --- |
| `401` | 缺少认证或认证无效。 |
| `403` | 当前 API Key 已禁用，或没有访问模型列表权限。 |

## Related Pages

- [文档概览](/zh-CN/)
- [查询余额](/zh-CN/balance)
- [通用异步图像生成](/zh-CN/models/image/async-image-generation)
- [Seedream 5.0 Pro 图像生成](/zh-CN/models/image/seedream-5-0-pro)
- [Seedance 2.5](/zh-CN/models/video/seedance-2-5)
- [Grok Imagine 视频生成](/zh-CN/models/video/grok-imagine)
- [Gemini Omni Flash Preview 视频生成](/zh-CN/models/video/gemini-omni-flash-preview)
- [Hailuo 视频生成](/zh-CN/models/video/hailuo)
- [Kling 图片](/zh-CN/models/image/kling)
- [Kling 视频](/zh-CN/models/video/kling)
- [数字人口播](/zh-CN/models/avatar/digital-human)

---

# 音乐生成

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/audio/music-generation
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/audio/music-generation.md
Description: MiniMax Music 音乐生成来源文档。

本文档介绍如何在 aijisu 中使用 MiniMax Music 2.6 异步音乐生成接口。

当前支持模型：

| 模型名称 | 类型 | 适合场景 | 计费方式 |
|---|---|---|---|
| `minimax-music-2.6` | 音乐生成 | 广告音乐、短视频 BGM、播客开场、产品宣传曲、纯音乐氛围铺底 | 按输出音频条数计费 |

接口采用异步任务模式：

| 操作 | 方法 | 路径 |
|---|---|---|
| 提交音乐任务 | `POST` | `/v1/audio/tasks` |
| 查询音乐任务 | `GET` | `/v1/audio/tasks/{task_id}` |

---

## 1. 通用鉴权

所有接口都需要在请求头中携带 API Key：

```http
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
Content-Type: application/json
```

示例域名：

```uri
https://api.xxx.xx
```

---

## 2. 模型简介

`minimax-music-2.6` 用于根据音乐描述和歌词生成音乐音频。它适合生成短视频配乐、广告歌曲、品牌宣传曲、播客片头、课程开场音乐、情绪氛围 BGM 等。

模型支持两类常见方式：

- 有歌词歌曲：传 `prompt` + `lyrics`
- 纯音乐：传 `prompt` + `is_instrumental: true`

---

## 3. 提交音乐任务

```http
POST https://api.xxx.xx/v1/audio/tasks
```

### 3.1 请求参数

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | 是 | 固定为 `minimax-music-2.6` |
| `prompt` | string | 是 | 音乐描述，建议包含风格、情绪、速度、用途、乐器、声音质感 |
| `lyrics` | string | 否 | 歌词。非纯音乐时建议提供 |
| `lyrics_optimizer` | boolean | 否 | 是否优化歌词 |
| `is_instrumental` | boolean | 否 | 是否生成纯音乐 |
| `audio_setting` | object | 否 | 音频设置对象，按平台开放能力透传 |

### 3.2 提交响应示例

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "audio.generation.job",
  "status": "queued"
}
```

字段说明：

| 字段 | 说明 |
|---|---|
| `id` / `task_id` | 异步任务 ID，用于查询结果 |
| `status` | 任务状态，常见值为 `queued`、`processing`、`completed`、`failed` |

---

## 4. 查询音乐任务

```http
GET https://api.xxx.xx/v1/audio/tasks/{task_id}
```

查询示例：

```bash
curl -X GET "https://api.xxx.xx/v1/audio/tasks/task_xxxxxxxxxxxxx" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx"
```

完成响应示例：

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "audio.generation.job",
  "status": "completed",
  "audio_url": "https://api.xxx.xx/media/xxxxx.mp3",
  "result": {
    "outputs": [
      "https://api.xxx.xx/media/xxxxx.mp3"
    ],
    "audios": [
      {
        "url": "https://api.xxx.xx/media/xxxxx.mp3"
      }
    ]
  }
}
```

---

## 5. 请求示例

### 5.1 生成广告歌曲

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-2.6",
    "prompt": "A bright synth pop song for a product launch, upbeat, modern commercial style, clean vocal, energetic chorus",
    "lyrics": "Hello future, we are ready now\nLight the skyline, make it loud\nEvery step is shining brighter\nWe are here and moving proud",
    "lyrics_optimizer": true,
    "is_instrumental": false
  }'
```

### 5.2 生成短视频 BGM

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-2.6",
    "prompt": "A catchy 30-second lifestyle vlog background track, light guitar, soft beat, sunny mood, no vocal",
    "is_instrumental": true
  }'
```

### 5.3 生成播客片头音乐

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-2.6",
    "prompt": "A warm podcast intro jingle, 8 to 12 seconds feeling, soft piano, subtle electronic pulse, professional and friendly",
    "is_instrumental": true
  }'
```

### 5.4 生成中文品牌歌曲

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-2.6",
    "prompt": "Chinese mandopop brand song, warm female vocal, inspiring chorus, clean arrangement, suitable for a technology brand",
    "lyrics": "向前走 不回头\n新的光 落在心口\n每一次 出发的时候\n我们都 把未来握在手中",
    "lyrics_optimizer": true,
    "is_instrumental": false
  }'
```

### 5.5 生成课程开场音乐

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-2.6",
    "prompt": "Educational course intro music, calm but motivating, soft marimba, piano, gentle percussion, suitable for online learning",
    "is_instrumental": true
  }'
```

---


## 6. 常见错误

### 6.1 缺少 prompt

错误请求：

```json
{
  "model": "minimax-music-2.6",
  "lyrics": "Hello world"
}
```

修复方式：补充 `prompt`。

### 6.2 非纯音乐但缺少歌词

如果设置：

```json
{
  "is_instrumental": false
}
```

建议同时传入 `lyrics`。

---

## 7. 推荐工作流

1. 根据场景写清楚音乐风格、情绪、用途。
2. 如果需要人声，提供歌词。
3. 提交 `/v1/audio/tasks`。
4. 轮询 `/v1/audio/tasks/{task_id}`。
5. 任务完成后读取 `audio_url`。

---

## 8. 最小可用请求

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-2.6",
    "prompt": "A bright short commercial pop song, modern and uplifting",
    "is_instrumental": true
  }'
```

---

# 语音与音乐概览

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/audio/overview
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/audio/overview.md
Description: UniAll 语音合成和音乐生成文档入口。

本分类整理来源菜单中的语音合成和音乐生成。

## 包含页面

- [音乐生成](/zh-CN/models/audio/music-generation)
- [语音合成](/zh-CN/models/audio/speech-synthesis)

## 接入建议

`minimax-music-2.6` 音乐任务使用 [音乐生成](/zh-CN/models/audio/music-generation)。MiniMax Speech HD 文本转语音和音色管理使用 [语音合成](/zh-CN/models/audio/speech-synthesis)。

两个能力都以异步音频任务为主：先提交任务，再根据 `task_id` 轮询，成功后读取返回的音频 URL。

---

# 语音合成

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/audio/speech-synthesis
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/audio/speech-synthesis.md
Description: 使用 UniAll 异步音频 API 生成语音并管理 MiniMax 音色。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

使用 MiniMax Speech HD 系列模型可以把文本生成语音。音色管理接口可以查询系统音色，也可以通过声音克隆或声音设计创建可复用的私有 `voice_id`。

## When To Use It

- 为短视频、广告、课程、旁白或数字人生成语音。
- 使用系统公共音色。
- 克隆或设计私有音色，再把返回的 `voice_id` 用在语音任务中。

## Supported Models

| 模型 | 类型 | 推荐场景 |
| --- | --- | --- |
| `minimax-speech-2.8-hd` | 文本转语音 | 自然短口播、情绪旁白、广告、数字人语音。 |
| `minimax-speech-02-hd` | 文本转语音 | 有声书、课程讲解、客服播报、新闻播报、长文本旁白。 |

## Endpoint

```http
POST /v1/audio/tasks
GET  /v1/audio/tasks/{task_id}
GET  /v1/audio/voices
POST /v1/audio/voices/clone
POST /v1/audio/voices/design
```

## Authentication

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## Speech Request Parameters

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `minimax-speech-2.8-hd` 或 `minimax-speech-02-hd`。 |
| `text` | string | 是 | 需要合成的文本。 |
| `voice_id` | string | 是 | 公共或私有音色 ID。 |
| `speed` | number | 否 | 模型支持时控制语速。 |
| `volume` | number | 否 | 模型支持时控制音量。 |
| `pitch` | number | 否 | 模型支持时控制音高。 |
| `format` | string | 否 | 输出格式，例如 `mp3` 或 `wav`。 |
| `language` | string | 否 | 多语言文本的语言提示。 |
| `audio_setting` | object | 否 | 模型支持时透传的高级音频设置。 |

## Speech Request Example

```bash
curl -X POST "{BASE_URL}/v1/audio/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-2.8-hd",
    "text": "Welcome back. Today we will introduce a faster way to build AI applications.",
    "voice_id": "voice_xxx",
    "format": "mp3",
    "speed": 1
  }'
```

## Submit Response

```json
{
  "task_id": "task_xxx",
  "status": "queued",
  "model": "minimax-speech-2.8-hd",
  "created_at": 1773980459
}
```

## Query Task Status

```bash
curl "{BASE_URL}/v1/audio/tasks/task_xxx" \
  -H "Authorization: Bearer sk-***"
```

```json
{
  "task_id": "task_xxx",
  "status": "succeeded",
  "progress": "100%",
  "output": {
    "audio_url": "https://example.com/speech.mp3"
  },
  "error": null
}
```

## Voice Management

查询可用音色：

```bash
curl "{BASE_URL}/v1/audio/voices" \
  -H "Authorization: Bearer sk-***"
```

通过参考音频克隆音色：

```bash
curl -X POST "{BASE_URL}/v1/audio/voices/clone" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "brand-narrator",
    "audio_url": "https://example.com/reference.wav"
  }'
```

通过文本描述设计音色：

```bash
curl -X POST "{BASE_URL}/v1/audio/voices/design" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "warm-host",
    "description": "Warm, clear, young adult narrator for product explainers"
  }'
```

后续语音任务中使用返回的 `voice_id`。

## Billing Notes

语音生成按生成音频用量计费。声音克隆和声音设计会创建可复用私有音色，可能单独计费。精确价格应以当前产品价格页为准。

## Common Errors

- 缺少 `text` 或 `voice_id`。
- 传入当前账户不可见的私有 `voice_id`。
- 文本过长但没有拆分为多个任务。
- 输出格式不支持。
- 余额不足或 API Key 已禁用。

## Related Pages

- [语音与音乐概览](/zh-CN/models/audio/overview)
- [音乐生成](/zh-CN/models/audio/music-generation)
- [数字人口播](/zh-CN/models/avatar/digital-human)

---

# MiniMax Speech HD

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/audio/speech/minimax-speech-hd
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/audio/speech/minimax-speech-hd.md
Description: MiniMax Speech HD 语音生成来源文档。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

本文档介绍如何在 aijisu 中使用 MiniMax Speech HD 系列异步语音生成模型。

当前支持模型：

| 模型名称 | 类型 | 推荐场景 |
|---|---|---|
| `minimax-speech-2.8-hd` | 文本转语音 | 短视频口播、广告配音、数字人语音、情绪化旁白、自然口语 |
| `minimax-speech-02-hd` | 文本转语音 | 有声书、课程讲解、客服播报、新闻播报、长文本旁白、多语言语音 |

接口采用异步任务模式：

| 操作 | 方法 | 路径 |
|---|---|---|
| 提交语音任务 | `POST` | `/v1/audio/tasks` |
| 查询语音任务 | `GET` | `/v1/audio/tasks/{task_id}` |

基础请求地址示例：

```uri
https://api.xxx.xx
```

## 1. 模型简介

### 1.1 minimax-speech-2.8-hd

`minimax-speech-2.8-hd` 是更新一代高清语音生成模型，适合需要更强自然感、口语感、停顿感和情绪表现力的语音内容。

适合场景：

- 短视频口播
- 广告配音
- 数字人讲解
- 情绪化角色台词
- 播客开场
- 带笑声、叹气、停顿等自然声音细节的内容

推荐文本示例：

```markdown
欢迎回来。<#0.5#> 今天我们聊一个很有意思的话题。(laughs)
```

### 1.2 minimax-speech-02-hd

`minimax-speech-02-hd` 是成熟稳定的高清语音生成模型，适合生产型、稳定型、长文本型语音任务。

适合场景：

- 有声书
- 课程讲解
- 企业培训
- 新闻播报
- 客服语音
- 长文本旁白
- 多语言语音生成

推荐文本示例：

```markdown
本节课我们将学习函数的基本概念。函数可以帮助我们封装重复逻辑，提高代码复用性。
```

## 2. 鉴权方式

所有请求都需要携带 API Key。

请求头：

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 3. 提交语音生成任务

请求地址：

```http
POST https://api.xxx.xx/v1/audio/tasks
```

### 3.1 请求参数

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | 是 | 模型名称，支持 `minimax-speech-2.8-hd`、`minimax-speech-02-hd` |
| `text` | string | 是 | 要生成语音的文本 |
| `input` | string | 否 | `text` 的别名，适配部分 OpenAI 风格请求 |
| `voice_id` | string | 否 | 音色 ID，例如平台提供的预设音色或克隆音色 ID |
| `voice` | string | 否 | 音色名称，兼容字段 |
| `speed` | number | 否 | 语速，常用范围 `0.5` 到 `2.0` |
| `emotion` | string | 否 | 情绪，如 `happy`、`sad`、`angry`、`fearful`、`disgusted`、`surprised`、`neutral` |
| `language` | string | 否 | 语言提示，如 `Chinese`、`English`、`Japanese`、`auto` |
| `output_format` | string | 否 | 输出格式，建议使用 `url` |
| `response_format` | string | 否 | 响应格式，建议使用 `url` |
| `sample_rate` | number | 否 | 采样率，如 `32000`、`44100` |
| `pronunciation_dict` | object | 否 | 自定义发音词典 |
| `timber_weights` | array | 否 | 混合音色权重，高级用法 |
| `subtitle_enable` | boolean | 否 | 是否尝试生成字幕信息 |
| `metadata` | object | 否 | 自定义业务信息 |
| `extra_body` | object | 否 | 高级参数扩展 |

注意：

- `text` 和 `input` 二选一即可。
- 推荐优先使用 `text`。
- 如果同时传入 `text` 和 `input`，两者内容必须一致。
- 当前接口为异步任务接口，提交任务后需要通过 `task_id` 查询结果。
- 计费按输入字符数计算，中文、英文、数字、标点、空格、换行、emoji、停顿标签、声音标签都会计入字符数。
- 示例中的 `voice_id` 仅用于演示，请替换为站内实际可用音色 ID。

### 3.2 最简请求示例

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-2.8-hd",
    "text": "你好，欢迎使用 aijisu 语音生成服务。"
  }'
```

### 3.3 提交成功返回示例

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "audio.generation.job",
  "status": "queued",
  "raw_status": "SUBMITTED",
  "progress": "0%",
  "audio_url": null,
  "result": null,
  "error": null
}
```

## 4. 查询任务结果

请求地址：

```http
GET https://api.xxx.xx/v1/audio/tasks/{task_id}
```

请求示例：

```bash
curl -X GET "https://api.xxx.xx/v1/audio/tasks/task_xxxxxxxxxxxxx" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### 4.1 生成中返回示例

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "audio.generation.job",
  "status": "in_progress",
  "raw_status": "IN_PROGRESS",
  "progress": "45%",
  "audio_url": null,
  "result": null,
  "error": null
}
```

### 4.2 生成完成返回示例

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "audio.generation.job",
  "status": "completed",
  "raw_status": "SUCCESS",
  "progress": "100%",
  "audio_url": "https://example.com/audio.mp3",
  "result": {
    "audio_url": "https://example.com/audio.mp3",
    "outputs": [
      "https://example.com/audio.mp3"
    ],
    "audios": [
      {
        "url": "https://example.com/audio.mp3"
      }
    ]
  },
  "error": null
}
```

### 4.3 生成失败返回示例

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "audio.generation.job",
  "status": "failed",
  "raw_status": "FAILURE",
  "progress": "100%",
  "audio_url": null,
  "result": null,
  "error": {
    "message": "audio task failed"
  }
}
```

## 5. 任务状态说明

| status | 说明 |
|---|---|
| `queued` | 已提交，等待处理 |
| `in_progress` | 正在生成 |
| `processing` | 处理中 |
| `completed` | 生成完成 |
| `failed` | 生成失败 |

建议每 2 到 5 秒查询一次任务状态，不建议高频轮询。

## 6. 声音标签和停顿

`minimax-speech-2.8-hd` 更适合使用自然声音标签和停顿标记。

| 写法 | 说明 |
|---|---|
| `<#0.5#>` | 停顿 0.5 秒 |
| `<#1.0#>` | 停顿 1 秒 |
| `(laughs)` | 笑声 |
| `(sighs)` | 叹气 |
| `(coughs)` | 咳嗽 |
| `(clears throat)` | 清嗓 |
| `(gasps)` | 倒吸气 |
| `(sniffs)` | 吸鼻 |
| `(groans)` | 低哼 |
| `(yawns)` | 打哈欠 |

示例：

```markdown
你终于来了。<#0.8#> 我还以为，你已经忘了这个约定。(sighs)
```

## 7. 使用场景示例

### 7.1 中文短视频口播

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-2.8-hd",
    "text": "今天给大家分享一个提高效率的小技巧。<#0.4#> 很简单，但真的很有用。",
    "voice_id": "Wise_Woman",
    "speed": 1.05,
    "emotion": "happy",
    "output_format": "url"
  }'
```

### 7.2 课程讲解

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-02-hd",
    "text": "本节课我们将学习函数的基本概念。函数可以帮助我们把重复的逻辑封装起来，提高代码的复用性。",
    "voice_id": "Wise_Woman",
    "speed": 0.95,
    "emotion": "neutral",
    "output_format": "url"
  }'
```

### 7.3 广告配音

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-2.8-hd",
    "text": "全新升级，限时开启。<#0.3#> 现在下单，享受专属优惠！",
    "voice_id": "Wise_Woman",
    "speed": 1.12,
    "emotion": "happy",
    "output_format": "url"
  }'
```

### 7.4 有声书旁白

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-02-hd",
    "text": "夜色渐深，街边的灯一盏接一盏亮起。她站在窗前，安静地望着远处的城市。",
    "voice_id": "Wise_Woman",
    "speed": 0.88,
    "emotion": "neutral",
    "output_format": "url"
  }'
```

### 7.5 情绪化角色台词

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-2.8-hd",
    "text": "你终于来了。<#0.6#> 我还以为，你已经忘了这个约定。(sighs)",
    "voice_id": "Wise_Woman",
    "speed": 0.92,
    "emotion": "sad",
    "output_format": "url"
  }'
```

### 7.6 英文播客开场

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-2.8-hd",
    "text": "Hey, welcome back to the show. <#0.4#> Today we are talking about how AI is changing creative work. (laughs)",
    "voice_id": "Wise_Woman",
    "speed": 1.0,
    "emotion": "happy",
    "language": "English",
    "output_format": "url"
  }'
```

### 7.7 多语言客服问候

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-02-hd",
    "text": "您好，欢迎致电客户服务中心。Please hold on for a moment. 我们将尽快为您服务。",
    "voice_id": "Wise_Woman",
    "speed": 1.0,
    "language": "auto",
    "emotion": "neutral",
    "output_format": "url"
  }'
```

### 7.8 新闻播报

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-02-hd",
    "text": "今天的主要新闻包括：人工智能产业持续增长，多家企业发布新一代智能创作工具。",
    "voice_id": "Wise_Woman",
    "speed": 1.0,
    "emotion": "neutral",
    "output_format": "url"
  }'
```

### 7.9 数字人口播

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-2.8-hd",
    "text": "大家好，我是你的 AI 助手。<#0.4#> 接下来，我会用一分钟带你了解今天的重点内容。",
    "voice_id": "Wise_Woman",
    "speed": 1.03,
    "emotion": "happy",
    "output_format": "url"
  }'
```

### 7.10 儿童故事

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-2.8-hd",
    "text": "很久很久以前，森林里住着一只勇敢的小兔子。它每天最喜欢做的事情，就是去河边看星星。",
    "voice_id": "Wise_Woman",
    "speed": 0.9,
    "emotion": "happy",
    "output_format": "url"
  }'
```

### 7.11 企业培训语音

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-02-hd",
    "text": "欢迎参加本次企业安全培训。请大家认真阅读操作规范，并在实际工作中严格遵守。",
    "voice_id": "Wise_Woman",
    "speed": 0.96,
    "emotion": "neutral",
    "output_format": "url"
  }'
```

### 7.12 慢速冥想旁白

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-2.8-hd",
    "text": "闭上眼睛。<#1.0#> 慢慢吸气。<#1.0#> 再缓缓呼出。",
    "voice_id": "Wise_Woman",
    "speed": 0.82,
    "emotion": "neutral",
    "output_format": "url"
  }'
```

### 7.13 使用 input 字段提交

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-02-hd",
    "input": "这是一条使用 input 字段提交的语音生成任务。",
    "voice_id": "Wise_Woman",
    "output_format": "url"
  }'
```

### 7.14 自定义发音词典

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-2.8-hd",
    "text": "欢迎使用 AI极速，新一代智能创作平台。",
    "voice_id": "Wise_Woman",
    "output_format": "url",
    "pronunciation_dict": {
      "tone_list": [
        "AI极速/(A)(I)(ji2)(su4)"
      ]
    }
  }'
```

### 7.15 高采样率音频

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-2.8-hd",
    "text": "这是一段用于视频后期制作的高质量配音。",
    "voice_id": "Wise_Woman",
    "sample_rate": 44100,
    "output_format": "url"
  }'
```

### 7.16 客服 IVR 菜单播报

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-02-hd",
    "text": "您好，欢迎致电。业务咨询请按一，订单查询请按二，人工服务请按零。",
    "voice_id": "Wise_Woman",
    "speed": 0.98,
    "emotion": "neutral",
    "output_format": "url"
  }'
```

### 7.17 产品介绍视频旁白

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-2.8-hd",
    "text": "这是一款为创作者打造的智能工具。<#0.4#> 它可以帮你更快完成脚本、配音和内容生成。",
    "voice_id": "Wise_Woman",
    "speed": 1.02,
    "emotion": "happy",
    "output_format": "url"
  }'
```

### 7.18 严肃纪录片旁白

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-02-hd",
    "text": "在漫长的时间里，人类不断探索自然、理解世界，并试图找到自身与时代之间的关系。",
    "voice_id": "Wise_Woman",
    "speed": 0.9,
    "emotion": "neutral",
    "output_format": "url"
  }'
```

## 8. JavaScript 调用示例

```javascript
const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://api.xxx.xx";

async function createAudioTask() {
  const response = await fetch(`${BASE_URL}/v1/audio/tasks`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "minimax-speech-2.8-hd",
      text: "你好，这是一段由 aijisu 生成的语音。",
      voice_id: "Wise_Woman",
      speed: 1,
      emotion: "neutral",
      output_format: "url"
    })
  });

  if (!response.ok) {
    throw new Error(await response.text());
  }

  return await response.json();
}

async function getAudioTask(taskId) {
  const response = await fetch(`${BASE_URL}/v1/audio/tasks/${taskId}`, {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${API_KEY}`
    }
  });

  if (!response.ok) {
    throw new Error(await response.text());
  }

  return await response.json();
}

async function main() {
  const task = await createAudioTask();
  console.log("task_id:", task.task_id);

  while (true) {
    const result = await getAudioTask(task.task_id);
    console.log(result.status, result.progress);

    if (result.status === "completed") {
      console.log("audio_url:", result.audio_url);
      break;
    }

    if (result.status === "failed") {
      console.error("failed:", result.error);
      break;
    }

    await new Promise(resolve => setTimeout(resolve, 3000));
  }
}

main().catch(console.error);
```

## 9. Python 调用示例

```python
import time
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.xxx.xx"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "minimax-speech-02-hd",
    "text": "你好，这是一段通过 Python 提交的语音生成任务。",
    "voice_id": "Wise_Woman",
    "speed": 1,
    "emotion": "neutral",
    "output_format": "url",
}

create_resp = requests.post(
    f"{BASE_URL}/v1/audio/tasks",
    headers=headers,
    json=payload,
)
create_resp.raise_for_status()

task = create_resp.json()
task_id = task["task_id"]

while True:
    query_resp = requests.get(
        f"{BASE_URL}/v1/audio/tasks/{task_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
    )
    query_resp.raise_for_status()

    result = query_resp.json()
    print(result["status"], result.get("progress"))

    if result["status"] == "completed":
        print("audio_url:", result.get("audio_url"))
        break

    if result["status"] == "failed":
        print("failed:", result.get("error"))
        break

    time.sleep(3)
```

## 10. 计费说明

语音生成按输入字符数计费。

会计入字符数的内容包括：

- 中文
- 英文
- 数字
- 标点
- 空格
- 换行
- emoji
- 声音标签
- 停顿标签

示例：

```markdown
你好，世界！
```

字符计算：

```markdown
你 好 ， 世 界 ！
```

共 6 个字符。

实际扣费以站内模型价格、分组倍率、套餐规则和账户余额规则为准。

## 11. 模型选择建议

### 11.1 优先使用 minimax-speech-2.8-hd

适合：

- 需要更自然的口语表达
- 需要笑声、叹气、停顿等声音细节
- 做短视频口播
- 做广告配音
- 做数字人口播
- 做情绪化角色语音

### 11.2 优先使用 minimax-speech-02-hd

适合：

- 长文本旁白
- 有声书
- 课程讲解
- 客服播报
- 新闻播报
- 多语言内容
- 更偏稳定生产的场景

## 12. 推荐模板

### 12.1 短视频口播模板

```json
{
  "model": "minimax-speech-2.8-hd",
  "text": "今天给大家分享一个非常实用的小技巧。<#0.4#> 学会之后，你的效率会明显提升。",
  "voice_id": "Wise_Woman",
  "speed": 1.05,
  "emotion": "happy",
  "output_format": "url"
}
```

### 12.2 有声书模板

```json
{
  "model": "minimax-speech-02-hd",
  "text": "夜色渐深，城市的喧嚣慢慢退去，只剩窗外微弱的风声。",
  "voice_id": "Wise_Woman",
  "speed": 0.88,
  "emotion": "neutral",
  "output_format": "url"
}
```

### 12.3 客服播报模板

```json
{
  "model": "minimax-speech-02-hd",
  "text": "您好，欢迎致电客户服务中心。请稍候，我们将尽快为您接通人工服务。",
  "voice_id": "Wise_Woman",
  "speed": 1,
  "emotion": "neutral",
  "output_format": "url"
}
```

### 12.4 情绪角色模板

```json
{
  "model": "minimax-speech-2.8-hd",
  "text": "你真的要离开吗？<#0.8#> 我以为，我们还有机会。(sighs)",
  "voice_id": "Wise_Woman",
  "speed": 0.92,
  "emotion": "sad",
  "output_format": "url"
}
```

### 12.5 英文口播模板

```json
{
  "model": "minimax-speech-2.8-hd",
  "text": "Welcome back. <#0.4#> Today we are going to talk about how creators can use AI to work faster.",
  "voice_id": "Wise_Woman",
  "speed": 1,
  "emotion": "happy",
  "language": "English",
  "output_format": "url"
}
```

## 13. 常见问题

### 13.1 为什么提交后没有立刻返回音频？

因为语音生成是异步任务。提交接口只返回任务 ID，需要通过查询接口获取最终音频 URL。

### 13.2 `text` 和 `input` 有什么区别？

`input` 是 `text` 的别名。推荐优先使用 `text`。

### 13.3 能不能一次生成多个音频？

当前建议一次请求生成一条音频。如果需要多段音频，建议拆成多个任务分别提交。

### 13.4 长文本怎么处理？

建议按段落拆分成多个任务。这样更容易控制失败重试、段落顺序和后期拼接。

### 13.5 如何让语音更自然？

建议：

- 保留标点符号
- 适当加入停顿标签
- 不要把单句写得过长
- 根据场景调整 `speed`
- 口播、广告、数字人优先使用 `minimax-speech-2.8-hd`

### 13.6 音频 URL 可以直接播放吗？

任务完成后返回的 `audio_url` 通常可以直接用于播放器播放、下载或后续处理。实际可访问时长以站点存储策略为准。

### 13.7 请求失败时怎么排查？

常见原因：

- API Key 未填写或无效
- `model` 写错
- `text` 或 `input` 为空
- 同时传入 `text` 和 `input`，但两者内容不一致
- 音色 ID 不可用
- 参数格式不正确
- 账户余额不足或无权限使用该模型

## 14. 完整流程示例

### 第一步：提交任务

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-2.8-hd",
    "text": "你好，这是一条完整流程测试语音。",
    "voice_id": "Wise_Woman",
    "speed": 1,
    "emotion": "neutral",
    "output_format": "url"
  }'
```

返回：

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "audio.generation.job",
  "status": "queued",
  "raw_status": "SUBMITTED",
  "progress": "0%",
  "audio_url": null,
  "result": null,
  "error": null
}
```

### 第二步：查询任务

```bash
curl -X GET "https://api.xxx.xx/v1/audio/tasks/task_xxxxxxxxxxxxx" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### 第三步：获取音频 URL

当 `status` 为 `completed` 时，读取：

```json
{
  "audio_url": "https://example.com/audio.mp3"
}
```

即可播放或下载生成的音频。

---

# MiniMax Speech 音色管理

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/audio/speech/voice-management
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/audio/speech/voice-management.md
Description: MiniMax Speech 音色管理来源文档。

本文档介绍如何在 aijisu 中使用 MiniMax 音色能力，包括音色列表、声音克隆和声音设计。

如果你只是想把文字生成语音，请使用语音生成接口：

- `POST /v1/audio/tasks`
- `GET /v1/audio/tasks/{task_id}`

如果你想创建自己的 `voice_id`，再把这个 `voice_id` 用到语音生成里，请使用本文档中的音色接口。

## 1. 支持能力

| 能力 | 接口 | 是否收费 | 说明 |
|---|---|---:|---|
| 查询音色列表 | `GET /v1/audio/voices` | 否 | 返回系统公共音色和当前账号可见的私有音色 |
| 声音克隆 | `POST /v1/audio/voices/clone` | 是 | 通过参考音频生成一个可复用的 `voice_id` |
| 声音设计 | `POST /v1/audio/voices/design` | 是 | 通过文字描述设计一个可复用的 `voice_id` |
| 使用音色生成语音 | `POST /v1/audio/tasks` | 是 | 将 `voice_id` 传给 TTS 模型生成音频 |

当前推荐配合以下 TTS 模型使用：

| 模型名称 | 说明 |
|---|---|
| `minimax-speech-2.8-hd` | 更新一代高清语音生成模型，适合自然口播、短视频、数字人、广告配音 |
| `minimax-speech-02-hd` | 稳定高清语音生成模型，适合旁白、有声书、课程、客服、长文本播报 |

声音克隆和声音设计创建出来的 `voice_id` 可以在以上两个 TTS 模型中使用。

## 2. 接口地址

示例域名统一使用：

```uri
https://api.xxx.xx
```

实际调用时请替换为你的 aijisu API 域名。

| 操作 | 方法 | 路径 |
|---|---|---|
| 查询音色列表 | `GET` | `/v1/audio/voices` |
| 声音克隆 | `POST` | `/v1/audio/voices/clone` |
| 声音设计 | `POST` | `/v1/audio/voices/design` |
| 提交语音生成任务 | `POST` | `/v1/audio/tasks` |
| 查询语音生成任务 | `GET` | `/v1/audio/tasks/{task_id}` |

## 3. 鉴权方式

所有接口都使用 Bearer Token：

```http
Authorization: Bearer YOUR_API_KEY
```

示例：

```bash
curl https://api.xxx.xx/v1/audio/voices \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## 4. 音色 ID 说明

`voice_id` 是调用 TTS 时使用的音色标识。

音色来源分为两类：

| 来源 | 说明 |
|---|---|
| 系统音色 | 平台内置公共音色，所有用户可查询和使用 |
| 私有音色 | 当前账号通过声音克隆或声音设计创建的音色，仅当前账号可见和可用 |

声音克隆和声音设计成功后，接口会返回一个 `voice_id`。你可以把它保存到自己的业务系统中，后续在 `/v1/audio/tasks` 中传入该 `voice_id` 来生成语音。

## 5. 查询音色列表

### 5.1 请求

```http
GET /v1/audio/voices
```

可选查询参数：

| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---:|---|
| `model` | string | 否 | 按兼容模型筛选音色，可选 `minimax-speech-2.8-hd` 或 `minimax-speech-02-hd` |

### 5.2 查询全部可见音色

```bash
curl "https://api.xxx.xx/v1/audio/voices" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### 5.3 查询适用于 Speech 2.8 HD 的音色

```bash
curl "https://api.xxx.xx/v1/audio/voices?model=minimax-speech-2.8-hd" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### 5.4 查询适用于 Speech 02 HD 的音色

```bash
curl "https://api.xxx.xx/v1/audio/voices?model=minimax-speech-02-hd" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### 5.5 响应示例

```json
{
  "object": "audio.voice.list",
  "model": "minimax-speech-2.8-hd",
  "data": [
    {
      "voice_id": "Chinese (Mandarin)_Kind-hearted_Elder",
      "display_name": "Kind-hearted Elder",
      "language": "Chinese (Mandarin)",
      "description": "MiniMax system voice",
      "source_type": "system",
      "visibility": "public",
      "status": "active",
      "compatible_models": [
        "minimax-speech-2.8-hd",
        "minimax-speech-02-hd"
      ],
      "preview_audio_url": null,
      "created_at": "2026-06-23T18:05:59Z"
    },
    {
      "voice_id": "ttv-voice-2026062416421526-E4jmMP8B",
      "display_name": "local-design-taskid-smoke",
      "language": "Chinese (Mandarin)",
      "description": "Local smoke test for task id in sync response.",
      "source_type": "voice_design",
      "visibility": "private",
      "status": "active",
      "compatible_models": [
        "minimax-speech-2.8-hd",
        "minimax-speech-02-hd"
      ],
      "preview_audio_url": "https://api.xxx.xx/media/preview.mp3",
      "created_at": "2026-06-24T08:42:23Z"
    }
  ]
}
```

### 5.6 响应字段

| 字段 | 说明 |
|---|---|
| `object` | 固定为 `audio.voice.list` |
| `model` | 当前筛选模型 |
| `data` | 音色数组 |
| `data[].voice_id` | 音色 ID，后续 TTS 调用传这个值 |
| `data[].display_name` | 音色名称 |
| `data[].language` | 音色语言 |
| `data[].description` | 音色描述 |
| `data[].source_type` | 音色来源，可能是 `system`、`voice_clone`、`voice_design` |
| `data[].visibility` | 可见性，可能是 `public` 或 `private` |
| `data[].status` | 状态，通常为 `active` |
| `data[].compatible_models` | 可使用该音色的 TTS 模型 |
| `data[].preview_audio_url` | 预览音频链接，可能为空 |
| `data[].created_at` | 创建时间 |

## 6. 声音克隆

声音克隆用于从一段参考音频中提取声音特征，创建一个新的私有 `voice_id`。

适合场景：

- 克隆主播、讲师、客服、品牌代言人的声音
- 为数字人生成固定音色
- 为课程、有声书、短视频矩阵复用同一个声音
- 把线下录音中的声音整理成可重复调用的 TTS 音色

### 6.1 请求

```http
POST /v1/audio/voices/clone
```

请求体为 JSON。

| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---:|---|
| `audio_url` | string | 是 | 参考音频 URL，需要接口服务可访问 |
| `text` | string | 建议 | 参考音频对应文本或预览文本，用于提升克隆质量和生成预览 |
| `preview_text` | string | 否 | `text` 的兼容字段。若同时传，建议与 `text` 保持一致 |
| `display_name` | string | 否 | 音色名称，便于列表展示 |
| `name` | string | 否 | `display_name` 的兼容字段 |
| `language` | string | 否 | 音色语言，例如 `Chinese (Mandarin)`、`English` |
| `description` | string | 否 | 音色描述 |
| `noise_reduction` | boolean | 否 | 是否启用降噪 |
| `need_volume_normalization` | boolean | 否 | 是否进行音量归一化 |
| `accuracy` | number/string | 否 | 克隆精度相关参数，按平台当前支持透传 |

### 6.2 参考音频建议

| 项目 | 建议 |
|---|---|
| 音频内容 | 单人说话，背景干净 |
| 音频时长 | 建议 10 秒以上，过短会影响相似度 |
| 录音质量 | 尽量无混响、无音乐、无明显噪声 |
| 说话方式 | 自然稳定，不要频繁变声或多人交替 |
| 文本匹配 | 如果知道音频原文，建议把原文放到 `text` |
| 授权合规 | 仅克隆你有权使用的声音 |

### 6.3 最小请求示例

```bash
curl -X POST "https://api.xxx.xx/v1/audio/voices/clone" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/audio/reference-speaker.mp3",
    "text": "大家好，欢迎来到今天的课程。我们会用简单的方法讲清楚这个概念。",
    "display_name": "course-teacher-voice",
    "language": "Chinese (Mandarin)"
  }'
```

### 6.4 带降噪和音量归一化

```bash
curl -X POST "https://api.xxx.xx/v1/audio/voices/clone" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/audio/noisy-reference.wav",
    "text": "这是一个用于声音克隆的参考音频，请尽量保持音色自然稳定。",
    "display_name": "cleaned-brand-speaker",
    "language": "Chinese (Mandarin)",
    "description": "品牌讲解类克隆音色",
    "noise_reduction": true,
    "need_volume_normalization": true
  }'
```

### 6.5 英文主播声音克隆

```bash
curl -X POST "https://api.xxx.xx/v1/audio/voices/clone" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/audio/english-host.mp3",
    "text": "Welcome back to the show. Today we are going to explore a simple but powerful idea.",
    "display_name": "english-podcast-host",
    "language": "English",
    "description": "Warm English podcast host voice"
  }'
```

### 6.6 响应示例

```json
{
  "object": "audio.voice",
  "model": "minimax-voice-clone",
  "task_id": "task_abc123",
  "voice_id": "VoiceClone123456",
  "preview_audio_url": "https://api.xxx.xx/media/voice-clone-preview.mp3",
  "voice": {
    "voice_id": "VoiceClone123456",
    "display_name": "course-teacher-voice",
    "language": "Chinese (Mandarin)",
    "description": "品牌讲解类克隆音色",
    "source_type": "voice_clone",
    "visibility": "private",
    "status": "active",
    "compatible_models": [
      "minimax-speech-2.8-hd",
      "minimax-speech-02-hd"
    ],
    "preview_audio_url": "https://api.xxx.xx/media/voice-clone-preview.mp3",
    "created_at": "2026-06-24T08:42:23Z"
  },
  "billing_contract": {
    "billing_version": "media-v1",
    "public_model": "minimax-voice-clone",
    "operation": "audio.voice_clone",
    "settlement_policy": "fixed_at_estimate",
    "billing_stage": "final",
    "facts": {
      "voice_clones": 1,
      "preview_characters": 36
    }
  },
  "outputs": [
    {
      "url": "https://api.xxx.xx/media/voice-clone-preview.mp3",
      "type": "audio"
    }
  ]
}
```

## 7. 声音设计

声音设计用于通过文字描述生成一个新的私有 `voice_id`，不需要上传参考音频。

适合场景：

- 为短视频账号设计固定口播音色
- 为数字人设计声音人设
- 为游戏角色、剧情角色、广播主持人设计声音
- 快速生成客服、课程、广告、旁白音色
- 没有参考音频，但有明确声音描述的场景

### 7.1 请求

```http
POST /v1/audio/voices/design
```

请求体为 JSON。

| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---:|---|
| `prompt` | string | 是 | 声音设计描述，描述音色、性别、年龄感、语言、情绪、场景等 |
| `preview_text` | string | 是 | 用于生成预览音频的文本 |
| `text` | string | 否 | `preview_text` 的兼容字段 |
| `display_name` | string | 否 | 音色名称，便于列表展示 |
| `name` | string | 否 | `display_name` 的兼容字段 |
| `language` | string | 否 | 音色语言，例如 `Chinese (Mandarin)`、`English` |
| `description` | string | 否 | 音色描述 |

### 7.2 Prompt 写法建议

建议在 `prompt` 中描述这些信息：

| 维度 | 示例 |
|---|---|
| 语言 | Chinese Mandarin、English、Cantonese |
| 性别 | male、female |
| 年龄感 | young adult、middle-aged、elder |
| 声音质感 | warm、clear、soft、energetic、calm |
| 场景 | product demo、customer service、audiobook、game character |
| 情绪 | friendly、confident、gentle、dramatic |
| 节奏 | slow、medium pace、lively |

### 7.3 中文温柔旁白

```bash
curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A warm, calm Chinese Mandarin female narrator voice for short product demos, clear diction, gentle confidence, studio quality.",
    "preview_text": "你好，这是一段声音设计预览。欢迎体验全新的语音能力。",
    "display_name": "warm-product-narrator",
    "language": "Chinese (Mandarin)",
    "description": "适合产品讲解和短视频口播的温柔女声"
  }'
```

### 7.4 数字人口播音色

```bash
curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A confident Chinese Mandarin female digital human presenter voice, natural conversational tone, bright but not exaggerated, suitable for business explanation videos.",
    "preview_text": "大家好，我是你的智能讲解员。今天我们用一分钟了解这个功能。",
    "display_name": "digital-human-presenter",
    "language": "Chinese (Mandarin)",
    "description": "数字人讲解员音色"
  }'
```

### 7.5 客服播报音色

```bash
curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A polite Chinese Mandarin customer service voice, patient, clear, stable, friendly, suitable for service notifications and call center messages.",
    "preview_text": "您好，您的订单已经处理完成。如有疑问，请随时联系我们的客服团队。",
    "display_name": "customer-service-clear",
    "language": "Chinese (Mandarin)",
    "description": "客服通知和电话播报音色"
  }'
```

### 7.6 游戏角色音色

```bash
curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A young Chinese Mandarin fantasy game character voice, playful, lively, slightly mysterious, expressive but clear.",
    "preview_text": "终于等到你了。前面的路可不简单，跟紧我，我们马上出发。",
    "display_name": "fantasy-guide-character",
    "language": "Chinese (Mandarin)",
    "description": "游戏引导角色音色"
  }'
```

### 7.7 英文广告音色

```bash
curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A modern English commercial voice, energetic, premium, confident, suitable for product launch ads and social media videos.",
    "preview_text": "Meet the new way to create, edit, and publish your ideas in minutes.",
    "display_name": "english-commercial-premium",
    "language": "English",
    "description": "English commercial voice for product ads"
  }'
```

### 7.8 有声书旁白音色

```bash
curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A mature Chinese Mandarin audiobook narrator voice, calm, steady, immersive, with clear pronunciation and comfortable pacing.",
    "preview_text": "夜色慢慢落下，远处的灯光一盏接一盏亮起，故事也从这里开始。",
    "display_name": "audiobook-calm-narrator",
    "language": "Chinese (Mandarin)",
    "description": "有声书长篇旁白音色"
  }'
```

### 7.9 响应示例

```json
{
  "object": "audio.voice",
  "model": "minimax-voice-design",
  "task_id": "task_437fb17536aa4ff7830ffb7a39f43a99",
  "voice_id": "ttv-voice-2026062416421526-E4jmMP8B",
  "preview_audio_url": "https://api.xxx.xx/media/design-preview.mp3",
  "voice": {
    "voice_id": "ttv-voice-2026062416421526-E4jmMP8B",
    "display_name": "warm-product-narrator",
    "language": "Chinese (Mandarin)",
    "description": "适合产品讲解和短视频口播的温柔女声",
    "source_type": "voice_design",
    "visibility": "private",
    "status": "active",
    "compatible_models": [
      "minimax-speech-2.8-hd",
      "minimax-speech-02-hd"
    ],
    "preview_audio_url": "https://api.xxx.xx/media/design-preview.mp3",
    "created_at": "2026-06-24T08:42:23Z"
  },
  "billing_contract": {
    "billing_version": "media-v1",
    "public_model": "minimax-voice-design",
    "operation": "audio.voice_design",
    "settlement_policy": "fixed_at_estimate",
    "billing_stage": "final",
    "facts": {
      "voice_designs": 1,
      "preview_characters": 12
    }
  },
  "outputs": [
    {
      "url": "https://api.xxx.xx/media/design-preview.mp3",
      "type": "audio"
    }
  ]
}
```

## 8. 将 voice_id 用于语音生成

声音克隆或声音设计成功后，把返回的 `voice_id` 放到 `/v1/audio/tasks` 中即可生成语音。

### 8.1 使用声音设计音色生成中文口播

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-2.8-hd",
    "text": "欢迎来到今天的产品演示。接下来，我们会快速了解三个核心功能。",
    "voice_id": "ttv-voice-2026062416421526-E4jmMP8B",
    "speed": 1.0,
    "response_format": "url"
  }'
```

### 8.2 使用声音克隆音色生成课程讲解

```bash
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-02-hd",
    "text": "本节课我们来学习一个非常重要的概念。请先观察这个例子，再思考它背后的规律。",
    "voice_id": "VoiceClone123456",
    "speed": 0.95,
    "response_format": "url"
  }'
```

### 8.3 查询语音生成任务

```bash
curl "https://api.xxx.xx/v1/audio/tasks/task_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### 8.4 语音生成任务完成响应示例

```json
{
  "object": "audio.generation.job",
  "task_id": "task_abc123",
  "model": "minimax-speech-2.8-hd",
  "status": "completed",
  "audio_url": "https://api.xxx.xx/media/output.mp3",
  "result": {
    "audio_url": "https://api.xxx.xx/media/output.mp3",
    "outputs": [
      "https://api.xxx.xx/media/output.mp3"
    ],
    "audios": [
      {
        "url": "https://api.xxx.xx/media/output.mp3"
      }
    ]
  }
}
```

## 9. 计费说明

实际扣费以 aijisu 控制台展示和账户配置为准。以下为当前接口的基础计费口径。

| 能力 | 计费项 | 基础计费公式 |
|---|---|---|
| 查询音色列表 | 免费 | 不扣费 |
| 声音克隆 | 克隆次数 + 预览字符 | `voice_clones * 1.5 + preview_characters * 0.0003` |
| 声音设计 | 设计次数 + 预览字符 | `voice_designs * 3 + preview_characters * 0.00003` |
| 语音生成 | 输入字符数 | 按 TTS 模型的字符计费规则 |

说明：

- `preview_characters` 是预览文本的 Unicode 字符数。
- 中文、英文、空格、标点、换行、emoji 都会计入字符数。
- 字符数不是 UTF-8 字节数，也不是 token 数。
- 声音克隆和声音设计采用提交时确认计费策略。
- 如果请求失败，按平台失败退款规则处理。

## 10. Node.js 示例

### 10.1 声音设计

```javascript
const response = await fetch("https://api.xxx.xx/v1/audio/voices/design", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "A warm Chinese Mandarin female narrator voice, clear and calm.",
    preview_text: "你好，这是声音设计预览。",
    display_name: "node-design-voice",
    language: "Chinese (Mandarin)"
  })
});

const data = await response.json();
console.log(data.voice_id);
console.log(data.preview_audio_url);
```

### 10.2 用生成的 voice_id 创建语音任务

```javascript
const voiceId = "ttv-voice-2026062416421526-E4jmMP8B";

const response = await fetch("https://api.xxx.xx/v1/audio/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "minimax-speech-2.8-hd",
    text: "这是一段使用自定义音色生成的语音。",
    voice_id: voiceId,
    response_format: "url"
  })
});

const task = await response.json();
console.log(task.task_id);
```

## 11. Python 示例

### 11.1 声音克隆

```python
import requests

api_key = "YOUR_API_KEY"

response = requests.post(
    "https://api.xxx.xx/v1/audio/voices/clone",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "audio_url": "https://example.com/audio/reference-speaker.mp3",
        "text": "大家好，欢迎来到今天的课程。",
        "display_name": "python-clone-voice",
        "language": "Chinese (Mandarin)",
        "noise_reduction": True,
        "need_volume_normalization": True,
    },
    timeout=180,
)

data = response.json()
print(data["voice_id"])
print(data.get("preview_audio_url"))
```

### 11.2 查询音色列表

```python
import requests

api_key = "YOUR_API_KEY"

response = requests.get(
    "https://api.xxx.xx/v1/audio/voices",
    headers={"Authorization": f"Bearer {api_key}"},
    params={"model": "minimax-speech-2.8-hd"},
    timeout=30,
)

voices = response.json()["data"]
for voice in voices:
    print(voice["voice_id"], voice.get("display_name"))
```

## 12. 常见错误

### 12.1 缺少鉴权

```json
{
  "error": {
    "message": "API key required.",
    "type": "invalid_request_error",
    "code": "api_key_required"
  }
}
```

解决方法：检查请求头是否包含 `Authorization: Bearer YOUR_API_KEY`。

### 12.2 声音克隆缺少 audio_url

```json
{
  "error": {
    "message": "`audio_url` is required.",
    "type": "invalid_request_error",
    "code": "invalid_request_parameter"
  }
}
```

解决方法：传入可公网访问的参考音频 URL。

### 12.3 声音设计缺少 prompt

```json
{
  "error": {
    "message": "`prompt` is required.",
    "type": "invalid_request_error",
    "code": "invalid_request_parameter"
  }
}
```

解决方法：补充声音描述，例如性别、语言、场景、情绪、语速和质感。

### 12.4 声音设计缺少 preview_text

```json
{
  "error": {
    "message": "`preview_text` is required.",
    "type": "invalid_request_error",
    "code": "invalid_request_parameter"
  }
}
```

解决方法：传入用于生成预览音频的文本。

### 12.5 voice_id 不可用

```json
{
  "error": {
    "message": "`voice_id` is not visible for the current client or is not compatible with this model",
    "type": "invalid_request_error",
    "code": "invalid_request_parameter"
  }
}
```

可能原因：

- `voice_id` 拼写错误。
- 当前账号无权使用该私有音色。
- 该音色不兼容当前 TTS 模型。
- 音色已被禁用或不可用。

解决方法：

1. 先调用 `GET /v1/audio/voices?model=...` 查询可用音色。
2. 从返回结果中复制 `voice_id`。
3. 再将该 `voice_id` 用到 `/v1/audio/tasks`。

## 13. 最佳实践

### 13.1 什么时候用声音克隆

当你已经有参考音频，并且需要复刻某个真实声音时，使用声音克隆。

典型场景：

- 已有主播录音。
- 已有讲师试听音频。
- 已有品牌代言人授权音频。
- 想让后续 TTS 尽量接近参考声音。

### 13.2 什么时候用声音设计

当你没有参考音频，但能描述想要的声音时，使用声音设计。

典型场景：

- 设计一个数字人声音。
- 为短视频账号生成品牌音色。
- 为游戏角色生成声音。
- 快速试出多种广告或客服音色。

### 13.3 音色命名建议

建议给 `display_name` 使用稳定、可读、可搜索的名称。

示例：

```markdown
brand-female-presenter
course-teacher-male
customer-service-clear
game-guide-young
english-commercial-premium
```

### 13.4 保存 voice_id

创建成功后，请保存：

- `voice_id`
- `display_name`
- `source_type`
- `preview_audio_url`
- `compatible_models`
- `created_at`

其中最重要的是 `voice_id`。后续 TTS 调用只需要传 `voice_id`。

### 13.5 生产环境调用建议

- 声音克隆和声音设计通常比普通 TTS 更慢，建议客户端设置较长超时时间。
- 不要在前端暴露 API Key。
- 建议由服务端调用 aijisu API。
- 对 `voice_id` 做业务侧保存，避免重复创建相同音色。
- 创建前确认音频和声音授权，避免克隆无授权声音。

---

# 数字人口播

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/avatar/digital-human
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/avatar/digital-human.md
Description: 使用一张图片和音频或 UniAll 音色 ID 创建 Kling V3 数字人视频。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

## 概览

可灵数字人统一使用稳定模型 `kling-v3`，并传入 `operation: avatar`。请求需要一张公开图片，以及音频 URL 或 UniAll `voice_id` 二选一；不要再使用历史 Kling Avatar 档位模型名。

UniAll 当前没有开放可灵主体库的创建和查询接口，因此普通公开请求不要传 `subject_ids`。

## 适用场景

- 已有口播音频时使用 `audio_url`。
- 需要使用 UniAll 音色列表或克隆接口返回的音色时使用 `voice_id`。
- 标准清晰度使用 `resolution: std`，更高清晰度使用 `resolution: pro`。

## 接口

| 操作 | 方法 | 路径 |
| --- | --- | --- |
| 创建数字人视频任务 | `POST` | `/v1/videos` |
| 查询视频任务 | `GET` | `/v1/videos/{task_id}` |
| 下载已完成的视频 | `GET` | `/v1/videos/{task_id}/content` |
| 查询可灵音色 | `GET` | `/v1/audio/voices?model=kling-v3` |
| 克隆可灵音色 | `POST` | `/v1/audio/voices/clone` |

## 鉴权

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 使用 `kling-v3`。 |
| `operation` | string | 是 | 使用 `avatar`。 |
| `prompt` | string | 是 | UniAll 视频接口要求提供的讲解、表情和镜头提示词。 |
| `image` | string | 是 | 数字人图片的公开 HTTP(S) URL。 |
| `audio_url` | string | 条件必填 | 公开口播音频 URL，与 `voice_id` 二选一。 |
| `voice_id` | string | 条件必填 | UniAll 音色 ID，与 `audio_url` 二选一。 |
| `resolution` | string | 否 | `std` 或 `pro`，默认 `std`。 |
| `watermark` | boolean | 否 | 是否添加 AIGC 水印。 |

不要传 `sound` 开关。`audio_url` 和 `voice_id` 是口型驱动输入，展示风格由提示词描述；同一个请求不要同时传入两个音色输入。

## 查询可用音色

```bash
curl "{BASE_URL}/v1/audio/voices?model=kling-v3" \
  -H "Authorization: Bearer sk-***"
```

使用音色列表响应中的 UniAll `voice_id`，不要传入上游音色 ID。

## 克隆音色

```bash
curl -X POST "{BASE_URL}/v1/audio/voices/clone" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "voice_name": "产品旁白",
    "audio_url": "https://example.com/voice-sample.mp3",
    "text": "这是克隆音色的试听文本。"
  }'
```

克隆成功后保存响应中的 UniAll `voice_id`，再用于数字人任务。

## 请求示例

### 使用音频 URL

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "operation": "avatar",
    "prompt": "自然讲解产品，表情友好，正面稳定镜头。",
    "image": "https://example.com/presenter.png",
    "audio_url": "https://example.com/speech.mp3",
    "resolution": "pro",
    "watermark": false
  }'
```

### 使用 UniAll 音色

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "operation": "avatar",
    "prompt": "专业讲解口吻，表情自然，正面稳定镜头。",
    "image": "https://example.com/presenter.png",
    "voice_id": "voice_xxxxxxxxxxxxx",
    "resolution": "std"
  }'
```

## 响应示例

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "kling-v3",
  "status": "queued",
  "progress": 0
}
```

## 任务状态与结果

保存 `id` 或 `task_id`，然后按照[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)中的公共规则，每 3 到 10 秒轮询一次，并处理终态、结果字段、错误和带鉴权下载。

## 计费说明

数字人视频通常结合 `kling-v3`、`operation: avatar`、`resolution` 和输出时长计费。音色克隆可能按照模型广场当前规则单独计费。任务提交时可能预扣，最终以任务结算和消费记录为准。

## 常见错误

- 使用历史数字人档位模型名，而不是 `kling-v3`。
- 缺少 `operation: avatar` 或必填的 `prompt`。
- 同时传入 `audio_url` 和 `voice_id`，或两者都没有传。
- 传入上游音色 ID，而不是 UniAll `voice_id`。
- 在公开主体库接口尚未开放时传入 `subject_ids`。
- 传入 `sound`、`duration`，或媒体 URL 无法由服务端公开访问。
- 一次轮询超时后重新提交付费任务，而不是继续查询原 `task_id`。

公共响应不会返回供应商名称、上游任务 ID、路由、凭证或上游原始请求。

## 相关页面

- [Kling 视频](/zh-CN/models/video/kling)
- [Kling 图片](/zh-CN/models/image/kling)
- [视频生成概览](/zh-CN/models/video/overview)

---

# 数字人概览

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/avatar/overview
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/avatar/overview.md
Description: UniAll 数字人口播文档入口。

本分类整理来源菜单中的数字人口播流程，以及用户提供的 Kling V3 调用口径。

## 包含页面

- [数字人口播](/zh-CN/models/avatar/digital-human)

## 接入建议

数字人口播使用 `kling-v3` 和 `operation: avatar`。提交一张数字人图片，并在音频 URL 和 UniAll `voice_id` 中二选一，随后轮询返回的 `task_id`，直到输出视频可用。

如果流程需要 `voice_id`，使用[数字人口播](/zh-CN/models/avatar/digital-human)页面中的可灵音色列表或克隆接口。

---

# 通用异步图像生成

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/image/async-image-generation
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/async-image-generation.md
Description: 通用异步图像生成来源文档。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

更新时间：2026-04-29

本文说明如何使用图片异步任务接口调用 NanoBanana 系列模型和 `gpt-image-2`，包括请求方式、参数、响应、计费规则和两类模型的差异。

## 1. 接口概览

### 1.1 提交异步图片任务

```http
POST /v1/images/tasks
```

支持：

- 文生图：`task_type = text2image`
- 图生图：`task_type = image2image`

### 1.2 查询异步图片任务

```http
GET /v1/images/tasks/{task_id}
```

### 1.3 认证方式

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## 2. 可用模型

### 2.1 NanoBanana 系列

上游 Nano 系列模型包括：

| 模型名 | 说明 |
| --- | --- |
| `NanoBanana` | NanoBanana 基础模型 |
| `NanoBanana2-0.5K` | NanoBanana2，0.5K 档 |
| `NanoBanana2-1K` | NanoBanana2，1K 档 |
| `NanoBanana2-2K` | NanoBanana2，2K 档 |
| `NanoBanana2-4K` | NanoBanana2，4K 档 |
| `NanoBananaPro-1K` | NanoBanana Pro，1K 档 |
| `NanoBananaPro-2K` | NanoBanana Pro，2K 档 |
| `NanoBananaPro-4K` | NanoBanana Pro，4K 档 |
| `NanoBananaPro-8K` | NanoBanana Pro，8K 档 |

注意：最终用户是否能调用某个模型，取决于平台后台是否已在通道和计费中启用该模型。
### 2.2 gpt-image-2

| 模型名 | 说明 |
| --- | --- |
| `gpt-image-2` | 按 `size + quality + n` 参数矩阵计费的图片模型 |

## 3. 通用请求参数

这些字段适用于 NanoBanana 系列和 `gpt-image-2`。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 模型名，例如 `NanoBanana2-0.5K`、`gpt-image-2` |
| `prompt` | string | 是 | 图片生成或编辑提示词 |
| `task_type` | string | 否 | `text2image` 或 `image2image`。不传时，后端会根据是否存在图片输入自动推断 |
| `image` | string / file | 图生图单图必填 | 单张参考图。JSON 中传图片 URL； |
| `images` | string[] | 图生图多图必填 | 多张参考图 URL，推荐多图统一使用这个字段 |
| `size` | string | 视模型而定 | 输出尺寸。`gpt-image-2` 必填，支持值见 [gpt-image-2 size 可选值](#gpt-image-2-size-options)；NanoBanana 系列优先使用 `aspect_ratio` 控制比例 |
| `aspect_ratio` | string | 部分模型可选 | `NanoBanana`、`NanoBananaPro-*`、`NanoBanana2-*` 支持，详见 [NanoBanana 系列能力差异](#nanobanana-capability-options)；`gpt-image-2` 不支持 |
| `quality` | string | 否 | 输出质量。`gpt-image-2` 支持值见 [gpt-image-2 quality 可选值](#gpt-image-2-quality-options)；NanoBanana 系列通常由模型档位决定 |
| `n` | integer | 否 | 生成数量。默认 `1`。`gpt-image-2` 允许 `1-8`；NanoBanana 不支持|
| `output_format` | string | 可选 | 控制输出图片类型。Nano 支持值见 [NanoBanana 系列能力差异](#nanobanana-capability-options)；`gpt-image-2` 支持值见 [gpt-image-2 output_format 可选值](#gpt-image-2-output-format-options) |


### 3.1 参考图传参口径

对外统一只推荐两个字段：

单图：

```json
{
  "image": "https://example.com/input.png"
}
```

多图：

```json
{
  "images": [
    "https://example.com/a.png",
    "https://example.com/b.png"
  ]
}
```

不要混用多个参考图字段。兼容旧字段仍会被解析并按顺序合并，混用可能导致重复参考图。新接入只使用 `image` 或 `images`。

任务类型推断规则：

- 没有图片输入：按 `text2image` 处理
- 有 `image` / `images` / multipart 图片文件：按 `image2image` 处理
- 显式传了 `task_type` 时，以显式值为准

## 4. NanoBanana 系列参数

NanoBanana 系列使用同一套异步图片任务请求结构。

### 4.1 文生图 JSON 请求

```json
{
  "model": "NanoBanana2-0.5K",
  "task_type": "text2image",
  "prompt": "A small red cube on a clean white desk, minimal product photo, soft daylight",
  "aspect_ratio": "1:1",
  "output_format": "png",
  "n": 1,
  "response_format": "url"
}
```

### 4.2 图生图 JSON 请求

```json
{
  "model": "NanoBanana2-0.5K",
  "task_type": "image2image",
  "prompt": "Turn the reference image into a clean product render",
  "image": "https://example.com/input.png",
  "aspect_ratio": "16:9",
  "output_format": "jpeg",
  "n": 1,
  "response_format": "url"
}
```

### 4.3 参数约束

| 参数 | NanoBanana 系列规则 |
| --- | --- |
| `model` | 传具体 Nano 模型名 |
| `prompt` | 必填 |
| `task_type` | `text2image` / `image2image`，可省略并由平台推断 |
| `aspect_ratio` | 推荐使用；控制输出比例。常见值包括 `1:1`、`16:9`、`9:16`、`4:3`、`3:4`，实际支持范围以上游模型为准 |
| `output_format` | 推荐使用；控制输出图片类型。`NanoBanana` 支持 `png` / `jpeg` / `webp`；`NanoBananaPro-*`、`NanoBanana2-*` 支持 `png` / `jpeg` |
| `size` | 不作为 NanoBanana 系列的主要控制参数；如传入，会按上游兼容能力处理 |
| `quality` | 不作为 NanoBanana 系列的平台计费维度；通常由模型档位决定 |
| `n` | 可选；默认 `1`。计费会按生成数量乘算，实际最大值以上游限制为准 |
| `response_format` | 推荐 `url` |
| 图片输入字段 | 单图用 `image`，多图用 `images`；multipart 上传文件时使用 `image` |

###### NanoBanana capability options

### 4.4 NanoBanana 系列能力差异

| 模型 | `aspect_ratio` | `output_format` |
| --- | --- | --- |
| `NanoBanana` | 支持 | 支持 `png` / `jpeg` / `webp` |
| `NanoBananaPro-*` | 支持 | 支持 `png` / `jpeg` |
| `NanoBanana2-*` | 支持 | 支持 `png` / `jpeg` |

### 4.5 计费

NanoBanana 系列按模型固定单价计费，再乘以生成数量 `n` 或实际上游返回的结果数量。

`aspect_ratio` 和 `output_format` 控制生成效果，不参与当前平台计费；不同 Nano 模型档位的基础单价由后台模型价格配置决定。

当前本地测试实例已启用 `NanoBanana2-0.5K`，具体消耗以平台后台价格配置和消费日志为准。

如果后台启用其他 NanoBanana 模型，需要分别配置对应模型价格。

## 5. gpt-image-2 参数

`gpt-image-2` 使用参数矩阵计费。`size` 是必填参数；`quality` 和 `n` 有默认值；`output_format` 可用于控制输出图片类型；不支持 `aspect_ratio`。

### 5.1 文生图 JSON 请求

```json
{
  "model": "gpt-image-2",
  "task_type": "text2image",
  "prompt": "A small blue glass sphere on a clean white desk, minimal product photo, soft daylight",
  "size": "1024x768",
  "quality": "low",
  "output_format": "webp",
  "n": 1,
  "response_format": "url"
}
```

### 5.2 图生图 JSON 请求

```json
{
  "model": "gpt-image-2",
  "task_type": "image2image",
  "prompt": "Keep the product shape, change the background to a bright studio scene",
  "image": "https://example.com/input.png",
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "png",
  "n": 1,
  "response_format": "url"
}
```

### 5.3 图生图 multipart 请求

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -F "model=gpt-image-2" \
  -F "task_type=image2image" \
  -F "prompt=Keep the subject, make it a clean studio product photo" \
  -F "size=1024x1024" \
  -F "quality=medium" \
  -F "output_format=png" \
  -F "n=1" \
  -F "response_format=url" \
  -F "image=@/path/to/input.png"
```

### 5.4 参数约束

| 参数 | 规则 |
| --- | --- |
| `size` | 必填，必须是 [gpt-image-2 size 可选值](#gpt-image-2-size-options) 中的值 |
| `aspect_ratio` | 不支持；请使用 `size` 控制输出尺寸和比例 |
| `quality` | 可选，默认 `medium`，支持值见 [gpt-image-2 quality 可选值](#gpt-image-2-quality-options) |
| `output_format` | 可选，支持值见 [gpt-image-2 output_format 可选值](#gpt-image-2-output-format-options) |
| `n` | 可选，默认 `1`，范围 `1-8` |
| `response_format` | 推荐 `url` |
| `task_type` | `text2image` / `image2image`，可省略并由平台推断 |

###### GPT Image 2 quality options

`quality` 支持值：

| 输入值 | 归一化后 |
| --- | --- |
| `low` | `low` |
| `medium` | `medium` |
| `high` | `high` |

###### GPT Image 2 output format options

`output_format` 支持值：

| 输入值 |
| --- |
| `png` |
| `jpeg` |
| `webp` |

###### GPT Image 2 size options

### 5.5 gpt-image-2 size 可选值

`gpt-image-2` 通过 `size` 控制输出尺寸和比例，不支持单独传 `aspect_ratio`。`quality` 可传 `low`、`medium`、`high`；`n` 会按生成数量计入最终消耗。

| Size | 比例 | 方向 | 备注档位 |
| --- | --- | --- | --- |
| `1024x768` | `4:3` | 横向 | `1K` |
| `768x1024` | `3:4` | 竖向 | `1K` |
| `1344x1024` | `4:3` | 横向 | `1K` |
| `1024x1344` | `3:4` | 竖向 | `1K` |
| `1280x1024` | `5:4` | 横向 | `1K` |
| `1024x1280` | `4:5` | 竖向 | `1K` |
| `1360x768` | `16:9` | 横向 | `1K` |
| `768x1360` | `9:16` | 竖向 | `1K` |
| `1536x864` | `16:9` | 横向 | `1K` |
| `864x1536` | `9:16` | 竖向 | `1K` |
| `1024x1024` | `1:1` | 正方形 | `1K` |
| `1536x1024` | `3:2` | 横向 | `1K` |
| `1024x1536` | `2:3` | 竖向 | `1K` |
| `2048x1024` | `2:1` | 横向 | `1K` |
| `1024x2048` | `1:2` | 竖向 | `1K` |
| `2016x864` | `21:9` | 横向 | `1K` |
| `864x2016` | `9:21` | 竖向 | `1K` |
| `1920x1080` | `16:9` | 横向 | `2K` |
| `1080x1920` | `9:16` | 竖向 | `2K` |
| `1536x1536` | `1:1` | 正方形 | `2K` |
| `2048x1360` | `3:2 近似` | 横向 | `2K` |
| `1360x2048` | `2:3 近似` | 竖向 | `2K` |
| `2048x1536` | `4:3` | 横向 | `2K` |
| `1536x2048` | `3:4` | 竖向 | `2K` |
| `2160x1440` | `3:2` | 横向 | `2K` |
| `1440x2160` | `2:3` | 竖向 | `2K` |
| `2048x1152` | `16:9` | 横向 | `2K` |
| `1152x2048` | `9:16` | 竖向 | `2K` |
| `2688x1344` | `2:1` | 横向 | `2K` |
| `1344x2688` | `1:2` | 竖向 | `2K` |
| `2688x1152` | `21:9` | 横向 | `2K` |
| `1152x2688` | `9:21` | 竖向 | `2K` |
| `2560x1440` | `16:9` | 横向 | `2K` |
| `1440x2560` | `9:16` | 竖向 | `2K` |
| `2048x2048` | `1:1` | 正方形 | `4K` |
| `2560x2048` | `5:4` | 横向 | `2K` |
| `2048x2560` | `4:5` | 竖向 | `2K` |
| `2880x2880` | `1:1` | 正方形 | `4K` |
| `3264x2448` | `4:3` | 横向 | `4K` |
| `2448x3264` | `3:4` | 竖向 | `4K` |
| `3504x2336` | `3:2` | 横向 | `4K` |
| `2336x3504` | `2:3` | 竖向 | `4K` |
| `3840x1920` | `2:1` | 横向 | `4K` |
| `1920x3840` | `1:2` | 竖向 | `4K` |
| `3840x1648` | `21:9 近似` | 横向 | `4K` |
| `1648x3840` | `9:21 近似` | 竖向 | `4K` |
| `3840x2160` | `16:9` | 横向 | `4K` |
| `2160x3840` | `9:16` | 竖向 | `4K` |

## 6. 提交响应

提交成功后返回任务对象。

```json
{
  "task_id": "task_xxx",
  "status": "succeeded",
  "progress": "100%",
  "result_url": "https://example.com/result.png",
  "metadata": {
    "task_type": "text2image",
    "result_count": 1
  },
  "error": null
}
```

字段说明：

| 字段 | 说明 |
| --- | --- |
| `task_id` | 平台任务 ID，用于后续查询 |
| `status` | `queued`、`processing`、`succeeded`、`failed` |
| `progress` | 任务进度，例如 `0%`、`50%`、`100%` |
| `result_url` | 第一张结果图 URL |
| `metadata.task_type` | 任务类型 |
| `metadata.result_count` | 结果数量 |
| `metadata.result_urls` | 多结果时返回 URL 数组 |
| `error` | 失败时包含错误信息，成功时为 `null` |

## 7. 查询响应

```bash
curl "{BASE_URL}/v1/images/tasks/task_xxx" \
  -H "Authorization: Bearer sk-***"
```

成功响应：

```json
{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxx",
    "status": "succeeded",
    "progress": "100%",
    "result_url": "https://example.com/result.png",
    "metadata": {
      "task_type": "text2image",
      "result_count": 1
    },
    "error": null
  }
}
```

建议客户端轮询间隔为 `2-5` 秒。任务进入 `succeeded` 或 `failed` 后可停止轮询。

## 8. 完整 curl 示例

### 8.1 NanoBanana 文生图

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "NanoBanana2-0.5K",
    "task_type": "text2image",
    "prompt": "A small red cube on a clean white desk, minimal product photo, soft daylight",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "n": 1,
    "response_format": "url"
  }'
```

### 8.2 gpt-image-2 文生图

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "task_type": "text2image",
    "prompt": "A small blue glass sphere on a clean white desk, minimal product photo, soft daylight",
    "size": "1024x768",
    "quality": "low",
    "output_format": "webp",
    "n": 1,
    "response_format": "url"
  }'
```

### 8.3 查询任务

```bash
curl "{BASE_URL}/v1/images/tasks/task_xxx" \
  -H "Authorization: Bearer sk-***"
```

## 9. NanoBanana 与 gpt-image-2 差异

| 对比项 | NanoBanana 系列 | `gpt-image-2` |
| --- | --- | --- |
| 模型列表 | 多个模型名区分基础版、Pro 和分辨率档位 | 单一模型名 |
| 当前本地已启用 | `NanoBanana2-0.5K` | `gpt-image-2` 已实测可用 |
| 计费方式 | 模型固定单价 * 生成数量 | `size + quality` 参数计费 * `n` |
| 比例控制 | 支持 `aspect_ratio`，例如 `1:1`,`2:3`,`3:2`,`3:4`,`4:3`,`4:5`,`5:4`,`9:16`,`16:9`,`21:9` | 不支持 `aspect_ratio`；使用 `size`，例如 `1024x768`、`1024x1024` |
| 输出格式控制 | `NanoBanana` 支持 `png` / `jpeg` / `webp`；`NanoBananaPro-*`、`NanoBanana2-*` 支持 `png` / `jpeg` | 支持 `png` / `jpeg` / `webp` |
| `size` | 不作为主要控制参数；模型档位和 `aspect_ratio` 更关键 | 必填，且必须命中 [gpt-image-2 size 可选值](#gpt-image-2-size-options) |
| `quality` | 不作为平台计费维度；通常由模型档位决定 | 可选，默认 `medium`，参与计费 |
| `n` | 可选，默认 `1`，最大值以上游限制为准 | 可选，默认 `1`，范围 `1-8` |
| `response_format` | 推荐 `url` | 推荐 `url` |
| 图生图 | 单图用 `image`，多图用 `images`，传参考图即走图生图/编辑路径 | 单图用 `image`，多图用 `images`，传参考图即走图生图/编辑路径 |


## 10. 最小接入流程

1. 使用 `POST /v1/images/tasks` 提交任务。
2. 保存返回的 `task_id`。
3. 使用 `GET /v1/images/tasks/{task_id}` 轮询任务。
4. 当 `status = succeeded` 时读取 `result_url`。

---

# GPT-Image-2

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/image/gpt-image-2
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/gpt-image-2.md
Description: 通过 UniAll 图像 API 调用 gpt-image-2 生成或编辑图片。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

`gpt-image-2` 可通过 OpenAI 兼容图像接口进行文生图和图像编辑。该模型使用 `size` 同时控制尺寸和画幅比例，不支持 `aspect_ratio`。

## Endpoint

```http
POST /v1/images/generations
POST /v1/images/edits
```

文生图使用 `/v1/images/generations`。包含参考图的编辑请求使用 `/v1/images/edits`。

## Authentication

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 固定使用 `gpt-image-2`。 |
| `prompt` | string | 是 | 图片生成或编辑提示词。 |
| `image` | string/object | 条件必填 | 编辑图片时的参考图。 |
| `images` | array | 条件必填 | 支持多图时使用的参考图数组。 |
| `size` | string | 是 | 输出尺寸，必须使用支持的尺寸值。 |
| `quality` | string | 否 | `low`、`medium` 或 `high`。默认 `medium`。 |
| `output_format` | string | 否 | `png`、`jpeg` 或 `webp`。 |
| `n` | integer | 否 | 输出图片数量，默认 `1`，范围为 `1` 到 `8`。 |
| `response_format` | string | 否 | 生成资产建议使用 `url`。 |

## 支持尺寸

常用尺寸：

| 尺寸 | 比例 | 档位 |
| --- | --- | --- |
| `1024x768` | `4:3` | `1K` |
| `768x1024` | `3:4` | `1K` |
| `1024x1024` | `1:1` | `1K` |
| `1536x864` | `16:9` | `1K` |
| `864x1536` | `9:16` | `1K` |
| `1920x1080` | `16:9` | `2K` |
| `1080x1920` | `9:16` | `2K` |
| `1536x1536` | `1:1` | `2K` |
| `2048x2048` | `1:1` | `4K` |
| `3840x2160` | `16:9` | `4K` |
| `2160x3840` | `9:16` | `4K` |

完整启用尺寸矩阵以产品模型配置为准。

## 文生图示例

```bash
curl -X POST "{BASE_URL}/v1/images/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A small blue glass sphere on a clean white desk, minimal product photo, soft daylight",
    "size": "1024x768",
    "quality": "low",
    "output_format": "webp",
    "n": 1,
    "response_format": "url"
  }'
```

## 图像编辑示例

```bash
curl -X POST "{BASE_URL}/v1/images/edits" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Keep the product shape, change the background to a bright studio scene",
    "image": "https://example.com/input.png",
    "size": "1024x1024",
    "quality": "medium",
    "output_format": "png",
    "n": 1,
    "response_format": "url"
  }'
```

## 响应示例

```json
{
  "created": 1778688000,
  "data": [
    {
      "url": "https://example.com/generated.png"
    }
  ]
}
```

## 计费说明

`gpt-image-2` 使用 `size + quality` 参数矩阵计费，并乘以 `n`。`output_format` 控制文件格式，在当前来源范围内不是独立计费维度。

## 常见错误

- 缺少 `size`。
- 传入 `aspect_ratio`；该模型应使用 `size`。
- `quality` 不在 `low`、`medium`、`high` 范围内。
- `n` 不在 `1` 到 `8` 范围内。
- 使用了当前账号不支持的尺寸。

## 相关页面

- [图像生成概览](/zh-CN/models/image/overview)
- [通用异步图像生成](/zh-CN/models/image/async-image-generation)
- [Seedream 图像生成](/zh-CN/models/image/seedream)

---

# GPT-Image-2.5

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/image/gpt-image-2-5
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/gpt-image-2-5.md
Description: 通过 UniAI 同步图像接口调用 GPT Image 2.5 生成和编辑图片。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

GPT Image 2.5 提供两个公开模型 ID：

- `gpt-image-2.5-flare`
- `gpt-image-2.5-sunburst`

两个模型使用相同的 OpenAI 兼容同步图像契约。文生图使用 `/v1/images/generations`；请求包含参考图时，使用 `/v1/images/edits`。

当前 API Key 可用的模型，以 `GET /v1/models` 返回的模型列表为准。

## 适用场景

GPT Image 2.5 适合：

- 同步文生图；
- 使用一张或多张参考图进行图片编辑；
- 调整输出尺寸、质量和格式；
- 获取 URL 或 Base64 图片响应。

## 接口

```http
GET /v1/models
POST /v1/images/generations
POST /v1/images/edits
```

图片接口会等待上游结果，并在同一个响应中返回生成图片，不会创建需要轮询的任务。

## 鉴权

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

也可以使用以下兼容 Header：

```http
x-api-key: sk-***
```

## 模型可用性

```bash
curl "{BASE_URL}/v1/models" \
  -H "Authorization: Bearer sk-***"
```

成功响应会列出当前 API Key 可见的模型 ID：

```json
{
  "object": "list",
  "data": [
    {
      "id": "gpt-image-2.5-flare",
      "object": "model",
      "created": 0,
      "owned_by": "uniall"
    },
    {
      "id": "gpt-image-2.5-sunburst",
      "object": "model",
      "created": 0,
      "owned_by": "uniall"
    }
  ]
}
```

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `gpt-image-2.5-flare` 或 `gpt-image-2.5-sunburst`。 |
| `prompt` | string | 是 | 生成或编辑指令，最长 32,000 个字符。 |
| `size` | string | 否 | `auto` 或 `WIDTHxHEIGHT`，默认 `auto`。 |
| `quality` | string | 否 | `auto`、`low`、`medium`、`high`、`xhigh` 或 `max`，默认 `auto`。 |
| `n` | integer | 否 | 输出图片数量，默认 `1`，范围为 `1` 到 `10`。 |
| `output_format` | string | 否 | `png`、`jpeg` 或 `webp`，默认 `png`。 |
| `response_format` | string | 否 | `url` 或 `b64_json`，默认 `b64_json`。 |
| `images` | array | 条件必填 | `/v1/images/edits` 的 JSON 参考图数组，每项使用 `{"image_url":"..."}`。 |
| `mask` | object | 否 | `/v1/images/edits` 的 JSON 蒙版，使用 `{"image_url":"..."}`，作用于第一张参考图。 |

## 尺寸规则

显式传入 `WIDTHxHEIGHT` 时：

- 宽和高必须是正整数，且都是 `16` 的倍数；
- 长边不能超过 `3840` 像素；
- 宽高比不能超过 `3:1`；
- 总像素必须在 `655,360` 到 `8,294,400` 之间。

如果希望根据请求和参考图上下文自动选择尺寸，使用 `auto`。

## 文生图示例

```bash
curl -X POST "{BASE_URL}/v1/images/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "白色桌面上的红色陶瓷杯，棚拍产品照片，不要文字",
    "size": "1024x1024",
    "quality": "medium",
    "output_format": "png",
    "n": 1,
    "response_format": "url"
  }'
```

## JSON 图片编辑示例

请求包含一张或多张参考图时，使用 `/v1/images/edits`。

```bash
curl -X POST "{BASE_URL}/v1/images/edits" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "保留产品主体，将背景替换为明亮的摄影棚场景",
    "images": [
      {"image_url": "https://example.com/product.png"}
    ],
    "size": "auto",
    "quality": "high",
    "output_format": "png",
    "response_format": "url"
  }'
```

每张 JSON 参考图使用 HTTP(S) 图片 URL，或 PNG、JPEG、WebP Base64 Data URL。单次请求最多可以传入 16 张参考图。

## Base64 图片编辑示例

使用 JSON 编辑请求时，将参考图作为完整的 Base64 Data URL 传入 `images[].image_url`。

```bash
curl -X POST "{BASE_URL}/v1/images/edits" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "保留产品主体，将背景替换为明亮的摄影棚场景",
    "images": [
      {
        "image_url": "data:image/png;base64,BASE64_IMAGE_DATA"
      }
    ],
    "size": "1024x1024",
    "quality": "high",
    "output_format": "png",
    "response_format": "url"
  }'
```

Data URL 必须包含 MIME 前缀，例如 `data:image/png;base64,...`、`data:image/jpeg;base64,...` 或 `data:image/webp;base64,...`。

## multipart 图片编辑

本地文件建议使用 multipart。多张参考图可以重复传入 `image[]`。

```bash
curl -X POST "{BASE_URL}/v1/images/edits" \
  -H "Authorization: Bearer sk-***" \
  -F "model=gpt-image-2.5-sunburst" \
  -F "prompt=保留主体，将背景改成浅蓝色" \
  -F "image[]=@product.png" \
  -F "response_format=url"
```

multipart 蒙版可以使用 `mask=@mask.png`。蒙版必须是带 Alpha 通道的 PNG，小于 4 MB，并且与第一张参考图尺寸一致。

## 响应示例

```json
{
  "created": 1789121337,
  "size": "1024x1024",
  "output_format": "png",
  "data": [
    {
      "url": "https://api.uniall.ai/generated-media/example.png"
    }
  ],
  "usage": {
    "prompt_tokens": 23,
    "completion_tokens": 425,
    "total_tokens": 448,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 23,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 0
    },
    "usage_source": "upstream_response"
  }
}
```

当 `response_format` 为 `b64_json` 时，每个 `data` 项返回 `b64_json` 而不是 `url`。该值是纯 Base64 内容，不包含 `data:image/...;base64,` 前缀。

## Base64 响应示例

如果应用需要在 JSON 响应中直接获取图片字节，将 `response_format` 设置为 `b64_json`。

```bash
curl -X POST "{BASE_URL}/v1/images/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "白色桌面上的红色陶瓷杯，棚拍产品照片",
    "size": "1024x1024",
    "quality": "medium",
    "output_format": "png",
    "response_format": "b64_json"
  }'
```

响应中的 `b64_json` 是纯 Base64 内容，不包含 `data:image/...;base64,` 前缀：

```json
{
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}
```

## 相关页面

- [图像生成概览](/zh-CN/models/image/overview)
- [GPT-Image-2](/zh-CN/models/image/gpt-image-2)
- [模型列表](/zh-CN/models)

---

# 编辑图像

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/image/gpt-image-2/openai-edit
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/gpt-image-2/openai-edit.md
Description: GPT-Image-2 编辑图像接口。

公共模型名称为`gpt-image-2-auto`，按返回图片分辨率 / 质量 / 张数计费，API调用参考下方，size 可选  `auto`
计费模式： 根据生成真实图片尺寸计费，在异步模式下预扣费用，结果返回时回算，多退少补


## `gpt-image-2-origin`开放尺寸
计费模式：按size精准扣费

### 1K

| 比例 | 横向 | 竖向 | 方向 |
| --- | --- | --- | --- |
| `4:3 / 3:4` | `1024x768`, `1344x1024` | `768x1024`, `1024x1344` | 横/竖 |
| `5:4 / 4:5` | `1280x1024` | `1024x1280` | 横/竖 |
| `16:9 / 9:16` | `1360x768`, `1536x864` | `768x1360`, `864x1536` | 横/竖 |
| `1:1` | `1024x1024` | - | 正方形 |
| `3:2 / 2:3` | `1536x1024` | `1024x1536` | 横/竖 |
| `2:1 / 1:2` | `2048x1024` | `1024x2048` | 横/竖 |
| `21:9 / 9:21` | `2016x864` | `864x2016` | 横/竖 |

### 2K

| 比例 | 横向 | 竖向 | 方向 |
| --- | --- | --- | --- |
| `16:9 / 9:16` | `1920x1080`, `2048x1152`, `2560x1440` | `1080x1920`, `1152x2048`, `1440x2560` | 横/竖 |
| `1:1` | `1536x1536` | - | 正方形 |
| `3:2 / 2:3` | `2048x1360`, `2160x1440` | `1360x2048`, `1440x2160` | 横/竖 |
| `4:3 / 3:4` | `2048x1536` | `1536x2048` | 横/竖 |
| `2:1 / 1:2` | `2688x1344` | `1344x2688` | 横/竖 |
| `21:9 / 9:21` | `2688x1152` | `1152x2688` | 横/竖 |
| `5:4 / 4:5` | `2560x2048` | `2048x2560` | 横/竖 |

### 4K

| 比例 | 横向 | 竖向 | 方向 |
| --- | --- | --- | --- |
| `1:1` | `2048x2048`, `2880x2880` | - | 正方形 |
| `4:3 / 3:4` | `3264x2448` | `2448x3264` | 横/竖 |
| `3:2 / 2:3` | `3504x2336` | `2336x3504` | 横/竖 |
| `2:1 / 1:2` | `3840x1920` | `1920x3840` | 横/竖 |
| `21:9 / 9:21` | `3840x1648` | `1648x3840` | 横/竖 |
| `16:9 / 9:16` | `3840x2160` | `2160x3840` | 横/竖 |

## 接口参数与示例

### Endpoint


```http
POST /v1/images/edits/
```
### 请求体参数

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |


### 响应字段

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |


### 响应示例

#### 示例 1

```json
{
  "created": 1777107492,
  "data": [
    {
      "url": "https://xxxxx.com/xxxx.png"
    }
  ]
}
```

---

# 生成图像

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/image/gpt-image-2/openai-generate
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/gpt-image-2/openai-generate.md
Description: GPT-Image-2 生成图像接口。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

公共模型名称为`gpt-image-2-auto`，按返回图片分辨率 / 质量 / 张数计费，API调用参考下方，size 可选  `auto`
计费模式： 根据生成真实图片尺寸计费，在异步模式下预扣费用，结果返回时回算，多退少补


## `gpt-image-2-origin`开放尺寸
计费模式：按size精准扣费

### 1K

| 比例 | 横向 | 竖向 | 方向 |
| --- | --- | --- | --- |
| `4:3 / 3:4` | `1024x768`, `1344x1024` | `768x1024`, `1024x1344` | 横/竖 |
| `5:4 / 4:5` | `1280x1024` | `1024x1280` | 横/竖 |
| `16:9 / 9:16` | `1360x768`, `1536x864` | `768x1360`, `864x1536` | 横/竖 |
| `1:1` | `1024x1024` | - | 正方形 |
| `3:2 / 2:3` | `1536x1024` | `1024x1536` | 横/竖 |
| `2:1 / 1:2` | `2048x1024` | `1024x2048` | 横/竖 |
| `21:9 / 9:21` | `2016x864` | `864x2016` | 横/竖 |

### 2K

| 比例 | 横向 | 竖向 | 方向 |
| --- | --- | --- | --- |
| `16:9 / 9:16` | `1920x1080`, `2048x1152`, `2560x1440` | `1080x1920`, `1152x2048`, `1440x2560` | 横/竖 |
| `1:1` | `1536x1536` | - | 正方形 |
| `3:2 / 2:3` | `2048x1360`, `2160x1440` | `1360x2048`, `1440x2160` | 横/竖 |
| `4:3 / 3:4` | `2048x1536` | `1536x2048` | 横/竖 |
| `2:1 / 1:2` | `2688x1344` | `1344x2688` | 横/竖 |
| `21:9 / 9:21` | `2688x1152` | `1152x2688` | 横/竖 |
| `5:4 / 4:5` | `2560x2048` | `2048x2560` | 横/竖 |

### 4K

| 比例 | 横向 | 竖向 | 方向 |
| --- | --- | --- | --- |
| `1:1` | `2048x2048`, `2880x2880` | - | 正方形 |
| `4:3 / 3:4` | `3264x2448` | `2448x3264` | 横/竖 |
| `3:2 / 2:3` | `3504x2336` | `2336x3504` | 横/竖 |
| `2:1 / 1:2` | `3840x1920` | `1920x3840` | 横/竖 |
| `21:9 / 9:21` | `3840x1648` | `1648x3840` | 横/竖 |
| `16:9 / 9:16` | `3840x2160` | `2160x3840` | 横/竖 |

## 接口参数与示例

### Endpoint


```http
POST /v1/images/generations/
```
### 请求体参数

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `model` | string | No |  | 用于图像生成的模型。 `gpt-image-2-origin` |
| `prompt` | string | Yes |  | 所需图像的文本描述。`gpt-image-1` 的最大长度为 32000 个字符，`dall-e-2` 的最大长度为 1000 个字符，`dall-e-3` 的最大长度为 4000 个字符。 |
| `size` | string | No |  | 生成的图像的大小。对于 gpt-image-2，size 必须是 1024x768（横向）、1024x1024（方形）、1024x1536（纵向）、1920x1080（横向）、2560x1440（横向）或 3840x2160（横向）之一； |
| `quality` | string | No |  | 将生成的图像的质量。可选：`low `, `medium `, `high` |
| `output_format` | string | No |  | 输出图片格式。可选:`png / jpeg / webp`, 默认“png” |
| `n` | string | Yes |  |  |

### 请求示例

#### 示例

```json
{
  "model": "gpt-image-2-origin",
  "prompt": "A cute baby sea otter",
  "size": "1024x1536",
  "quality": "medium",
  "output_format": "png"
}
```

```bash
curl -X POST "{BASE_URL}/v1/images/generations/" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-origin",
    "prompt": "A cute baby sea otter",
    "size": "1024x1536",
    "quality": "medium",
    "output_format": "png"
}'
```
### 响应字段

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `created` | integer | Yes |  |  |
| `data` | array | Yes |  |  |
| `usage` | object | Yes |  |  |

### 响应示例

#### 成功示例

```json
{
  "created": 1777105463,
  "data": [
    {
      "url": "https://xxxxxx/xxx.jpg"
    }
  ]
}
```

---

# Kling

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/image/kling
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/kling.md
Description: 通过 UniAll 异步图片任务调用可灵 V3、Omni 和 Image O1 生成及编辑图片。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

## 概览

可灵图片能力统一使用 `POST /v1/images/tasks`。通过 `operation` 选择生成方式，通过请求体顶层的 `resolution` 选择清晰度，通过 `num_images` 选择输出数量。

| 模型 | 图片能力 | 清晰度 |
| --- | --- | --- |
| `kling-v3` | 文生图、单图编辑、扩图、主体图补全 | `1k`、`2k` |
| `kling-v3-omni` | 文生图、单图编辑、多图参考、组图 | `1k`、`2k`、`4k` |
| `kling-image-o1` | 文生图、单图编辑、多图参考、组图 | `1k`、`2k`、`4k` |

模型是否可用取决于模型广场、API Key 的模型权限和当前启用的路由。

## 适用场景

- 文生图、单图编辑、扩图或根据一张正面图补全主体时使用 `kling-v3`。
- 需要最多四张参考图、`4k` 或组图结果时使用 `kling-v3-omni`。
- 需要相同的多图请求结构、且只使用图片模型时使用 `kling-image-o1`。

## 接口

| 操作 | 方法 | 路径 |
| --- | --- | --- |
| 创建异步图片任务 | `POST` | `/v1/images/tasks` |
| 查询图片任务 | `GET` | `/v1/images/tasks/{task_id}` |

## 鉴权

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## 清晰度与比例

在请求体顶层传入 `resolution`，不要使用 `size` 代替。默认值为 `1k`；`outpaint` 和 `complete_subject` 不要传 `resolution`。

- V3 支持 `16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`3:2`、`2:3` 和 `21:9`。
- Omni 和 Image O1 除上述比例外还支持 `auto`。

## 生成方式

| `operation` | 支持模型 | 必要输入 |
| --- | --- | --- |
| `text_to_image` | V3、Omni、Image O1 | 无输入图 |
| `image_edit` | V3、Omni、Image O1 | 一张 `image` |
| `reference_to_image` | Omni、Image O1 | `images` 传两到四张参考图 |
| `outpaint` | V3 | 一张 `image` 和 `outpaint` |
| `complete_subject` | V3 | 一张正面 `image` |

`kling-v3` 不接受两张原始图片用于 `reference_to_image`。多图参考应使用 `kling-v3-omni` 或 `kling-image-o1`。

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `kling-v3`、`kling-v3-omni` 或 `kling-image-o1`。 |
| `task_type` | string | 是 | 文生图使用 `text2image`；其他图片 operation 使用 `image2image`。 |
| `operation` | string | 是 | 上表中的生成方式。 |
| `prompt` | string | 是 | UniAll 异步图片接口要求提供的提示词。 |
| `image` | string | 条件必填 | 单图 operation 使用的一张公开图片 URL。 |
| `images` | string[] | 条件必填 | 多图参考使用的两到四张公开图片 URL。 |
| `resolution` | string | 否 | `1k`、`2k` 或模型支持的 `4k`；默认 `1k`。扩图和主体补全不要传。 |
| `aspect_ratio` | string | 否 | 输出比例；支持的图片编辑请求可使用 `auto`。 |
| `num_images` | integer | 否 | 输出数量，范围为 `1` 到 `9`。 |
| `negative_prompt` | string | 否 | V3 文生图的反向提示词。 |
| `result_type` | string | 否 | Omni 和 Image O1 可使用 `single` 或 `series`。 |
| `outpaint` | object | 条件必填 | `outpaint` 使用的四方向扩展倍率。 |
| `watermark` | boolean | 否 | 是否添加 AIGC 水印。 |

## 请求示例

### V3 文生图

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "task_type": "text2image",
    "operation": "text_to_image",
    "prompt": "电影感产品摄影，一只银色腕表放在黑色石材展台上。",
    "negative_prompt": "模糊，变形，文字，水印",
    "resolution": "2k",
    "aspect_ratio": "16:9",
    "num_images": 1,
    "watermark": false
  }'
```

### V3 单图编辑

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "task_type": "image2image",
    "operation": "image_edit",
    "prompt": "保持人物身份，把背景替换为干净的摄影棚。",
    "image": "https://example.com/person.png",
    "resolution": "2k",
    "aspect_ratio": "3:4",
    "num_images": 1
  }'
```

### Omni 多图参考 4K

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-omni",
    "task_type": "image2image",
    "operation": "reference_to_image",
    "prompt": "以第一张图为主体，参考第二张图的服装和色彩，生成统一的电影感肖像。",
    "images": [
      "https://example.com/person.png",
      "https://example.com/style.png"
    ],
    "resolution": "4k",
    "aspect_ratio": "16:9",
    "num_images": 1,
    "result_type": "single"
  }'
```

`kling-image-o1` 使用相同的多图参考结构，只需修改 `model`。

### V3 扩图

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "task_type": "image2image",
    "operation": "outpaint",
    "prompt": "自然延展海滩和天空，保持原图光线与透视。",
    "image": "https://example.com/source.png",
    "outpaint": {
      "up_expansion_ratio": 0.2,
      "down_expansion_ratio": 0,
      "left_expansion_ratio": 0.1,
      "right_expansion_ratio": 0.1
    },
    "num_images": 1,
    "watermark": false
  }'
```

每个扩图倍率必须在 `0` 到 `2` 之间，至少一个方向大于 `0`，扩展后的总面积不能超过原图的三倍。扩图不要传 `resolution`。

### V3 主体图补全

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "task_type": "image2image",
    "operation": "complete_subject",
    "prompt": "补全人物主体图。",
    "image": "https://example.com/front.png"
  }'
```

主体图补全只接受一张正面图，不传 `resolution`、`aspect_ratio` 或 `num_images`。`prompt` 用于满足 UniAll 图片任务的通用请求要求，不会代替图片输入。

## 响应示例

```json
{
  "task_id": "task_xxxxxxxxxxxxx",
  "status": "queued",
  "progress": "0%",
  "result_url": "",
  "metadata": {
    "task_type": "image2image"
  },
  "error": null
}
```

## 任务状态与结果

每 3 到 10 秒调用 `GET /v1/images/tasks/{task_id}`，直到任务进入 `succeeded` 或 `failed`。查询响应外层为 `code` 和 `data`；成功后读取 `data.result_url`，多图结果同时读取 `data.metadata.result_urls`。

不要因为一次查询超时就重新提交付费任务，应继续查询原 `task_id`。公共异步图片响应流程参见[通用异步图像生成](/zh-CN/models/image/async-image-generation)。

## 计费说明

图片通常结合公共模型、`operation`、`resolution`、输入图片数和输出图片数计费。任务提交时可能预扣，最终以任务结算记录和模型广场当前价格为准。

## 常见错误

- 使用 `size` 代替 `resolution`。
- 给 `kling-v3` 传入 `4k`。
- 使用 `kling-v3` 和两张原始图片调用 `reference_to_image`。
- 混用 `image`、`images` 和 `reference_image_urls`，重复提交同一输入。
- 给 `outpaint` 或 `complete_subject` 传入 `resolution`。
- 媒体 URL 无法由服务端公开访问。
- 查询超时后重新提交，而不是继续轮询原任务。

公共响应不会返回供应商名称、上游任务 ID、路由、凭证或上游原始请求。

## 相关页面

- [Kling 视频](/zh-CN/models/video/kling)
- [通用异步图像生成](/zh-CN/models/image/async-image-generation)
- [数字人口播](/zh-CN/models/avatar/digital-human)

---

# Nano 系列

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/image/nano-series
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/nano-series.md
Description: 选择 Nano Banana 模型、分辨率以及 OpenAI 或 Gemini 兼容的图片调用方式。

Nano 系列支持文生图以及使用一张或多张参考图进行编辑。UniAll 使用同一 API Key 提供两种请求风格，请按现有客户端和结果格式选择其中一种。

## 选择接口风格

| 使用场景 | 推荐文档 | 结果格式 |
| --- | --- | --- |
| 已使用 OpenAI Images 客户端、需要图片 URL 或异步任务 | [OpenAI Images 格式](./nano-series/openai-format) | `data[].url` 中的 URL |
| 已使用 Gemini 客户端，或需要 Base64 图片输入与输出 | [Gemini generateContent 格式](./nano-series/gemini-format) | `candidates[].content.parts[].inlineData.data` 中的 Base64 |

两种方式都使用 `https://api.uniall.ai` 和同一份 UniAll API Key。不要混用两种格式的参数名。

## 推荐模型

| 模型 | 可用分辨率 | 默认值 | 推荐场景 |
| --- | --- | --- | --- |
| `nano-banana-2` | `0.5k`、`1k`、`2k`、`4k` | `1k` | 通用生成、图片编辑和快速 0.5K 预览。 |
| `nano-banana-pro` | `1k`、`2k`、`4k` | `1k` | 更高细节的生成与编辑。 |
| `nano-banana-2-lite` | `1k` | `1k` | 轻量 1K 任务。 |

新接入请使用这些统一的小写模型 ID。实际可用范围取决于账号已启用的模型。

## 支持的输出比例

三个模型均支持：

```markdown
1:1  2:3  3:2  3:4  4:3  4:5  5:4  9:16  16:9  21:9
```

两种接口风格的分辨率字段不同：

| 输出规格 | OpenAI Images | Gemini generateContent |
| --- | --- | --- |
| 0.5K | `resolution: "0.5k"` | `imageSize: "512"` |
| 1K | `resolution: "1k"` | `imageSize: "1K"` |
| 2K | `resolution: "2k"` | `imageSize: "2K"` |
| 4K | `resolution: "4k"` | `imageSize: "4K"` |

0.5K 仅适用于 `nano-banana-2`。不要传 `512K`，Gemini 的 `imageSize` 也不要传 `0.5k`。

## 旧版兼容模型名

`NanoBanana2-1K`、`NanoBananaPro-2K` 等固定分辨率模型名可能仍可兼容使用，但这些属于已弃用的兼容别名，可能随时移除。新接入应使用统一模型 ID，并在请求参数中选择分辨率。

## 接入检查清单

- `n` 保持为 `1`，当前每次请求只生成一张图片。
- OpenAI 风格的参考图使用服务端可访问的 HTTP(S) URL 或完整 Data URL。
- Gemini 的 `inlineData.data` 只放纯 Base64，不要包含 `data:image/...;base64,` 前缀。
- 同步调用可按需把客户端超时设置到 600 秒。
- 客户端超时后不要立刻重复提交，原任务仍可能完成。
- 如需长期保留结果，请及时把临时结果 URL 转存到自己的存储。
- 日志中不要记录 API Key 或完整图片 Base64。

## 计费说明

计费取决于所选模型和分辨率。生产调用前请以账号当前可见的模型价格为准。客户端超时不代表生成或计费已经停止。

## 相关页面

- [OpenAI Images 格式](./nano-series/openai-format)
- [Gemini generateContent 格式](./nano-series/gemini-format)
- [通用异步图像生成](/zh-CN/models/image/async-image-generation)

---

# Gemini generateContent 格式

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/image/nano-series/gemini-format
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/nano-series/gemini-format.md
Description: 使用 Gemini 兼容的 generateContent 接口生成和编辑 Nano 系列图片。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

已有 Gemini 风格客户端，或需要 Base64 图片输入与输出时使用此格式。模型名放在 URL 中，图片参数放在 `generationConfig.imageConfig` 中。

## 接口

```http
POST /v1beta/models/{model}:generateContent
```

将 `{model}` 替换为 `nano-banana-2`、`nano-banana-pro` 或 `nano-banana-2-lite`。

## 鉴权

```http
x-api-key: sk-***
Content-Type: application/json
```

OpenAI Images 和 Gemini 两种格式使用同一份 UniAll API Key。

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `contents` | array | 是 | 包含一条用户消息的对话内容。 |
| `contents[].role` | string | 是 | 使用 `user`。 |
| `contents[].parts[].text` | string | 是 | 生成或编辑指令。 |
| `contents[].parts[].inlineData` | object | 条件必填 | 编辑使用的参考图；多图时重复此 part。 |
| `inlineData.mimeType` | string | 条件必填 | 图片媒体类型，例如 `image/png`。 |
| `inlineData.data` | string | 条件必填 | 不带 Data URL 前缀的纯 Base64。 |
| `generationConfig.responseModalities` | string[] | 是 | 同时接受文字和图片结果时使用 `["TEXT", "IMAGE"]`。 |
| `generationConfig.imageConfig.imageSize` | string | 否 | `512`、`1K`、`2K` 或 `4K`，默认 `1K`；受模型限制。 |
| `generationConfig.imageConfig.aspectRatio` | string | 否 | 输出比例，例如 `1:1`、`3:4` 或 `16:9`。 |

| 模型 | 支持的 `imageSize` |
| --- | --- |
| `nano-banana-2` | `512`、`1K`、`2K`、`4K` |
| `nano-banana-pro` | `1K`、`2K`、`4K` |
| `nano-banana-2-lite` | `1K` |

## 文生图示例

```bash
curl -X POST "{BASE_URL}/v1beta/models/nano-banana-2:generateContent" \
  -H "x-api-key: sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "电影感产品图：透明香水瓶放在黑色岩石上，蓝色薄雾，无文字"
          }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {
        "imageSize": "512",
        "aspectRatio": "1:1"
      }
    }
  }'
```

## 图片编辑示例

构造 JSON 请求前，先把图片编码为纯 Base64：

```bash
IMAGE_BASE64="$(base64 < ./reference.png | tr -d '\n')"
```

```json
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "保持人物和构图不变，把背景替换成雨夜霓虹街道"
        },
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "BASE64_IMAGE_DATA"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "TEXT",
      "IMAGE"
    ],
    "imageConfig": {
      "imageSize": "2K",
      "aspectRatio": "3:4"
    }
  }
}
```

每增加一张参考图，就增加一个 `inlineData` part，并保持图片顺序与提示词描述一致。

## 响应示例

```json
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "图片已生成。"
          },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "iVBORw0KGgoAAAANSUhEUgAA..."
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ]
}
```

找到包含 `inlineData` 的 part，对其中的 `data` 进行 Base64 解码，并按返回的 `mimeType` 保存。部分客户端可能把字段名规范化为 `inline_data` 和 `mime_type`。

## Python 示例

```python
import base64
import requests

response = requests.post(
    "https://api.uniall.ai/v1beta/models/nano-banana-2:generateContent",
    headers={"x-api-key": "sk-***", "Content-Type": "application/json"},
    json={
        "contents": [{
            "role": "user",
            "parts": [{"text": "一只戴宇航员头盔的橘猫"}],
        }],
        "generationConfig": {
            "responseModalities": ["TEXT", "IMAGE"],
            "imageConfig": {"imageSize": "512", "aspectRatio": "1:1"},
        },
    },
    timeout=600,
)
response.raise_for_status()

for candidate in response.json().get("candidates", []):
    for part in candidate.get("content", {}).get("parts", []):
        image = part.get("inlineData") or part.get("inline_data")
        if image and image.get("data"):
            with open("generated.png", "wb") as output:
                output.write(base64.b64decode(image["data"]))
            raise SystemExit(0)

raise RuntimeError("response did not contain an image")
```

## 旧版兼容模型名

早期把固定分辨率写进模型名的 Gemini preview ID 可能仍可兼容使用，但已经弃用，并可能随时移除。新接入请在 URL 中使用统一 Nano 模型，并通过 `imageSize` 选择分辨率。

## 计费说明

计费取决于模型和 `imageSize`，请以账号当前可见的模型价格为准。响应包含 Base64 图片数据，体积可能较大。

## 常见错误

- 把 0.5K 写成 `imageSize: "0.5k"` 或 `"512K"`，正确值是 `"512"`。
- 为 `nano-banana-pro` 或 `nano-banana-2-lite` 请求 `512`。
- 在 `inlineData.data` 中包含 `data:image/png;base64,` 前缀。
- 只读取第一个响应 part，没有查找包含 `inlineData` 的 part。
- 在日志中记录完整 Base64 响应或 API Key。

## 相关页面

- [Nano 系列](../nano-series)
- [OpenAI Images 格式](./openai-format)

---

# OpenAI Images 格式

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/image/nano-series/openai-format
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/nano-series/openai-format.md
Description: 使用同步 OpenAI Images 接口或 UniAll 异步任务生成和编辑 Nano 系列图片。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

已有 OpenAI Images 客户端或需要图片 URL 时使用此格式。文生图和图片编辑均提供同步接口；不适合保持长连接的客户端可使用 UniAll 异步任务。

## 接口

| 流程 | 方法与路径 | 行为 |
| --- | --- | --- |
| 文生图 | `POST /v1/images/generations` | 等待生成并返回图片 URL。 |
| 图片编辑 | `POST /v1/images/edits` | 等待生成并返回图片 URL。 |
| 异步生成或编辑 | `POST /v1/images/tasks` | 立即返回任务 ID。 |
| 查询异步任务 | `GET /v1/images/tasks/{task_id}` | 返回任务状态和结果。 |

## 鉴权

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

也支持 `x-api-key: sk-***`，但 OpenAI 风格客户端推荐使用 Bearer 鉴权。

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `nano-banana-2`、`nano-banana-pro` 或 `nano-banana-2-lite`。 |
| `prompt` | string | 是 | 生成或编辑指令。 |
| `resolution` | string | 否 | `0.5k`、`1k`、`2k` 或 `4k`，默认 `1k`；受模型限制。 |
| `aspect_ratio` | string | 否 | 输出比例，例如 `1:1`、`3:4` 或 `16:9`。 |
| `images` | string[] | 条件必填 | 编辑使用的参考图 URL 或完整 Data URL。 |
| `n` | integer | 否 | 保持为 `1`，当前每次请求生成一张图片。 |
| `output_format` | string | 否 | 输出格式，例如 `png`。 |
| `request_id` | string | 否 | 异步任务使用的非敏感业务关联 ID。 |

0.5K 仅适用于 `nano-banana-2`，必须写成 `resolution: "0.5k"`。

## 同步文生图

```bash
curl -X POST "{BASE_URL}/v1/images/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "电影感产品图：透明香水瓶放在黑色岩石上，蓝色薄雾，无文字",
    "resolution": "0.5k",
    "aspect_ratio": "1:1",
    "n": 1,
    "output_format": "png"
  }'
```

## 同步图片编辑

```bash
curl -X POST "{BASE_URL}/v1/images/edits" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "保持人物和构图不变，把背景替换成雨夜霓虹街道",
    "images": ["https://example.com/reference/person.png"],
    "resolution": "2k",
    "aspect_ratio": "3:4",
    "n": 1,
    "output_format": "png"
  }'
```

参考图 URL 必须能被服务端直接访问。多张参考图按提示词描述顺序放入 `images`。

## 同步响应

```json
{
  "created": 1787366400,
  "data": [
    {
      "url": "https://media.example.com/generated/image.png",
      "width": 512,
      "height": 512
    }
  ]
}
```

从 `data[0].url` 读取结果；如需长期保留，请及时转存。

## 异步任务

生成和编辑共用 `POST /v1/images/tasks`。请求包含 `images` 时按编辑任务处理。

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "电影感产品图：透明香水瓶放在黑色岩石上",
    "resolution": "0.5k",
    "aspect_ratio": "1:1",
    "n": 1,
    "output_format": "png",
    "request_id": "image-20260822-0001"
  }'
```

```json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "image.generation.job",
  "model": "nano-banana-2",
  "status": "PENDING",
  "progress": 0,
  "image_url": null
}
```

保存 `task_id`；不要因为任务仍为 `PENDING` 就重新创建。

## 任务状态与结果

```bash
curl "{BASE_URL}/v1/images/tasks/task_xxx" \
  -H "Authorization: Bearer sk-***"
```

开始时每 2～3 秒查询一次，等待时间变长后降到每 5～10 秒一次。`?refresh=true` 仅用于确实需要立即刷新上游状态的场景，不要每次轮询都添加。

| 状态 | 含义 | 处理方式 |
| --- | --- | --- |
| `PENDING` | 等待处理 | 继续轮询。 |
| `IN_PROGRESS` | 正在生成 | 继续轮询。 |
| `COMPLETED` | 已完成 | 优先读取 `data[0].url`，再回退到 `image_url`。 |
| `FAILED` | 生成失败 | 读取公开错误并停止。 |
| `CANCELLED` | 已取消 | 停止轮询。 |

```json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "model": "nano-banana-2",
  "status": "COMPLETED",
  "progress": 100,
  "image_url": "https://media.example.com/generated/image.png",
  "data": [
    {
      "url": "https://media.example.com/generated/image.png",
      "width": 512,
      "height": 512
    }
  ],
  "error": null
}
```

## 旧版兼容模型名

`NanoBanana2-0.5K`、`NanoBananaPro-4K` 等固定分辨率别名可能仍可兼容使用，但已经弃用，并可能随时移除。新代码请使用统一模型 ID 加 `resolution`。

## 计费说明

计费取决于所选模型和分辨率，请以账号当前可见价格为准。同步请求断开或客户端超时，不代表生成已经停止。

## 常见错误

- 把 0.5K 写成 `resolution: "512"` 或 `"512K"`，正确值是 `"0.5k"`。
- 为 `nano-banana-pro` 或 `nano-banana-2-lite` 请求 0.5K。
- 参考图 URL 需要登录或临时 Cookie，导致服务端无法访问。
- 客户端超时后立即重试，产生重复生成。
- 根据错误消息文本分支，而不是 HTTP 状态码和结构化错误字段。

## 相关页面

- [Nano 系列](../nano-series)
- [Gemini generateContent 格式](./gemini-format)
- [通用异步图像生成](/zh-CN/models/image/async-image-generation)

---

# 图像生成概览

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/image/overview
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/overview.md
Description: UniAll 图像生成 API 分类入口。

图像生成文档覆盖来源菜单中选定的页面，以及用户提供的可灵图片调用口径。

## 包含页面

- [通用异步图像生成](/zh-CN/models/image/async-image-generation)
- [Seedream 图像生成](/zh-CN/models/image/seedream)
- [Seedream 5.0 Pro 图像生成](/zh-CN/models/image/seedream-5-0-pro)
- [GPT-Image-2 图像生成](/zh-CN/models/image/gpt-image-2)
- [GPT-Image-2.5](/zh-CN/models/image/gpt-image-2-5)
- [Nano 系列图像生成](/zh-CN/models/image/nano-series)
- [Kling](/zh-CN/models/image/kling)

## 接入建议

如果所选模型使用轮询流程，先阅读通用异步图像生成页面。Kling 使用 `/v1/images/tasks`，通过 `operation` 选择文生图、编辑、多图参考、扩图或主体补全。调用 `seedream-5.0-pro` 时，文生图使用 `/v1/images/generations`，参考图请求使用 `/v1/images/edits`。

---

# Seedream

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/image/seedream
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/seedream.md
Description: Seedream 图像生成来源文档。

本文档面向 Seedream 系列图片生成模型，覆盖三个图片模型的接口、参数、限制、响应和示例。

## 基本信息

### 鉴权

所有 `/v1/*` 接口都需要 API Key：

```http
Authorization: Bearer <your_api_key>
```

### 支持的模型

| Public model | 能力 | 计费口径 |
|---|---|---:|
| `seedream-4.0` | 文生图、图片编辑 | 按输出图片张数 |
| `seedream-4.5` | 文生图、图片编辑 | 按输出图片张数 |
| `seedream-5.0-lite` | 文生图、图片编辑 | 按输出图片张数 |

同一个模型名称同时支持文生图和图片编辑：

| 请求形态 | 操作类型 |
|---|---|
| 不传参考图 | 文生图 |
| 传 `image` / `image_url` / `image_urls` / `images` | 图片编辑 |

> 计费建议：按实际输出图片张数计费。`custom_size`、横图、竖图、比例本身不改变计费。

## 推荐入口

| 场景 | Endpoint | 等待结果 | 返回形态 |
|---|---|---:|---|
| 文生图，同步拿图 | `POST /v1/images/generations` | 是 | `data[].url` |
| 图片编辑，同步拿图 | `POST /v1/images/edits` | 是 | `data[].url` |

## 参数总表

### 支持参数

| 参数 | 类型 | 位置 | 必填 | 说明 |
|---|---|---|---:|---|
| `model` | string | body | 是 | `seedream-4.0`、`seedream-4.5`、`seedream-5.0-lite` |
| `prompt` | string | body | 是 | 文生图或编辑提示词 |
| `n` | integer | body | 否 | 输出图片数，`1` 到 `6`。OpenAI 兼容字段 |
| `custom_size` | object | body | 否 | 自定义输出尺寸，例如 `{"width": 2048, "height": 2048}` |
| `image` | string / array | body / form | 编辑必填之一 | 参考图 URL，可传单张或多张 |
| `image_url` | string / object / array | body / form | 编辑必填之一 | 参考图 URL，兼容 `{ "url": "..." }` 写法 |
| `image_urls` | array | body / form | 编辑必填之一 | 多参考图 URL |
| `images` | array | body | 编辑必填之一 | 多参考图 URL，支持字符串或对象 |
| `timeout_seconds` | integer | body | 否 | 同步接口等待超时时间 |

### `n`

- 默认值：`1`
- 最小值：`1`
- 最大值：`6`

示例：

```json
{
  "num_images": 3
}
```

或：

```json
{
  "n": 3
}
```

## `custom_size` 尺寸规则

格式：

```json
{
  "custom_size": {
    "width": 2048,
    "height": 2048
  }
}
```

尺寸约束：

| 模型 | 最小总像素 | 最大总像素 | 最大边长 | 是否要求 16 倍数 |
|---|---:|---:|---:|---:|
| `seedream-4.0` | `921600` | `16777216` | `4096` | 否 |
| `seedream-4.5` | `3686400` | `16777216` | `4096` | 否 |
| `seedream-5.0-lite` | `3686400` | `16777216` | `4096` | 否 |

常用安全尺寸：

| 尺寸 | 比例 | `seedream-4.0` | `seedream-4.5` | `seedream-5.0-lite` |
|---|---|---:|---:|---:|
| `960x960` | `1:1` | 可用 | 不可用，低于最小像素 | 不可用，低于最小像素 |
| `1280x720` | `16:9` | 可用 | 不可用，低于最小像素 | 不可用，低于最小像素 |
| `720x1280` | `9:16` | 可用 | 不可用，低于最小像素 | 不可用，低于最小像素 |
| `2048x2048` | `1:1` | 可用 | 可用 | 可用 |
| `2560x1440` | `16:9` | 可用 | 可用 | 可用 |
| `1440x2560` | `9:16` | 可用 | 可用 | 可用 |
| `2304x1728` | `4:3` | 可用 | 可用 | 可用 |
| `1728x2304` | `3:4` | 可用 | 可用 | 可用 |
| `4096x4096` | `1:1` | 可用，最大像素 | 可用，最大像素 | 可用，最大像素 |

## 参考图输入

图片编辑模式只支持 URL 参考图。不支持上传本地文件。

可用写法：

```json
{
  "image": "https://example.com/a.png"
}
```

```json
{
  "image_url": "https://example.com/a.png"
}
```

```json
{
  "image_url": {
    "url": "https://example.com/a.png"
  }
}
```

```json
{
  "image_urls": [
    "https://example.com/a.png",
    "https://example.com/b.png"
  ]
}
```

```json
{
  "images": [
    "https://example.com/a.png",
    {
      "url": "https://example.com/b.png"
    },
    {
      "image_url": "https://example.com/c.png"
    }
  ]
}
```

编辑限制：

| 限制 | 值 |
|---|---:|
| 单次输入参考图最多 | `10` 张 |
| 单次输出图最多 | `6` 张 |
| 输入图数 + 输出图数最多 | `15` 张 |

示例：

| 输入参考图数量 | 最大 `num_images` |
|---:|---:|
| `1` | `6` |
| `5` | `6` |
| `9` | `6` |
| `10` | `5` |


## 同步文生图

### 最小请求

```bash
curl -X POST "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-4.0",
    "prompt": "一张干净的高端耳机产品图，白色摄影棚背景，柔和阴影"
  }'
```

响应：

```json
{
  "created": 1778688000,
  "data": [
    {
      "url": "https://example.com/generated-1.png"
    }
  ]
}
```

### 一次生成 6 张

```bash
curl -X POST "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-4.5",
    "prompt": "高端护肤品广告图，玻璃瓶，水滴质感，真实商业摄影",
    "num_images": 6,
    "custom_size": {
      "width": 2048,
      "height": 2048
    }
  }'
```

### 16:9 横图

`seedream-4.5` 和 `seedream-5.0-lite` 的最小像素更高，建议用 `2560x1440` 起步：

```bash
curl -X POST "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-lite",
    "prompt": "16:9 电影感城市夜景，霓虹灯，雨后街道，超写实",
    "n": 2,
    "custom_size": {
      "width": 2560,
      "height": 1440
    }
  }'
```

### 9:16 竖图

```bash
curl -X POST "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-4.5",
    "prompt": "竖版手机壁纸，未来主义跑车，夜晚街景，强烈光影",
    "num_images": 1,
    "custom_size": {
      "width": 1440,
      "height": 2560
    }
  }'
```

### `seedream-4.0` 小尺寸示例

`1280x720` 只适合 `seedream-4.0`，不适合 `seedream-4.5` 和 `seedream-5.0-lite`。

```bash
curl -X POST "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-4.0",
    "prompt": "横版社交媒体封面，蓝天草地，清爽插画风",
    "custom_size": {
      "width": 1280,
      "height": 720
    }
  }'
```

## 同步图片编辑

### JSON 单参考图

```bash
curl -X POST "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-4.0",
    "prompt": "把图片改成电影海报风格，增强光影，保留主体人物",
    "image": "https://example.com/source.png",
    "num_images": 1,
    "custom_size": {
      "width": 2048,
      "height": 2048
    }
  }'
```

### JSON 多参考图

```bash
curl -X POST "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-4.5",
    "prompt": "将两张参考图融合成同一套品牌广告视觉，保持产品一致性",
    "image_urls": [
      "https://example.com/product.png",
      "https://example.com/background.png"
    ],
    "n": 3,
    "custom_size": {
      "width": 2560,
      "height": 1440
    }
  }'
```

### `images` 数组对象写法

```bash
curl -X POST "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-lite",
    "prompt": "参考第一张的人物和第二张的服装，生成一张统一风格的商业大片",
    "images": [
      { "url": "https://example.com/person.png" },
      { "image_url": "https://example.com/outfit.png" }
    ],
    "num_images": 2,
    "custom_size": {
      "width": 2048,
      "height": 2048
    }
  }'
```

---

# Seedream 5.0 Pro

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/image/seedream-5-0-pro
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/seedream-5-0-pro.md
Description: 通过 UniAll.ai 同步图片接口调用 seedream-5.0-pro 生成或编辑图片。

使用 `seedream-5.0-pro` 时，文生图和图片编辑分别调用对应的同步接口。文生图使用 `/v1/images/generations` 且不传 `image`；图生图或图片编辑使用 `/v1/images/edits`，并传入 1 至 10 张参考图。

本文档对应 2026 年 7 月 25 日更新的公开调用契约。

## 概览

- 两个接口都在同一个 HTTP 响应中返回最终图片，不需要创建或轮询异步任务。
- 每次请求固定生成一张图片。
- 可以使用 `1K` 或 `2K` 分辨率档位并指定画幅比例，也可以直接传入精确尺寸。
- 参考图支持公网 URL 和 Base64 Data URL。
- 响应可以返回临时图片 URL 或纯 Base64 数据。

## 接口与鉴权

```http
POST https://api.uniall.ai/v1/images/generations
POST https://api.uniall.ai/v1/images/edits
Authorization: Bearer sk-***
Content-Type: application/json
```

- 文生图：调用 `/v1/images/generations`，不传 `image`。
- 图生图或图片编辑：调用 `/v1/images/edits`，并传入 `image`。

Base URL 为：

```uri
https://api.uniall.ai
```

如果 UniAll.ai 控制台为当前账号提供了专属 API 地址，请以控制台显示的地址为准。

## 快速开始

### 文生图

```bash
curl -X POST "https://api.uniall.ai/v1/images/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro",
    "prompt": "高端护肤品广告图，玻璃瓶放在浅色石材台面上，柔和自然光，中文品牌文字清晰",
    "size": "2K",
    "aspect_ratio": "16:9",
    "output_format": "jpeg",
    "response_format": "url"
  }'
```

### 图生图

```bash
curl -X POST "https://api.uniall.ai/v1/images/edits" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro",
    "prompt": "保留产品外形和标签文字，把背景替换成明亮的摄影棚场景",
    "image": "https://example.com/source-product.png",
    "size": "1K",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "response_format": "url"
  }'
```

### 精确尺寸

需要固定宽高时，直接把精确尺寸传给 `size`。同一个请求中不要再传 `aspect_ratio`。

```bash
curl -X POST "https://api.uniall.ai/v1/images/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro",
    "prompt": "宽幅科技产品发布会主视觉，主体位于画面中央，背景简洁",
    "size": "2048x1024",
    "output_format": "jpeg",
    "response_format": "url"
  }'
```

## 请求参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `model` | string | 是 | 无 | 固定为 `seedream-5.0-pro`。 |
| `prompt` | string | 是 | 无 | 图片生成或编辑提示词。 |
| `image` | string / string[] | 图生图必填 | 无 | `/v1/images/edits` 的参考图，支持公网 URL 或 Base64 Data URL，最多 10 张。 |
| `size` | string | 否 | `2K` | `1K`、`2K` 或精确尺寸 `WIDTHxHEIGHT`。 |
| `aspect_ratio` | string | 否 | 由模型判断 | 使用 `1K`、`2K` 时可指定画幅比例；精确尺寸模式不能传。 |
| `output_format` | string | 否 | `jpeg` | `jpeg` 或 `png`。 |
| `response_format` | string | 否 | `url` | `url` 或 `b64_json`。 |
| `watermark` | boolean | 否 | `true` | 是否添加“AI 生成”水印。 |

该模型每次固定生成一张图片。

## 尺寸与画幅比例

尺寸有以下两种用法，选择其中一种。

### 分辨率档位与画幅比例

```json
{
  "size": "2K",
  "aspect_ratio": "16:9"
}
```

`size` 支持 `1K` 和 `2K`。`aspect_ratio` 支持 `1:1`、`4:3`、`3:4`、`16:9`、`9:16`、`3:2`、`2:3` 和 `21:9`。

常见输出尺寸如下。最终尺寸以响应中的 `data[0].size` 为准。

| 分辨率 | `1:1` | `4:3` | `3:4` | `16:9` | `9:16` | `3:2` | `2:3` | `21:9` |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `1K` | `1024x1024` | `1152x864` | `864x1152` | `1424x800` | `800x1424` | `1248x832` | `832x1248` | `1568x672` |
| `2K` | `2048x2048` | `2368x1776` | `1776x2368` | `2816x1584` | `1584x2816` | `2496x1664` | `1664x2496` | `3136x1344` |

不传 `aspect_ratio` 时，模型会根据提示词和参考图判断画幅。

### 精确尺寸

```json
{
  "size": "2048x1024"
}
```

精确尺寸必须同时满足以下条件：

- `width * height` 必须在 `921600` 到 `4624220` 之间，包含边界值。
- 宽高比必须在 `1/16` 到 `16` 之间，包含边界值。
- 没有单独的 4096 最大边限制，例如 `4200x1000` 是合法尺寸。
- 不能同时传 `aspect_ratio`，因为精确尺寸已经确定画幅。

## 参考图输入

图生图和图片编辑统一调用 `/v1/images/edits`。

单张参考图传字符串，多张参考图传数组：

```json
{
  "image": [
    "https://example.com/product.png",
    "data:image/png;base64,..."
  ]
}
```

同一个请求中可以混合使用公网 URL 和 Base64 Data URL。

### 公网 URL

- 图片必须能被公网直接访问。
- 访问图片不能依赖 Cookie、登录状态或额外请求头。

### Base64 Data URL

必须使用完整的 Data URL 格式：

```uri
data:image/png;base64,...
```

- 图片格式名必须小写，但不要求 Base64 内容本身小写。
- 支持 JPEG、PNG、WEBP、BMP、TIFF、GIF、HEIC 和 HEIF。
- 每张 Data URL 图片最大 `30 MB`。
- 单次请求的参考图总数不能超过 10 张。

## 响应格式

输入形式和输出形式相互独立。URL 输入可以返回 Base64，Base64 输入也可以返回 URL。

### URL 响应

请求参数：

```json
{
  "response_format": "url"
}
```

响应示例：

```json
{
  "created": 1784900000,
  "data": [
    {
      "url": "https://example.com/generated.jpeg",
      "size": "2816x1584",
      "output_format": "jpeg"
    }
  ],
  "usage": {
    "generated_images": 1,
    "input_images": 0,
    "output_tokens": 17424,
    "total_tokens": 17424
  }
}
```

返回的 URL 可能在生成后 24 小时失效，请及时下载并保存图片。

### Base64 响应

请求参数：

```json
{
  "response_format": "b64_json"
}
```

图片项会返回 `b64_json`，不再返回 `url`：

```json
{
  "data": [
    {
      "b64_json": "...",
      "size": "2048x1024",
      "output_format": "png"
    }
  ]
}
```

`b64_json` 是纯 Base64 内容，不包含 Data URL 前缀。

### 响应字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `created` | integer | 响应的 Unix 时间戳。 |
| `data` | array | 生成结果数组，固定包含一个图片项。 |
| `data[].url` | string | `response_format` 为 `url` 时返回的临时图片地址。 |
| `data[].b64_json` | string | `response_format` 为 `b64_json` 时返回的纯 Base64 图片数据。 |
| `data[].size` | string | 最终输出尺寸，格式为 `WIDTHxHEIGHT`。 |
| `data[].output_format` | string | 最终图片格式。 |
| `usage.generated_images` | integer | 生成图片数量。 |
| `usage.input_images` | integer | 输入参考图数量。 |
| `usage.output_tokens` | integer | API 返回的输出用量。 |
| `usage.total_tokens` | integer | API 返回的总用量。 |

## 提示词定位与标注

点位、区域、文字替换、箭头、涂鸦和标注框都通过输入图与 `prompt` 表达，不需要增加请求参数。

```markdown
把 <bbox>100 200 800 900</bbox> 内的招牌替换为“新品上市”
在 <point>520 380</point> 附近增加一个小型台灯
```

坐标范围为 `0..999`。也可以直接在输入图中绘制箭头、标注框或其他标记，再通过提示词说明编辑意图。

## 计费说明

- 每次请求固定输出一张图片。
- 输入图片张数可能参与计费，具体以当前 UniAll.ai 模型页为准。
- 输出图片按实际像素分档：不超过 `2360000` 像素，或超过 `2360000` 像素。
- `1K`、`2K` 不是直接计费条件，最终根据生成图片的 `width * height` 判断档位。
- 具体单价、分组倍率和最终扣费以 UniAll.ai 模型页及消费日志为准。

## 常见问题

| 问题 | 常见原因 | 处理方式 |
| --- | --- | --- |
| 传入参考图后没有按编辑请求处理 | 请求发送到了 `/v1/images/generations`。 | 所有包含 `image` 的请求都改用 `/v1/images/edits`。 |
| 精确尺寸被拒绝 | 同时传了 `aspect_ratio`，或像素数、宽高比超出限制。 | 删除 `aspect_ratio`，并重新检查精确尺寸约束。 |
| 参考图被拒绝 | 超过 10 张、URL 无法公网直连，或 Data URL 格式不完整。 | 减少图片数量，并检查公网访问或完整 Data URL 格式。 |
| 图片格式被拒绝 | 使用了不支持的格式，或 Data URL 中的图片格式名不是小写。 | 改用支持的格式，并使用 `image/png` 等小写格式名。 |
| 响应中找不到预期字段 | 请求 `b64_json` 后仍读取 `url`，或反之。 | 根据 `response_format` 读取对应字段。 |
| 客户端在返回图片前超时 | 同步生成所需时间超过客户端 HTTP 超时。 | 增加客户端超时时间，继续等待原请求，不要轮询异步任务接口。 |

## 相关页面

- [Seedream 图像生成](/zh-CN/models/image/seedream)
- [图像生成概览](/zh-CN/models/image/overview)
- [模型列表](/zh-CN/models)

---

# Gemini Omni Flash Preview

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/gemini-omni-flash-preview
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/gemini-omni-flash-preview.md
Description: 通过 UniAll.ai Gemini Interactions API 调用 gemini-omni-flash-preview 生成视频。

本文档介绍如何通过 UniAll.ai API 调用
`gemini-omni-flash-preview` 生成视频。

示例使用以下地址：

```uri
https://api.uniall.ai
```

如果 UniAll.ai 控制台提供了专属 API 地址，请使用控制台显示的地址。

## 1. 快速开始

生成接口：

```http
POST /v1beta/interactions
```

鉴权方式：

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

最小文生视频请求：

```bash
curl -X POST "https://api.uniall.ai/v1beta/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": "A cinematic robot walking through rain at night.",
    "response_format": {
      "type": "video",
      "aspect_ratio": "16:9"
    },
    "generation_config": {
      "video_config": {
        "task": "text_to_video",
        "resolution": "720p",
        "duration_seconds": 4
      }
    }
  }'
```

## 2. 支持能力

| 能力 | `task` | 输入要求 |
|---|---|---|
| 文生视频 | `text_to_video` | 提示词，不携带图片或视频 |
| 图生视频 | `image_to_video` | 提示词 + 1 张图片 |
| 多参考生成 | `reference_to_video` | 提示词 + 图片、视频，或图片与视频的组合 |

当前不支持：

- 音频参考素材；
- 首帧与尾帧插值；
- 基于历史 `interaction_id` 的续作或编辑；
- 视频延长；
- Base64、`inline_data` 或 multipart 文件上传；
- 自定义分辨率、宽度或高度。

## 3. 请求参数

### 3.1 顶层参数

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | 是 | 固定为 `gemini-omni-flash-preview` |
| `input` | string / object / array | 是 | 提示词及可选的图片、视频 URL |
| `response_format` | object | 是 | 输出类型和画面比例 |
| `generation_config` | object | 建议 | 视频生成参数；建议始终显式传入 |
| `timeout_seconds` | integer | 否 | 服务端等待结果的最长秒数，默认 `300`；它不是视频时长 |

`POST /v1beta/interactions` 会等待视频生成完成后返回结果。调用方的
HTTP 客户端超时时间应大于 `timeout_seconds`，视频参考任务建议设置为
`600` 秒或更长。

### 3.2 `response_format`

| 参数 | 类型 | 必填 | 支持值 | 默认值 |
|---|---|---|---|---|
| `type` | string | 是 | `video` | 无 |
| `aspect_ratio` | string | 否 | `16:9`、`9:16` | `16:9` |

- `16:9`：横屏视频；
- `9:16`：竖屏视频。

### 3.3 `generation_config.video_config`

| 参数 | 类型 | 必填 | 支持值 | 说明 |
|---|---|---|---|---|
| `task` | string | 建议 | `text_to_video`、`image_to_video`、`reference_to_video` | 建议显式填写，避免输入意图不明确 |
| `resolution` | string | 否 | `720p` | 当前唯一支持的分辨率，默认 `720p` |
| `duration_seconds` | integer | 否 | `4`、`6`、`8`、`10` | 期望视频时长，默认 `4` |

当请求包含视频参考时，模型会结合参考视频自行决定最终输出时长，
`duration_seconds` 不保证与成品视频时长完全一致。需要精确时长时，
请以返回视频文件的实际时长为准。

### 3.4 `task` 与素材组合

| `task` | 图片 | 视频 | 允许的组合 |
|---|---:|---:|---|
| `text_to_video` | 0 | 0 | 仅提示词 |
| `image_to_video` | 1 | 0 | 恰好 1 张图片 |
| `reference_to_video` | 0–7 | 0–1 | 图片、多图、单视频或图片 + 单视频；至少包含一种素材 |

如果省略 `task`，系统会根据素材自动判断：

- 没有图片和视频：`text_to_video`；
- 恰好 1 张图片：`image_to_video`；
- 多张图片或包含视频：`reference_to_video`。

为保证调用结果稳定，生产环境建议始终显式传入 `task`。

## 4. `input` 写法

### 4.1 纯文本

文生视频可以直接传入字符串：

```json
{
  "input": "A paper boat sailing through a neon city during heavy rain."
}
```

### 4.2 数组写法

数组写法表达最清晰，推荐用于所有带素材的请求：

```json
{
  "input": [
    {
      "type": "text",
      "text": "Animate the subject with a slow cinematic camera push-in."
    },
    {
      "type": "image",
      "url": "https://example.com/subject.webp"
    },
    {
      "type": "video",
      "url": "https://example.com/motion-reference.mp4"
    }
  ]
}
```

数组元素：

| `type` | 参数 | 说明 |
|---|---|---|
| `text` | `text` | 文本提示词 |
| `image` | `url` | 可公开访问的图片 URL |
| `video` | `url` | 可公开访问的视频 URL |

### 4.3 对象简写

也可以使用对象及 URL 数组：

```json
{
  "input": {
    "text": "Use the references to create one cohesive cinematic shot.",
    "image_urls": [
      "https://example.com/character.png",
      "https://example.com/environment.jpg"
    ],
    "video_urls": [
      "https://example.com/camera-motion.mp4"
    ]
  }
}
```

支持的对象字段：

| 参数 | 类型 | 说明 |
|---|---|---|
| `text` | string | 提示词 |
| `image_url` | string | 单张图片 URL |
| `image_urls` | string[] | 多张图片 URL |
| `video_url` | string | 单个视频 URL |
| `video_urls` | string[] | 视频 URL 数组；当前最多 1 个 |

## 5. 提示词与素材限制

### 5.1 提示词

- 所有任务都应提供非空提示词；
- 最大长度为 `20000` 个字符；
- 多段文本会按顺序合并；
- 建议描述主体、动作、镜头运动、场景、光线、节奏和风格；
- 如果使用参考素材，建议在提示词中明确每个素材的用途。

提示词示例：

```markdown
Use the first image for the character appearance, the second image for the
environment, and the video for camera motion. Create one continuous cinematic
shot with natural movement and consistent lighting.
```

### 5.2 图片

- 支持 JPEG、PNG、WEBP；
- 每张图片最大 `20 MB`；
- URL 必须能由公网直接访问；
- 不应依赖 Cookie、登录状态或自定义请求头；
- 无视频时最多传入 7 张图片；
- 图生视频必须恰好传入 1 张图片。

### 5.3 视频

- 每次请求最多 1 个参考视频；
- 视频文件最大 `100 MB`；
- 输入视频最长 `30` 秒；
- 推荐使用兼容性较好的 MP4 文件；
- 参考素材使用视频开头最多 10 秒的内容；
- 视频 URL 必须能由公网直接访问。

### 5.4 参考素材配额

每张图片占 1 个素材单位，每个视频占 2 个素材单位，总计不能超过
7 个单位：

```markdown
图片数量 + 视频数量 × 2 <= 7
```

| 图片数 | 视频数 | 是否允许 |
|---:|---:|---|
| 7 | 0 | 是 |
| 5 | 1 | 是 |
| 6 | 1 | 否 |
| 0 | 1 | 是 |
| 0 | 2 | 否 |

## 6. 请求示例

以下示例均使用推荐的显式参数写法。

### 6.1 横屏文生视频

```bash
curl -X POST "https://api.uniall.ai/v1beta/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": "A wide cinematic shot of an astronaut walking through a field of glowing flowers at dusk, gentle wind, slow dolly-in camera movement.",
    "response_format": {
      "type": "video",
      "aspect_ratio": "16:9"
    },
    "generation_config": {
      "video_config": {
        "task": "text_to_video",
        "resolution": "720p",
        "duration_seconds": 6
      }
    },
    "timeout_seconds": 600
  }'
```

### 6.2 竖屏文生视频

```bash
curl -X POST "https://api.uniall.ai/v1beta/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": [
      {
        "type": "text",
        "text": "Vertical fashion film, a model walking through a minimalist white gallery, soft shadows, smooth handheld camera, premium editorial style."
      }
    ],
    "response_format": {
      "type": "video",
      "aspect_ratio": "9:16"
    },
    "generation_config": {
      "video_config": {
        "task": "text_to_video",
        "resolution": "720p",
        "duration_seconds": 10
      }
    },
    "timeout_seconds": 600
  }'
```

### 6.3 单图生成视频

```bash
curl -X POST "https://api.uniall.ai/v1beta/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": [
      {
        "type": "image",
        "url": "https://example.com/portrait.webp"
      },
      {
        "type": "text",
        "text": "Keep the character appearance consistent. Add subtle breathing and blinking, hair moving gently in the wind, and a slow camera push-in."
      }
    ],
    "response_format": {
      "type": "video",
      "aspect_ratio": "9:16"
    },
    "generation_config": {
      "video_config": {
        "task": "image_to_video",
        "resolution": "720p",
        "duration_seconds": 4
      }
    },
    "timeout_seconds": 600
  }'
```

### 6.4 多图角色与场景参考

```bash
curl -X POST "https://api.uniall.ai/v1beta/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": {
      "text": "Use the first image for the character, the second for clothing, and the third for the environment. Create one continuous shot of the character entering the cafe and looking toward the camera.",
      "image_urls": [
        "https://example.com/character.png",
        "https://example.com/outfit.jpg",
        "https://example.com/cafe.webp"
      ]
    },
    "response_format": {
      "type": "video",
      "aspect_ratio": "16:9"
    },
    "generation_config": {
      "video_config": {
        "task": "reference_to_video",
        "resolution": "720p",
        "duration_seconds": 8
      }
    },
    "timeout_seconds": 600
  }'
```

### 6.5 单视频动作参考

```bash
curl -X POST "https://api.uniall.ai/v1beta/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": [
      {
        "type": "video",
        "url": "https://example.com/dance-motion.mp4"
      },
      {
        "type": "text",
        "text": "Create a cinematic dancer performance using the reference for body movement and rhythm. Use dramatic blue stage lighting and a slowly orbiting camera."
      }
    ],
    "response_format": {
      "type": "video",
      "aspect_ratio": "16:9"
    },
    "generation_config": {
      "video_config": {
        "task": "reference_to_video",
        "resolution": "720p",
        "duration_seconds": 8
      }
    },
    "timeout_seconds": 600
  }'
```

### 6.6 图片与视频混合参考

```bash
curl -X POST "https://api.uniall.ai/v1beta/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": {
      "text": "Use the character image for appearance, the city image for the environment, and the video for camera motion. Keep the character identity and clothing consistent throughout the shot.",
      "image_urls": [
        "https://example.com/character.png",
        "https://example.com/night-city.jpg"
      ],
      "video_urls": [
        "https://example.com/camera-reference.mp4"
      ]
    },
    "response_format": {
      "type": "video",
      "aspect_ratio": "16:9"
    },
    "generation_config": {
      "video_config": {
        "task": "reference_to_video",
        "resolution": "720p",
        "duration_seconds": 10
      }
    },
    "timeout_seconds": 600
  }'
```

### 6.7 Python 调用

```python
import requests

api_url = "https://api.uniall.ai/v1beta/interactions"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "model": "gemini-omni-flash-preview",
    "input": [
        {
            "type": "image",
            "url": "https://example.com/product.png",
        },
        {
            "type": "text",
            "text": (
                "Create a premium product film with a slow 360-degree camera "
                "move, soft studio reflections, and a dark background."
            ),
        },
    ],
    "response_format": {
        "type": "video",
        "aspect_ratio": "16:9",
    },
    "generation_config": {
        "video_config": {
            "task": "image_to_video",
            "resolution": "720p",
            "duration_seconds": 6,
        }
    },
    "timeout_seconds": 600,
}

response = requests.post(
    api_url,
    headers=headers,
    json=payload,
    timeout=660,
)
response.raise_for_status()

result = response.json()
print(result["interaction_id"])
print(result["response"]["video"]["uri"])
```

### 6.8 JavaScript 调用

```javascript
const response = await fetch("https://api.uniall.ai/v1beta/interactions", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gemini-omni-flash-preview",
    input: "A tiny red train crossing a snowy mountain bridge at sunrise.",
    response_format: {
      type: "video",
      aspect_ratio: "16:9",
    },
    generation_config: {
      video_config: {
        task: "text_to_video",
        resolution: "720p",
        duration_seconds: 4,
      },
    },
    timeout_seconds: 600,
  }),
});

const result = await response.json();
if (!response.ok) {
  throw new Error(result.error?.message ?? "Video generation failed");
}

console.log(result.interaction_id);
console.log(result.response.video.uri);
```

## 7. 成功响应

成功时返回一个 Gemini Interactions 风格的结果：

```json
{
  "interaction_id": "task_xxx",
  "model": "gemini-omni-flash-preview",
  "response": {
    "video": {
      "uri": "https://api.uniall.ai/media/generated-video.mp4"
    }
  }
}
```

| 字段 | 说明 |
|---|---|
| `interaction_id` | 本次生成的唯一标识，可用于查询 |
| `model` | 实际调用的公共模型名称 |
| `response.video.uri` | 生成视频的访问地址 |

建议及时下载并保存生成结果，不要假设视频 URL 永久有效。

## 8. 任务状态与结果

`POST /v1beta/interactions` 通常会等待交互结果。需要后续查询时，保存 `interaction_id` 并调用 `GET /v1/videos/generations/{interaction_id}`，不要使用默认任务路径。公共终态、错误结构和结果字段见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。

## 9. 错误响应

错误响应采用统一结构：

```json
{
  "error": {
    "code": 400,
    "message": "`duration_seconds` must be one of 4, 6, 8, or 10",
    "status": "INVALID_ARGUMENT"
  }
}
```

常见错误：

| HTTP 状态码 | `error.status` | 说明 |
|---:|---|---|
| `400` | `INVALID_ARGUMENT` | 参数、素材数量或任务类型不符合要求 |
| `400` | `FAILED_PRECONDITION` | 请求内容未通过安全检查 |
| `401` | `UNAUTHENTICATED` | API Key 缺失或无效 |
| `404` | `NOT_FOUND` | 模型或查询标识不存在 |
| `429` | `RESOURCE_EXHAUSTED` | 请求频率过高 |
| `503` | `UNAVAILABLE` | 服务暂时不可用 |
| `504` | `DEADLINE_EXCEEDED` | 在 `timeout_seconds` 内未获得生成结果 |

## 10. 计费说明

价格与计费规则可能调整，请以 UniAll.ai 控制台当前显示的模型价格和用量记录为准。对账或联系支持时，请保留本次请求的 `interaction_id`。

## 11. 调用建议

- 显式传入 `task`、`resolution`、`duration_seconds` 和 `aspect_ratio`；
- 素材 URL 使用 HTTPS，并确认在无登录状态下可以直接下载；
- 客户端 HTTP 超时应比 `timeout_seconds` 多预留 30–60 秒；
- 视频参考任务的最终时长以成品文件为准；
- 多参考任务中，应在提示词里说明每个素材的用途；
- 收到 `429`、`503` 时使用指数退避重试，不要高频立即重试；
- 不要在日志、前端代码或公开仓库中暴露 API Key。

---

# Grok Imagine

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/grok-imagine
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/grok-imagine.md
Description: Grok Imagine 视频来源文档。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

更新时间：2026-06-03

本文说明如何在本站调用 Grok Imagine 视频模型。用户只需要使用本站稳定模型名和 OpenAI 兼容视频任务接口。

## 1. 可用模型

| 模型 | 适用场景 | 计费口径 |
| --- | --- | --- |
| `grok-imagine` | 文生视频、图生视频、多参考图生视频、视频编辑、视频续写 | 按能力类型、清晰度、输入/输出视频秒数等组件计费；图生视频输入图片不单独加价 |

新接入统一使用 `grok-imagine`，用输入形态和 `extra_body.operation` 表达具体能力。未在本站模型列表中展示的旧模型名不要直接调用。

## 2. 接口概览

### 2.1 推荐：OpenAI 兼容视频任务接口

```http
POST /v1/videos
GET  /v1/videos/{task_id}
GET  /v1/videos/{task_id}/content
```

`POST /v1/videos` 提交任务，返回视频任务 ID。客户端轮询 `GET /v1/videos/{task_id}` 获取状态。任务完成后，可以读取响应里的 URL，也可以通过 `/v1/videos/{task_id}/content` 代理获取视频文件流。

### 2.2 兼容：旧视频任务接口

```http
POST /v1/videos/generations
GET  /v1/videos/generations/{task_id}

POST /v1/video/generations
GET  /v1/video/generations/{task_id}
```

旧接口仍可用，但新接入推荐 `/v1/videos`。

### 2.3 认证

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## 3. 快速选型

| 你想做什么 | 推荐模型 | 关键输入 | 能力标识 |
| --- | --- | --- | --- |
| 根据提示词生成视频 | `grok-imagine` | `prompt` + `duration` | 自动推断 |
| 让一张图片动起来 | `grok-imagine` | `prompt` + `image` + `duration` | 自动推断 |
| 多张参考图生成视频 | `grok-imagine` | `prompt` + `images` + `duration` | 自动推断 |
| 编辑已有视频 | `grok-imagine` | `prompt` + `video` + `extra_body.operation=edit_video`，建议带 `extra_body.input_video_seconds` | `edit_video` |
| 续写已有视频 | `grok-imagine` | `prompt` + `video` + `duration` + `extra_body.operation=video_extend`，建议带 `extra_body.input_video_seconds` | `video_extend` |

说明：`extra_body.operation` 是本站稳定能力提示。输入形态明确时平台会自动推断；视频编辑和续写都传 `video`，建议显式传 `extra_body.operation` 消歧。

## 4. 参数说明

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 固定传 `grok-imagine` |
| `prompt` | string | 是 | 视频生成、编辑或续写提示词 |
| `image` | string/object | 图生视频必填 | 单张图片 URL；也支持 `{ "url": "..." }` |
| `images` | string[] | 多参考图必填 | 多张参考图片 URL |
| `image_url` / `image_urls` | string/string[] | 否 | 图片输入兼容字段 |
| `video` | string/object | 编辑/续写必填 | 源视频 URL；也支持 `{ "url": "..." }` |
| `videos` | string[] | 否 | 参考视频 URL 数组，适合参考视频类能力 |
| `size` | string | 否 | 清晰度，常用 `480p`、`720p`；视频续写可能不支持该参数 |
| `aspect_ratio` | string | 否 | 输出比例；文生视频常用 `16:9`、`1:1`、`9:16`，单图生视频可用 `auto` |
| `duration` | integer/string | 条件必填 | 输出秒数。文生、图生、多参考图和续写使用；视频编辑不要传该字段 |
| `seconds` | string | 条件必填 | OpenAI 兼容秒数字段；未传 `duration` 时可传 `seconds`，不要和 `duration` 同时传 |
| `extra_body.operation` | string | 否 | 稳定能力提示：`text_to_video`、`image_to_video`、`reference_to_video`、`edit_video`、`video_extend` |
| `extra_body.input_video_seconds` | integer | 编辑/续写建议传 | 源视频可计费秒数提示，传正整数秒。知道源视频秒数时建议传；未传时平台会探测或使用兜底值 |

## 5. 秒数规则

文生、图生、多参考图和续写都要传输出秒数。视频编辑不要传输出秒数。

| 场景 | 输出秒数字段 | 支持取值 | 输入视频秒数 |
| --- | --- | --- | --- |
| 文生视频 | `duration` 或 `seconds` | `1-15` 的整数秒 | 不需要 |
| 单图生视频 | `duration` 或 `seconds` | `1-15` 的整数秒 | 不需要 |
| 多参考图生视频 | `duration` 或 `seconds` | `1-10` 的整数秒 | 不需要 |
| 视频编辑 | 不传 `duration` / `seconds` | 不适用 | 建议传 `extra_body.input_video_seconds` |
| 视频续写 | `duration` 或 `seconds` | `2-10` 的整数秒 | 建议传 `extra_body.input_video_seconds` |

说明：

- 推荐使用 `duration`，例如 `"duration": 6`。
- 如果客户端只能使用 OpenAI 兼容字段，可以传 `seconds`，例如 `"seconds": "6"`。
- `duration` 和 `seconds` 二选一，不要同时传。
- 视频编辑和续写的 `extra_body.input_video_seconds` 是源视频秒数提示，不是输出秒数。
- 如果不确定源视频秒数，可以不传 `extra_body.input_video_seconds`；平台会探测输入视频时长，并在计费记录里展示秒数来源。
- 计费最终不会只信任用户传参，而是按任务结算记录中的输入/输出秒数来源结算。

## 6. 能力标识选择规则

大多数情况下不需要手动传 `extra_body.operation`：

- 没有图片和视频：文生视频。
- 有一张 `image`：图生视频。
- 有多张 `images`：参考图生视频。
- 有 `video`：建议显式传 `edit_video` 或 `video_extend`。

当你要编辑已有视频：

```json
{
  "extra_body": {
    "operation": "edit_video",
    "input_video_seconds": 8
  }
}
```

当你要续写已有视频：

```json
{
  "duration": 6,
  "extra_body": {
    "operation": "video_extend",
    "input_video_seconds": 8
  }
}
```

## 7. 完整请求示例

### 7.1 文生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine",
    "prompt": "电影感手持镜头，一名记者站在暴雪中的时代广场，路人撑伞快速走过，雪花不断打在镜头前，皮肤纹理真实，整体色调克制。",
    "size": "720p",
    "aspect_ratio": "16:9",
    "duration": 6
  }'
```

典型提交响应：

```json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video",
  "model": "grok-imagine",
  "status": "queued",
  "progress": 0,
  "created_at": 1773980459,
  "seconds": "6"
}
```

### 7.2 单图生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine",
    "prompt": "人物缓慢转头看向镜头，头发随风轻微摆动，电影级布光，镜头有细微推进。",
    "image": "https://example.com/portrait.png",
    "size": "480p",
    "aspect_ratio": "auto",
    "duration": 10
  }'
```

### 7.3 多参考图生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine",
    "prompt": "让 @Image1 中的人物走进 @Image2 的霓虹街景，保持人物身份一致，镜头缓慢推进。",
    "images": [
      "https://example.com/person.png",
      "https://example.com/street.png"
    ],
    "size": "720p",
    "aspect_ratio": "4:3",
    "duration": 10
  }'
```

### 7.4 视频编辑

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine",
    "prompt": "把这段视频改成电影感动漫风，同时保留原本动作节奏和构图。",
    "video": "https://example.com/source.mp4",
    "size": "720p",
    "extra_body": {
      "operation": "edit_video",
      "input_video_seconds": 8
    }
  }'
```

视频编辑不要传 `duration` / `seconds`。如果知道源视频秒数，建议传 `extra_body.input_video_seconds`，这样预估和日志更清楚；未传时平台会探测或使用兜底值。

### 7.5 视频续写

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine",
    "prompt": "延续镜头运动，逐渐露出远处城市天际线，保持原视频色调和运动方向。",
    "video": "https://example.com/source.mp4",
    "duration": 6,
    "extra_body": {
      "operation": "video_extend",
      "input_video_seconds": 8
    }
  }'
```

视频续写的 `duration` 表示输出续写秒数，支持 `2-10` 秒。如果知道源视频秒数，建议同时传 `extra_body.input_video_seconds`。

## 8. 任务状态与结果

创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。

## 9. 计费说明

Grok 视频在本站使用组件式计费，公开价格以模型广场展示为准。

| 场景 | 主要计费项 |
| --- | --- |
| 文生视频 | 清晰度档、输出视频秒数 |
| 单图生视频 | 清晰度档、输出视频秒数 |
| 多参考图生视频 | 清晰度档、输出视频秒数 |
| 视频编辑 | 清晰度档、输入视频秒数、输出视频秒数 |
| 视频续写 | 输入视频秒数、输出视频秒数 |

公开展示会显示“按实际参数计算”和组件单价，例如：

- 输入视频：按秒
- 输出视频 480P：按秒
- 输出视频 720P：按秒

图生视频和多参考图生视频中的输入图片数量可能出现在结算 facts 里，但第一版 Grok 视频规则不应把它配置成单独收费组件。

提交时可能有预扣。预扣用于任务提交阶段的余额锁定，不是把某个最大值当成单次公开售价。

## 10. 常见错误

### 把视频模型发到图片接口

`grok-imagine` 应调用 `/v1/videos`，不要发到 `/v1/images/generations`。

### 编辑和续写都只传了 `video`

这会产生歧义。编辑传：

---

# Grok Imagine Image

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/grok/grok-imagine-image
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/grok/grok-imagine-image.md
Description: Grok Imagine 图片来源文档。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

更新时间：2026-05-29

本文说明如何在本站调用 Grok Imagine 图片模型。用户只需要使用本站稳定模型名和 OpenAI 兼容图片接口。

## 1. 可用模型

| 模型 | 适用场景 | 计费口径 |
| --- | --- | --- |
| `grok-imagine-image` | 标准文生图、图片编辑 | 按输出图片、输入图片等组件计费 |
| `grok-imagine-image-quality` | 更高质量的文生图、图片编辑 | 按质量档、清晰度、图片数量等组件计费 |

推荐普通生成和编辑先使用 `grok-imagine-image`。需要更高质量或更高分辨率时使用 `grok-imagine-image-quality`。

## 2. 接口概览

### 2.1 推荐：异步图片任务

```http
POST /v1/images/tasks
GET  /v1/images/tasks/{task_id}
```

异步任务适合 Grok 这类可能耗时较长的媒体生成。它支持文生图、图生图，且能透传本站支持的媒体参数，例如 `resolution`、`aspect_ratio`、`output_format`、`num_images`。

### 2.2 兼容：OpenAI 图片接口

```http
POST /v1/images/generations
POST /v1/images/edits
```

这两个接口适合已经按 OpenAI 图片格式接入的客户端。`/v1/images/edits` 支持 JSON 图片 URL，也支持 `multipart/form-data` 上传图片文件。

### 2.3 认证

所有接口都使用 Bearer Token：

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## 3. 快速开始

### 3.1 异步文生图

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image",
    "task_type": "text2image",
    "prompt": "高端腕表广告图，黑色背景，金属反光克制，产品细节清晰，商业摄影，柔和轮廓光",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "output_format": "jpeg",
    "num_images": 1,
    "response_format": "url"
  }'
```

提交成功后会返回任务 ID：

```json
{
  "task_id": "task_xxx",
  "status": "queued",
  "progress": "0%",
  "result_url": "",
  "metadata": {
    "task_type": "text2image"
  },
  "error": null
}
```

查询任务：

```bash
curl "{BASE_URL}/v1/images/tasks/task_xxx" \
  -H "Authorization: Bearer sk-***"
```

完成后的典型响应：

```json
{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxx",
    "status": "succeeded",
    "progress": "100%",
    "result_url": "https://example.com/result-1.jpeg",
    "metadata": {
      "task_type": "text2image",
      "result_count": 1,
      "result_urls": [
        "https://example.com/result-1.jpeg"
      ]
    },
    "error": null
  }
}
```

### 3.2 异步图片编辑

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-quality",
    "task_type": "image2image",
    "prompt": "保持主体结构不变，把画面改成奢侈品广告摄影风格，黑金色调，背景干净，产品边缘清晰",
    "image": "https://example.com/source-watch.png",
    "aspect_ratio": "auto",
    "resolution": "2k",
    "output_format": "webp",
    "num_images": 2,
    "response_format": "url"
  }'
```

### 3.3 多参考图编辑

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-quality",
    "task_type": "image2image",
    "prompt": "把第一张图的产品放到第二张图的展台环境里，保持产品比例和材质一致，输出商业海报风格",
    "images": [
      "https://example.com/product.png",
      "https://example.com/stage.png"
    ],
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "output_format": "png",
    "num_images": 1,
    "response_format": "url"
  }'
```

### 3.4 同步文生图兼容调用

```bash
curl -X POST "{BASE_URL}/v1/images/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image",
    "prompt": "一张科技产品发布会主视觉，银色设备悬浮在深色舞台中央，灯光克制，高级感",
    "n": 1,
    "response_format": "url"
  }'
```

典型响应：

```json
{
  "created": 1773980459,
  "data": [
    {
      "url": "https://example.com/image.png",
      "revised_prompt": ""
    }
  ]
}
```

### 3.5 同步图片编辑兼容调用

JSON 图片 URL：

```bash
curl -X POST "{BASE_URL}/v1/images/edits" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image",
    "prompt": "保留人物身份，把背景替换成夜晚城市街头，电影感，浅景深",
    "image": "https://example.com/person.png",
    "n": 1,
    "response_format": "url"
  }'
```

multipart 文件上传：

```bash
curl -X POST "{BASE_URL}/v1/images/edits" \
  -H "Authorization: Bearer sk-***" \
  -F "model=grok-imagine-image" \
  -F "prompt=保留主体，改成高级棚拍产品图" \
  -F "n=1" \
  -F "response_format=url" \
  -F "image=@/path/to/source.png"
```

## 4. 参数说明

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `grok-imagine-image` 或 `grok-imagine-image-quality` |
| `prompt` | string | 是 | 生成或编辑提示词 |
| `task_type` | string | 否 | 异步任务使用，`text2image` 或 `image2image`；不传时平台会按是否有图片输入推断 |
| `image` | string | 图生图必填 | 单张输入图片 URL；同步编辑和异步编辑都支持 |
| `images` | string[] | 多图编辑必填 | 多张参考图 URL；推荐新接入使用该字段 |
| `image_url` | string | 否 | 单图 URL 兼容字段 |
| `image_urls` | string[] | 否 | 多图 URL 兼容字段 |
| `aspect_ratio` | string | 否 | 输出比例；文生图常用 `1:1`、`16:9`、`9:16`、`4:3`、`3:4`，图片编辑可用 `auto` |
| `resolution` | string | 否 | 清晰度档，常用 `1k`、`2k`；推荐在 `/v1/images/tasks` 中使用 |
| `output_format` | string | 否 | `jpeg`、`png`、`webp` |
| `num_images` | integer | 否 | 生成图片数量，通常 `1-4`；异步任务推荐使用 |
| `n` | integer | 否 | OpenAI 兼容数量字段，默认 `1` |
| `response_format` | string | 否 | 推荐 `url` |

输入图建议：

- 单图用 `image`。
- 多图用 `images`。
- 不要同时混用 `image`、`image_url`、`images`、`image_urls`，避免重复输入。

## 5. 计费说明

Grok 图片在本站使用组件式计费，公开价格以模型广场展示为准。

| 场景 | 主要计费项 |
| --- | --- |
| 文生图 | 输出图片数量、清晰度档、质量档 |
| 图片编辑 | 输入图片数量、输出图片数量、清晰度档、质量档 |

公开价格以模型广场展示的组件单价为准，例如“输出图片 / 张”“输入图片 / 张”“高清输出图片 / 张”。提交时可能存在预扣，但预扣是任务风控和余额锁定，不等同于最终公开单价。

## 6. 常见错误

### 把视频模型发到图片接口

`grok-imagine` 是视频模型，应调用 `/v1/videos` 或兼容视频任务接口。

### 图片编辑没有传图片

`/v1/images/edits` 和 `task_type=image2image` 都必须传 `image` 或 `images`。

### 文生图传 `aspect_ratio=auto`

`auto` 更适合图片编辑。文生图建议明确传 `1:1`、`16:9`、`9:16` 等比例。

### 同步接口和异步接口混用字段

如果需要 `resolution`、`num_images` 等 Grok 媒体参数，优先使用 `/v1/images/tasks`。同步兼容接口适合简单 OpenAI 图片客户端。

---

# Grok Video 1.5

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/grok/grok-video-1-5
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/grok/grok-video-1-5.md
Description: 通过 UniAll 异步视频接口使用 Grok Video 1.5 创建文生视频、单图生视频和多参考图视频任务。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

更新时间：2026-08-03

公共模型 `grok-video-1.5` 支持文生视频、单图生视频和多参考图生视频。通过 UniAll 异步视频接口提交任务，然后轮询任务，直到任务完成或失败。

## 1. 能力范围

| 生成方式 | 图片输入 | `prompt` | 最高分辨率 |
| --- | --- | --- | --- |
| 文生视频 | 不传图片字段 | 必填 | `1080p` |
| 单图生视频 | 一个 `image` 或 `image_url` | 可选 | `1080p` |
| 参考图生视频 | 1 到 7 个 `reference_images` 或 `reference_image_urls` | 必填 | `720p` |

本模型还支持：

- `1` 到 `15` 秒，默认 `8` 秒；
- `480p`、`720p`、`1080p`，默认 `480p`；
- `auto`、`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3` 画面比例；
- HTTP(S) 图片 URL 和完整的图片 Data URL。

本公共模型不开放参考音频、源视频编辑或视频续写。编辑和续写请继续使用现有 Grok Imagine 视频模型。

## 2. 适用场景

以下场景适合使用 `grok-video-1.5`：

- 只用提示词生成视频；
- 让一张图片动起来，可选是否补充提示词；
- 使用 1 到 7 张参考图保持人物、商品或视觉风格一致；
- 文生视频或单图生视频需要最高 `1080p` 输出。

首尾帧、参考音频、视频编辑和视频续写不属于本模型能力。

## 3. 接口与鉴权

新接入建议使用以下主要接口：

| 用途 | 方法 | 路径 |
| --- | --- | --- |
| 创建视频任务 | `POST` | `/v1/videos` |
| 查询视频任务 | `GET` | `/v1/videos/{task_id}` |

兼容的 `/v1/videos/generations` 创建和查询路径继续可用。

所有请求均需使用 Bearer Token：

```http
Authorization: Bearer sk-***
```

创建任务时还需携带：

```http
Content-Type: application/json
```

## 4. 请求体参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 固定传 `grok-video-1.5`。 |
| `prompt` | string | 条件必填 | 文生视频和参考图生视频必填；单图生视频可选。 |
| `duration` | integer 或整数字符串 | 否 | `1` 到 `15`，默认 `8`。 |
| `seconds` | integer 或整数字符串 | 否 | `duration` 的兼容别名；同时传入时两者必须一致。 |
| `resolution` | string | 否 | `480p`、`720p`、`1080p`，默认 `480p`；参考图生视频最高 `720p`。 |
| `size` | string | 否 | `resolution` 的兼容别名；同时传入时两者必须一致。 |
| `aspect_ratio` | string | 否 | `auto`、`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`。 |
| `image` | object | 否 | 单张结构化图片，固定形式为 `{"url":"..."}`。 |
| `image_url` | string | 否 | 单图兼容字段。 |
| `reference_images` | object[] | 否 | 1 到 7 张结构化参考图，形式为 `[{"url":"..."}]`。 |
| `reference_image_urls` | string[] | 否 | 兼容字段，包含 1 到 7 个图片 URL 或 Data URL。 |

新接入建议优先使用 `duration`、`resolution` 以及结构化的 `image` 或 `reference_images` 字段。

### 图片字段选择

四个图片字段互斥。图片类请求只能选择其中一个：

| 输入形式 | 使用字段 |
| --- | --- |
| 单张结构化图片 | `image: {"url":"..."}` |
| 单张兼容字符串 | `image_url: "..."` |
| 多张结构化参考图 | `reference_images: [{"url":"..."}]` |
| 多张兼容字符串参考图 | `reference_image_urls: ["..."]` |

不要在同一个请求中混用单图字段和参考图字段。

### 支持的图片值

每个图片值必须是以下形式之一：

- 服务端可访问的 `http://` 或 `https://` URL；
- 完整的图片 Data URL，例如 `data:image/png;base64,...`。

裸 Base64、本机路径、依赖浏览器登录态的 URL、`images`、`image_urls` 以及任何形式的 `file_id` 都会被拒绝。

## 5. 请求示例

### 5.1 文生视频

下面的请求使用 `1080p` 和默认 8 秒时长：

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-video-1.5",
    "prompt": "A quiet mountain lake at sunrise, gentle camera movement, realistic reflections.",
    "resolution": "1080p",
    "aspect_ratio": "16:9"
  }'
```

### 5.2 使用 HTTP URL 的单图生视频

单图生视频可以不传提示词：

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-video-1.5",
    "image": {
      "url": "https://example.com/product.jpg"
    },
    "duration": 6,
    "resolution": "720p"
  }'
```

### 5.3 使用 Data URL 的单图生视频

必须传入包含媒体类型和 Base64 前缀的完整 Data URL：

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-video-1.5",
    "prompt": "Subtle camera push-in and natural fabric movement.",
    "image_url": "data:image/png;base64,iVBORw0KGgo...",
    "duration": 5,
    "size": "480p",
    "aspect_ratio": "9:16"
  }'
```

### 5.4 多参考图生视频

参考图生视频接受 1 到 7 张图片，分辨率只支持 `480p` 或 `720p`：

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-video-1.5",
    "prompt": "Keep the character identity and clothing consistent while the character turns toward the camera.",
    "reference_images": [
      {"url": "https://example.com/character-front.jpg"},
      {"url": "https://example.com/character-side.jpg"}
    ],
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "9:16"
  }'
```

## 6. 响应示例

### 任务创建成功

请保存 `id` 或兼容字段 `task_id`，后续用于查询任务。

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "grok-video-1.5",
  "status": "queued",
  "raw_status": "PENDING",
  "progress": 0,
  "created_at": 1785715200,
  "video_url": null
}
```

## 7. 任务状态与结果

创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。

## 8. 画面比例行为

- 文生视频未传 `aspect_ratio` 时，实际默认值通常为 `16:9`。
- 单图生视频未传时，输出通常跟随输入图片比例。
- `auto` 作为兼容值继续接受。
- 如需稳定构图，请提前把源图和参考图处理为目标输出方向。

## 9. 计费说明

本文档不定义精确用户价格。归一后的时长、分辨率和输入图片数量都会影响计费：

- 未传时长时，按默认 8 秒计算；
- 文生视频没有输入图片计费维度；
- 单图生视频计 1 张输入图；
- 参考图生视频按实际参考图数量计算；
- 更高分辨率通常价格更高。

请在 UniAll 控制台查看当前价格，并在任务创建后核对账户用量。原任务进入终态前，不要重复提交。

## 10. 常见错误

### 缺少 `prompt`

文生视频和参考图生视频必须传 `prompt`。只有单图生视频可以省略提示词。

### 图片字段冲突

不要混用 `image`、`image_url`、`reference_images` 或 `reference_image_urls`，只能选择其中一个。

### 图片编码不合法

请使用 HTTP(S) URL 或完整 Data URL。`iVBORw0KGgo...` 这样的裸 Base64 字符串无效。

### 参考图生视频请求 `1080p`

参考图生视频最高支持 `720p`。请改用 `480p` 或 `720p`；如需 `1080p`，应使用文生视频或单图生视频。

### 参考图数量超限

`reference_images` 和 `reference_image_urls` 只接受 1 到 7 张图片。空数组或超过 7 张都会被拒绝。

### 传入未开放字段

不要传 `file_id`、`reference_audios`、`reference_audio_urls`、`voice_id`、`output`、`storage_options` 或 `user`，也不要把它们放进 `extra_body`。

### 请求不支持的视频操作

参考音频、首尾帧、视频编辑和视频续写不属于 `grok-video-1.5`。

## 11. 从旧契约迁移

| 项目 | 旧契约 | 当前契约 |
| --- | --- | --- |
| 生成方式 | 仅单图生视频 | 文生、单图、1 到 7 张参考图生视频 |
| 图片字段 | 仅 `image_url` | 结构化 `image` / `reference_images`，同时保留兼容 URL 字段 |
| 图片值 | 仅 HTTP(S) URL | HTTP(S) URL 或完整图片 Data URL |
| 单图提示词 | 必填 | 可选 |
| 时长 | 必填整数 `duration` | `duration` 或 `seconds`，`1..15`，默认 `8` |
| 分辨率 | `480p` 或 `720p` | 文生和单图新增 `1080p` |
| 画面比例 | 六种比例和 `auto` | 新增 `4:3`、`3:4` |

不要迁移到渠道原生模型名或文件 ID。继续使用稳定公共模型 `grok-video-1.5` 和 UniAll 任务接口。

## 12. 相关页面

- [查询余额](/zh-CN/balance)
- [Grok Imagine 视频生成](/zh-CN/models/video/grok-imagine)
- [Grok Imagine 图片生成](/zh-CN/models/video/grok/grok-imagine-image)

---

# Hailuo

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/hailuo
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/hailuo.md
Description: 通过 UniAll 视频任务接口调用 Hailuo 系列，创建文生、单图和首尾帧视频。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

更新时间：2026-08-04

## 概览

UniAll 通过 OpenAI 兼容的异步视频任务接口提供三个稳定的 Hailuo 公共模型。

| 模型 | 文生视频 | 单图生视频 | 首尾帧生视频 |
| --- | --- | --- | --- |
| `hailuo-02` | 支持 | 支持 | 支持 |
| `hailuo-2.3` | 支持 | 支持 | 不支持 |
| `hailuo-2.3-fast` | 不支持 | 支持 | 不支持 |

三个模型统一使用创建、查询和内容下载接口，请求字段组合决定生成模式。

## 适用场景

Hailuo 系列适合以下任务：

- 根据提示词生成 6 秒或 10 秒视频；
- 让一张可公开访问的图片动起来；
- 使用 `hailuo-02` 生成首尾帧过渡视频；
- 选择 `768p` 或 `1080p` 输出。

Hailuo 公共契约不支持音频、多参考图、参考视频、画幅比例控制或视频编辑。

## 公共限制

- `duration` 必须是 `6` 或 `10` 秒。
- `resolution` 必须是 `768p` 或 `1080p`。
- `1080p` 只支持生成 6 秒视频。
- 输入图片必须是公开可访问的 HTTP(S) URL。
- 提示词最长 2,000 个字符。

## 接口

| 用途 | 方法 | 路径 |
| --- | --- | --- |
| 创建视频任务 | `POST` | `/v1/videos` |
| 查询视频任务 | `GET` | `/v1/videos/{task_id}` |
| 下载视频文件 | `GET` | `/v1/videos/{task_id}/content` |

## 鉴权

所有请求均使用 UniAll Bearer Token：

```http
Authorization: Bearer sk-***
```

创建任务时还需发送：

```http
Content-Type: application/json
```

## 请求体参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `hailuo-02`、`hailuo-2.3` 或 `hailuo-2.3-fast`。 |
| `prompt` | string | 是 | 视频内容描述，最长 2,000 个字符。 |
| `image` | string | 条件必填 | 单图生视频的输入图或首尾帧模式的首帧，必须是公开 HTTP(S) URL。 |
| `last_image` | string | 条件必填 | 尾帧图片的公开 HTTP(S) URL；仅 `hailuo-02` 支持，且必须与 `image` 一起传入。 |
| `duration` | integer | 是 | `6` 或 `10`。 |
| `resolution` | string | 是 | `768p` 或 `1080p`；`1080p` 只支持 6 秒。 |
| `prompt_optimizer` | boolean | 否 | 是否在生成前优化提示词。 |
| `fast_pretreatment` | boolean | 否 | 是否使用快速预处理；首尾帧模式不要传 `true`。 |
| `watermark` | boolean | 否 | 是否添加 AIGC 水印。 |

根据生成模式选择输入字段：

| 模式 | 模型 | 输入字段 |
| --- | --- | --- |
| 文生视频 | `hailuo-02` 或 `hailuo-2.3` | `prompt` |
| 单图生视频 | 任意 Hailuo 模型 | `prompt` + `image` |
| 首尾帧生视频 | `hailuo-02` | `prompt` + `image` + `last_image` |

字段约束：

- 文生视频不要传入 `image` 或 `last_image`。
- `hailuo-2.3-fast` 只支持单图生视频，因此必须传入 `image`。
- `last_image` 不能单独使用，必须与 `image` 一起传入。
- `last_image` 只能与 `hailuo-02` 配合使用。
- 所有支持的公共参数都直接放在请求体顶层。
- 不要传入音频、多参考图数组、参考视频、画幅比例或视频编辑字段。

## 请求示例

### 文生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo-2.3",
    "prompt": "A cinematic train passes through a snowy mountain canyon while morning mist drifts slowly and the camera moves forward.",
    "duration": 6,
    "resolution": "1080p",
    "prompt_optimizer": true,
    "watermark": false
  }'
```

### 单图生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo-2.3-fast",
    "prompt": "The person naturally raises their head and looks at the camera while face and clothing remain consistent.",
    "image": "https://example.com/source.png",
    "duration": 6,
    "resolution": "768p",
    "fast_pretreatment": true,
    "watermark": false
  }'
```

### 首尾帧生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo-02",
    "prompt": "Transition naturally from day to night while the building structure remains stable and the motion stays smooth.",
    "image": "https://example.com/first.png",
    "last_image": "https://example.com/last.png",
    "duration": 6,
    "resolution": "1080p",
    "prompt_optimizer": true,
    "watermark": false
  }'
```

## 响应示例

### 任务创建成功

请保存返回的 `id`，用于后续查询：

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "object": "video",
  "model": "hailuo-2.3",
  "status": "queued",
  "progress": 0,
  "created_at": 1785772800
}
```

## 任务状态与结果

创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。

## 计费说明

所选模型、`duration` 和 `resolution` 会影响计费；`1080p` 不支持 10 秒请求。当前价格和最终扣费以 UniAll 模型页与消费日志为准。

## 常见错误

以下请求会被拒绝：

- 模型不支持当前生成模式；
- `duration` 不是 `6` 或 `10`；
- `1080p` 请求了 10 秒视频；
- `hailuo-2.3-fast` 缺少 `image`；
- 单独传入 `last_image`，或对 `hailuo-02` 以外的模型传入 `last_image`；
- 图片 URL 无法由服务端公开访问；
- 请求音频、参考视频、多参考图、画幅比例控制或视频编辑能力。

传入 `watermark: false` 表示请求关闭 AIGC 水印。最终水印行为还可能受平台可用性与模型策略影响；如果完成结果仍出现非预期水印，请联系 UniAll 支持。

## 相关页面

- [视频生成概览](/zh-CN/models/video/overview)
- [模型列表](/zh-CN/models)

---

# Happy Horse

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/happy-horse
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/happy-horse.md
Description: 通过 UniAll 使用统一的 Happy Horse 模型创建文生、图生、多参考图和视频编辑任务。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

更新时间：2026-08-10

## 概览

UniAll 只对外提供一个稳定的 Happy Horse 公共模型：`happy-horse`。当前公共契约开放 Happy Horse 1.0 的能力，生成方式和输出档位都通过请求参数选择，不再拆分成多个模型名。

| 能力 | `operation` | 必需素材 | 分辨率 |
| --- | --- | --- | --- |
| 文生视频 | `text_to_video` | 无 | `720p`、`1080p` |
| 图生视频 | `image_to_video` | 恰好 1 张图片 | `720p`、`1080p` |
| 多参考图生视频 | `reference_to_video` | 1 至 9 张图片 | `720p`、`1080p` |
| 视频编辑 | `edit_video` | 恰好 1 个视频，可选 0 至 5 张图片 | `720p`、`1080p` |

历史档位模型名不再兼容。所有请求都必须使用 `model: "happy-horse"`，并同时传入 `operation` 和 `resolution`。

公共 HappyHorse 1.0 契约不开放 `480p`，使用该分辨率的请求会在任务创建前被拒绝。

## 适用场景

使用 `happy-horse` 可以：

- 根据文字提示词生成视频；
- 让一张源图片动起来并尽量保持原始构图；
- 通过多张参考图保持人物、商品或视觉风格一致；
- 编辑已有视频，并选择保留原音频或自动处理音频。

## 接口

新接入统一使用以下接口：

| 用途 | 方法 | 路径 |
| --- | --- | --- |
| 创建视频任务 | `POST` | `/v1/videos` |
| 查询视频任务 | `GET` | `/v1/videos/{task_id}` |
| 获取完成后的视频 | `GET` | `/v1/videos/{task_id}/content` |

兼容的 `/v1/videos/generations` 和 `/v1/video/generations` 创建、查询路径仍可使用。新客户端建议统一使用 `/v1/videos`。

## 鉴权

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## 快速请求示例

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse",
    "operation": "text_to_video",
    "resolution": "1080p",
    "prompt": "A white horse runs across a misty grassland at sunrise, cinematic camera movement.",
    "duration": 7,
    "aspect_ratio": "16:9",
    "seed": 12345,
    "watermark": false
  }'
```

创建响应会同时返回 `id` 和兼容字段 `task_id`。保存其中任意一个值，用于后续轮询。

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "happy-horse",
  "status": "queued",
  "progress": 0,
  "created_at": 1785801600,
  "video_url": null
}
```

## 任务状态与结果

创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。

## 计费说明

- 生成任务按操作类型、选择的分辨率档位和生成时长计费。
- 视频编辑根据实际输入和输出视频时长进行最终结算，因此最终费用可能与提交时预估不同。
- `resolution` 选择的是公共服务档位，不保证每种画幅和源图片都对应同一个固定像素尺寸；对像素尺寸有严格要求时应检查成品媒体信息。
- 最终价格以 UniAll 当前价格页和任务结算记录为准。

## 常见错误

- 使用已删除的旧档位模型名，而不是 `happy-horse`。
- 缺少必填的 `operation` 或 `resolution`。
- 传入 `resolution: "480p"`；应使用 `720p` 或 `1080p`。
- 传入 `size`；Happy Horse 只使用 `resolution`，并会拒绝 `size`。
- `edit_video` 请求传入 `duration` 或 `aspect_ratio`。
- `image_to_video` 请求传入 `aspect_ratio`；图生视频画面比例跟随源图片。
- 媒体 URL 是私有地址、已过期或无法从公网访问。

## 相关页面

- [创建 Happy Horse 任务](/zh-CN/models/video/happy-horse/create-task)
- [视频生成概览](/zh-CN/models/video/overview)

---

# 创建 Happy Horse 视频任务

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/happy-horse/create-task
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/happy-horse/create-task.md
Description: 使用统一的 happy-horse 模型创建文生、图生、多参考图和视频编辑任务。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

更新时间：2026-08-10

## 概览

所有能力都使用唯一公共模型 `happy-horse`。通过 `operation` 选择文生、图生、多参考图或视频编辑，通过 `resolution` 选择输出档位。

不要使用已删除的旧档位模型名。旧名字与当前公共契约不兼容。

## 接口

```http
POST /v1/videos
```

兼容的创建路径：

```http
POST /v1/videos/generations
POST /v1/video/generations
```

新接入建议使用 `/v1/videos`。

## 鉴权

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## 能力矩阵

| `operation` | 提示词 | 图片输入 | 视频输入 | 分辨率 | `duration` | `aspect_ratio` |
| --- | --- | --- | --- | --- | --- | --- |
| `text_to_video` | 必填 | 不接受 | 不接受 | `720p`、`1080p` | 可选，默认 `5` | 可选，默认 `16:9` |
| `image_to_video` | 可选 | 恰好 1 张 | 不接受 | `720p`、`1080p` | 可选，默认 `5` | 不支持 |
| `reference_to_video` | 必填 | 1 至 9 张 | 不接受 | `720p`、`1080p` | 可选，默认 `5` | 可选，默认 `16:9` |
| `edit_video` | 必填 | 0 至 5 张 | 恰好 1 个 | `720p`、`1080p` | 不支持 | 不支持 |

## 请求体参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 固定为 `happy-horse`。 |
| `operation` | string | 是 | `text_to_video`、`image_to_video`、`reference_to_video` 或 `edit_video`。 |
| `resolution` | string | 是 | 所有操作均支持 `720p` 或 `1080p`。 |
| `prompt` | string | 条件必填 | 除 `image_to_video` 外均必填，最长 `2500` 字符。 |
| `duration` | integer | 否 | 仅生成使用，范围 `3` 至 `15`，默认 `5`；编辑请求不能传。 |
| `aspect_ratio` | string | 否 | 仅文生和多参考图生视频使用；图生和编辑请求不能传。 |
| `image` | string | 条件必填 | `image_to_video` 推荐使用的单张 HTTP(S) 图片字段。 |
| `images` | string[] | 条件必填 | `reference_to_video` 使用的 1 至 9 张 HTTP(S) 图片。 |
| `reference_image_urls` | string[] | 否 | 多参考图的别名；视频编辑也可使用，最多 5 张。 |
| `video` | string | 条件必填 | `edit_video` 使用的单个 HTTP(S) 源视频。 |
| `seed` | integer | 否 | 随机种子，范围 `0` 至 `2147483647`。 |
| `watermark` | boolean | 否 | 是否添加水印，默认 `false`。 |
| `audio_setting` | string | 否 | 仅编辑使用：`auto` 或 `origin`，默认 `auto`。 |

文生和多参考图生视频支持以下 `aspect_ratio`：

- `16:9`
- `9:16`
- `1:1`
- `4:3`
- `3:4`
- `4:5`
- `5:4`
- `9:21`
- `21:9`

`size` 和 `enable_safety_checker` 不属于 Happy Horse 公共参数，传入会被拒绝。

公共 HappyHorse 1.0 契约不开放 `480p`。把 `resolution` 设为 `480p` 的请求会在
任务创建前被拒绝。

## 输入规则

| 模式 | 可用素材字段 |
| --- | --- |
| 文生视频 | 不传图片或视频字段 |
| 图生视频 | 使用 `image`，或通过受支持的图片别名传入恰好 1 张图片 |
| 多参考图生视频 | 使用 `images` 或 `reference_image_urls`，传入 1 至 9 个 URL |
| 视频编辑 | 使用 `video`，并可选传入最多 5 个 `reference_image_urls` |

所有媒体输入都必须是完整、可公开访问的 HTTP 或 HTTPS URL。当前模型契约不接受文件上传、裸 Base64 或 Data URL。

## 请求示例

### 文生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse",
    "operation": "text_to_video",
    "resolution": "1080p",
    "prompt": "A white horse runs across a misty grassland at sunrise, realistic movement and soft rim light.",
    "duration": 7,
    "aspect_ratio": "21:9",
    "seed": 12345,
    "watermark": false
  }'
```

### 图生视频

输出构图跟随源图片，因此不要传 `aspect_ratio`。

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse",
    "operation": "image_to_video",
    "resolution": "720p",
    "image": "https://example.com/source-frame.png",
    "prompt": "The subject walks forward naturally while the camera slowly pushes in.",
    "duration": 5,
    "seed": 67890,
    "watermark": false
  }'
```

`image_to_video` 可以省略提示词。

### 多参考图生视频

提示词可以使用 `character1` 至 `character9`，按数组顺序指代参考图。

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse",
    "operation": "reference_to_video",
    "resolution": "720p",
    "prompt": "character1 drives character2 across the lunar surface while both identities remain consistent.",
    "reference_image_urls": [
      "https://example.com/character.png",
      "https://example.com/vehicle.png"
    ],
    "duration": 8,
    "aspect_ratio": "16:9",
    "seed": 24680,
    "watermark": false
  }'
```

### 视频编辑

编辑时长跟随源视频，不能传 `duration` 或 `aspect_ratio`。

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse",
    "operation": "edit_video",
    "resolution": "1080p",
    "prompt": "Replace the jacket with the referenced red jacket while preserving identity, motion, camera movement, and background.",
    "video": "https://example.com/source-video.mp4",
    "reference_image_urls": [
      "https://example.com/red-jacket.png"
    ],
    "audio_setting": "origin",
    "seed": 13579,
    "watermark": false
  }'
```

使用 `audio_setting: "origin"` 保留原音频；使用 `auto` 让服务自动决定音频处理方式。

## `extra_body` 兼容

推荐把公共参数直接放在请求体顶层。兼容客户端也可以把 `operation`、`resolution`、`seed`、`watermark` 和 `audio_setting` 放入 `extra_body`。不要在顶层和 `extra_body` 中传入互相冲突的值。

```json
{
  "model": "happy-horse",
  "prompt": "Turn the room into a warm wooden studio.",
  "video": "https://example.com/source-video.mp4",
  "extra_body": {
    "operation": "edit_video",
    "resolution": "720p",
    "audio_setting": "auto",
    "watermark": false
  }
}
```

## 响应示例

### 任务已受理

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "happy-horse",
  "status": "queued",
  "progress": 0,
  "created_at": 1785801600,
  "video_url": null
}
```

## 任务状态与结果

创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。

视频编辑等最终结算操作应在任务完成后再次读取 `billing_contract`。

## 素材限制

### 图生视频源图片

- 格式：JPEG、JPG、PNG、BMP 或 WebP。
- 最小尺寸：`300px`。
- 画面比例：`1:2.5` 至 `2.5:1`。
- 最大文件：`10MB`。

### 多参考图

- 格式：JPEG、JPG、PNG 或 WebP。
- 数量：1 至 9 张。
- 最短边至少 `400px`，建议 720p 以上。
- 每张最大 `10MB`。

### 视频编辑源素材

- 格式：MP4 或 MOV，推荐 H.264。
- 输入时长：3 至 60 秒；编辑服务最多处理 15 秒。
- 尺寸：长边不超过 `2160px`，短边不小于 `320px`。
- 画面比例：`1:2.5` 至 `2.5:1`。
- 帧率：大于 `8fps`。
- 最大文件：`100MB`。

编辑参考图支持 JPEG、JPG、PNG 或 WebP，尺寸至少 `300px`，每张最大 `10MB`。

## 计费说明

- 文生、图生和多参考图生成按请求的输出时长与分辨率档位结算。
- 视频编辑根据实际输入和输出视频时长进行最终结算，最终费用可能与提交时预估不同。
- `resolution` 是服务档位，不保证每种画幅或源图片都对应一个固定像素尺寸。
- 最终金额以 UniAll 当前价格页和任务结算记录为准。

## 常见错误

| 错误 | 原因 | 处理方式 |
| --- | --- | --- |
| 模型名无效 | 使用了已删除的旧档位模型名 | 把 `model` 改为 `happy-horse` |
| 缺少参数 | 未传 `operation` 或 `resolution` | 显式传入两个参数 |
| 参数不支持 | 传入了 `size` 或 `enable_safety_checker` | 删除不支持的字段 |
| 素材数量不正确 | 当前操作收到错误数量的图片或视频 | 按能力矩阵调整素材 |
| 分辨率不正确 | `resolution` 为 `480p` 或其他不支持的值 | 使用 `720p` 或 `1080p` |
| 编辑参数不正确 | 编辑请求包含 `duration` 或 `aspect_ratio` | 删除不支持字段 |
| 素材下载失败 | URL 私有、过期、重定向异常或无法访问 | 使用稳定的公开 HTTPS URL |

## 相关页面

- [Happy Horse 视频生成](/zh-CN/models/video/happy-horse)
- [视频生成概览](/zh-CN/models/video/overview)

---

# Kling

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/kling
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/kling.md
Description: 通过 UniAll 创建可灵文生、图生、参考、动作控制和视频编辑任务。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

## 概览

可灵视频能力统一使用稳定的版本级模型名。通过请求体顶层的 `resolution` 选择清晰度，通过 `operation` 选择生成方式；不要把清晰度、声音或上游路由写进模型名。

| 模型 | 视频能力 | 清晰度 |
| --- | --- | --- |
| `kling-v3-turbo` | 文生视频、单首帧图生视频 | `720p`、`1080p` |
| `kling-v3` | 文生视频、图生视频、首尾帧、动作控制、数字人 | `std`、`pro` |
| `kling-v3-omni` | 文生视频、图生视频、首尾帧、多模态参考、视频编辑 | `std`、`pro` |
| `kling-o1` | 文生视频、图生视频、首尾帧、多模态参考、视频编辑 | `std`、`pro` |

模型是否可用取决于模型广场、API Key 的模型权限和当前启用的路由。历史清晰度、声音、静音和数字人档位模型名不再接受，也不会自动转换。

## 适用场景

- 需要 `720p` 或 `1080p` 的快速文生、单图视频时使用 `kling-v3-turbo`。
- 需要首尾帧、动作控制或数字人时使用 `kling-v3`。
- 需要最多四张参考图的多模态参考或视频编辑时使用 `kling-v3-omni`。
- 需要相同的参考和编辑请求结构、且生成时长为 `3` 到 `10` 秒时使用 `kling-o1`。

## 接口

| 操作 | 方法 | 路径 |
| --- | --- | --- |
| 创建视频任务 | `POST` | `/v1/videos` |
| 查询视频任务 | `GET` | `/v1/videos/{task_id}` |
| 下载已完成的视频 | `GET` | `/v1/videos/{task_id}/content` |

`POST /v1/videos/generations` 和 `POST /v1/video/generations` 仍是兼容创建路径。新接入统一使用 `POST /v1/videos`。

## 鉴权

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## 清晰度与声音

在请求体顶层传入 `resolution`，不要使用 `size` 代替。未传时，Turbo 默认 `720p`，其他可灵视频模型默认 `std`。需要明确输出和计费记录时，建议显式传入。

可灵视频请求不接受 `sound` 开关。需要对白、音乐、环境声或静音效果时，直接写入 `prompt`。数字人任务使用的 `audio_url` 和 `voice_id` 是口型驱动输入，不属于声音开关。

## 生成方式

| `operation` | 支持模型 | 必要输入 |
| --- | --- | --- |
| `text_to_video` | Turbo、V3、Omni、O1 | `prompt` |
| `image_to_video` | Turbo、V3、Omni、O1 | `prompt` 和 `image` |
| `first_last_frame` | V3、Omni、O1 | `prompt`、`image` 和 `last_image` |
| `reference_to_video` | Omni、O1 | `prompt` 和图片或视频参考 |
| `edit_video` | Omni、O1 | `prompt` 和 `video_url`；参考图可选 |
| `motion_control` | V3 | `prompt`、`image`、`video` 和 `character_orientation` |
| `avatar` | V3 | 参见[数字人口播](/zh-CN/models/avatar/digital-human) |

时长规则：

- Turbo 和 V3 的生成 operation 支持 `3` 到 `15` 秒。
- Omni 的文生、图生和首尾帧支持 `3` 到 `15` 秒；`reference_to_video` 支持 `3` 到 `10` 秒。
- O1 的生成 operation 支持 `3` 到 `10` 秒。
- 动作控制、数字人和视频编辑按对应 operation 的结果时长规则处理；除非该 operation 明确支持，否则不要传 `duration`。
- Turbo 文生视频接受 `aspect_ratio`；Turbo 图生视频不接受。

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 稳定的可灵视频模型 ID。 |
| `prompt` | string | 是 | UniAll 视频任务接口要求提供的提示词。 |
| `operation` | string | 建议显式传入 | 上表中的生成方式。 |
| `resolution` | string | 否 | 模型对应的清晰度；默认值见上文。 |
| `duration` | integer | 条件必填 | 支持时长的 operation 的输出秒数。 |
| `aspect_ratio` | string | 条件必填 | `16:9`、`9:16` 或 `1:1`。 |
| `image` | string | 条件必填 | 图生视频图片或首帧的公开 HTTP(S) URL。 |
| `last_image` | string | 条件必填 | 尾帧图片 URL，需与 `image` 同时使用。 |
| `reference_image_urls` | string[] | 否 | 多模态参考或编辑使用的参考图 URL，最多四张。 |
| `video_url` | string | 条件必填 | 多模态参考或编辑使用的基础视频 URL。 |
| `video` | string | 条件必填 | `motion_control` 使用的动作参考视频 URL。 |
| `keep_original_sound` | string | 否 | 多模态参考和视频编辑可使用 `yes` 或 `no`。 |
| `character_orientation` | string | 条件必填 | `motion_control` 使用 `image` 或 `video`。 |
| `watermark` | boolean | 否 | 是否添加 AIGC 水印。 |

## 请求示例

### Turbo 文生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-turbo",
    "operation": "text_to_video",
    "prompt": "一架纸飞机穿过清晨的城市街道，电影感运镜，轻柔环境声。",
    "duration": 3,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "watermark": false
  }'
```

### Turbo 图生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-turbo",
    "operation": "image_to_video",
    "prompt": "纸飞机平稳向前滑翔，镜头缓慢跟随。",
    "image": "https://example.com/plane.png",
    "duration": 5,
    "resolution": "1080p"
  }'
```

Turbo 图生视频不要传 `aspect_ratio`。

### V3 首尾帧

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "operation": "first_last_frame",
    "prompt": "人物自然转身并看向镜头，过渡连续平滑。",
    "image": "https://example.com/first.png",
    "last_image": "https://example.com/last.png",
    "duration": 5,
    "resolution": "pro"
  }'
```

### V3 动作控制

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "operation": "motion_control",
    "prompt": "保持人物身份和服装，复现参考视频中的动作。",
    "image": "https://example.com/person.png",
    "video": "https://example.com/motion.mp4",
    "resolution": "pro",
    "character_orientation": "image"
  }'
```

### Omni 多模态参考

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-omni",
    "operation": "reference_to_video",
    "prompt": "保持人物身份和服装，把参考动作应用到基础视频。",
    "reference_image_urls": [
      "https://example.com/person.png",
      "https://example.com/clothes.png"
    ],
    "video_url": "https://example.com/base.mp4",
    "duration": 8,
    "resolution": "pro",
    "keep_original_sound": "yes"
  }'
```

### Omni 视频编辑

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-omni",
    "operation": "edit_video",
    "prompt": "保持人物动作不变，把背景替换为夜晚城市街道。",
    "video_url": "https://example.com/source.mp4",
    "reference_image_urls": [
      "https://example.com/city-style.png"
    ],
    "resolution": "pro",
    "keep_original_sound": "yes"
  }'
```

`kling-o1` 使用相同的文生、图生、首尾帧、参考和编辑请求结构，其生成时长范围为 `3` 到 `10` 秒。

## 响应示例

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "kling-v3",
  "status": "queued",
  "progress": 0
}
```

## 任务状态与结果

保存 `id` 或 `task_id`，然后按照[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)中的公共规则，每 3 到 10 秒轮询一次，并处理终态、结果字段、错误和带鉴权下载。

## 计费说明

视频通常结合公共模型、`operation`、`resolution` 和实际输出秒数计费。任务提交时可能预扣，最终以任务结算记录和模型广场当前价格为准。

## 常见错误

- 使用历史清晰度、声音、静音或数字人档位模型名，而不是上面的版本级模型。
- 使用 `size` 代替 `resolution`，或给视频请求传入 `sound`。
- Turbo 图生视频传入 `aspect_ratio`。
- 请求时长超出所选模型和 operation 的范围。
- 混用 `image`、`reference_image_urls` 和视频输入，重复提交同一个参考素材。
- 图片或视频 URL 无法由服务端公开访问。
- 一次轮询超时后重新提交付费任务，而不是继续查询原 `task_id`。

公共响应不会返回供应商名称、上游任务 ID、路由、凭证或上游原始请求。

## 相关页面

- [Kling 图片](/zh-CN/models/image/kling)
- [数字人口播](/zh-CN/models/avatar/digital-human)
- [视频生成概览](/zh-CN/models/video/overview)

---

# 视频生成概览

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/overview
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/overview.md
Description: 使用统一任务生命周期创建、查询并获取 UniAll 视频生成结果。

UniAll 视频模型默认共用一套异步任务生命周期。模型 ID、输入字段和能力限制以各模型页面为准；任务轮询、状态处理、错误和结果获取统一以本页为准。

## 模型

- [Happy Horse](/zh-CN/models/video/happy-horse)
- [Seedance 2.0](/zh-CN/models/video/seedance-2-0)
- [Seedance 2.5](/zh-CN/models/video/seedance-2-5)
- [Grok Video 1.5](/zh-CN/models/video/grok/grok-video-1-5)
- [Grok Imagine](/zh-CN/models/video/grok-imagine)
- [Veo 3.1](/zh-CN/models/video/veo-3-1)
- [Gemini Omni Flash Preview](/zh-CN/models/video/gemini-omni-flash-preview)
- [Vidu Q3](/zh-CN/models/video/vidu)
- [Hailuo](/zh-CN/models/video/hailuo)
- [Kling](/zh-CN/models/video/kling)
- [Wan 2.6](/zh-CN/models/video/wan-2-6)
- [Sora 2](/zh-CN/models/video/sora-2)

## 默认接口

`{BASE_URL}` 为 `https://api.uniall.ai`。

| 操作 | 方法 | 接口 |
| --- | --- | --- |
| 创建任务 | `POST` | `/v1/videos` |
| 查询状态与结果 | `GET` | `/v1/videos/{task_id}` |
| 下载已完成的视频 | `GET` | `/v1/videos/{task_id}/content` |

每次请求都要携带 `Authorization: Bearer sk-***`。部分模型页面会注明兼容创建路径或特定协议例外；模型 ID 和请求体仍以对应模型页面为准。

## 视频任务生命周期

### 1. 保存任务 ID

创建成功后会返回公开 `id`。部分响应还会在 `task_id` 中返回同一个值用于兼容。离开创建流程前应保存其中任意一个。

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "model-name",
  "status": "queued",
  "progress": 0,
  "created_at": 1785801600
}
```

### 2. 轮询任务

每 3 到 10 秒查询一次任务：

```bash
curl "{BASE_URL}/v1/videos/task_xxxxxxxxxxxxx" \
  -H "Authorization: Bearer sk-***"
```

仅当 `status` 变为 `completed` 或 `failed` 时停止轮询。任务仍为 `queued` 或 `in_progress` 时，不要重复创建同一任务。

| 状态 | 终态 | 含义 |
| --- | --- | --- |
| `queued` | 否 | 任务已受理，正在等待处理。 |
| `in_progress` | 否 | 正在生成视频或处理结果。 |
| `completed` | 是 | 最终结果已就绪。 |
| `failed` | 是 | 任务未生成结果；检查 `error`。 |

### 3. 读取结果

任务完成后，可从 `video_url`、`result.video_url` 或 `result.outputs[0]` 读取公开结果。这几个字段可能指向同一个视频。

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "model-name",
  "status": "completed",
  "progress": 100,
  "video_url": "https://example.com/generated-video.mp4",
  "result": {
    "video_url": "https://example.com/generated-video.mp4",
    "outputs": [
      "https://example.com/generated-video.mp4"
    ]
  },
  "error": null
}
```

需要最终文件时，使用带鉴权的内容接口：

```bash
curl -L "{BASE_URL}/v1/videos/task_xxxxxxxxxxxxx/content" \
  -H "Authorization: Bearer sk-***" \
  -o output.mp4
```

任务完成前不要调用内容接口。生成媒体应及时下载，不要把结果 URL 当作永久存储地址。

### 4. 处理失败

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "model-name",
  "status": "failed",
  "progress": 100,
  "result": null,
  "error": {
    "code": "task_failed",
    "message": "Video generation failed"
  }
}
```

参数错误应先修正输入再创建新任务。临时服务错误可使用退避策略重试，但原任务仍在运行时不要反复提交同一请求。

## 公共响应字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 用于轮询的公开任务 ID。 |
| `task_id` | string | 存在时为 `id` 的兼容别名。 |
| `object` | string | 任务对象类型，通常为 `video.generation.job`。 |
| `model` | string | 创建任务时使用的公开模型 ID。 |
| `status` | string | `queued`、`in_progress`、`completed` 或 `failed`。 |
| `progress` | integer | 可用时为 `0` 到 `100`；不能代替 `status` 判断终态。 |
| `video_url` | string 或 null | 任务完成后的公开结果 URL。 |
| `result` | object 或 null | 完成后的输出详情，包括 `video_url` 或 `outputs`。 |
| `error` | object 或 null | 失败任务的公开 `code` 和 `message`。 |
| `created_at` | integer | 可用时为 Unix 创建时间戳。 |
| `completed_at` | integer | 可用时为 Unix 完成时间戳。 |

## 模型例外

Gemini Omni Flash Preview 通过 `POST /v1beta/interactions` 创建请求。需要后续查询时，使用返回的 `interaction_id` 调用 `GET /v1/videos/generations/{interaction_id}`；终态、错误处理和结果字段仍遵循上面的公共规则。

Sora 2 原生 OpenAI 格式等特定协议页面可能直接流式返回自身格式，而不是标准视频任务。此类场景以对应页面的响应流程为准。

---

# Seedance 2.0

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/seedance-2-0
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/seedance-2-0.md
Description: 通过 UniAll 视频 API 调用 Seedance 2.0 模型生成视频。

Seedance 2.0 支持文生视频、图生视频、首尾帧、多模态参考、视频编辑和视频延长。新接入请从 [Seedance 2.0 系列调用指南](/zh-CN/models/video/seedance-2-0/series-guide) 开始；需要准备可复用图片、视频或音频时，使用 [Seedance 2.0 素材库](/zh-CN/models/video/seedance-2-0/material-library)。

## 支持模型

| 模型 | 支持分辨率 | 适用场景 |
| --- | --- | --- |
| `seedance2.0` | `480p`、`720p`、`1080p`、`4k` | 综合质量优先，支持完整能力。 |
| `seedance2.0-fast` | `480p`、`720p` | 生成速度优先。 |
| `seedance2.0-mini` | `480p`、`720p` | 轻量、速度优先。 |

## Endpoint

```http
POST /v1/videos
GET  /v1/videos/{task_id}
GET  /v1/videos/{task_id}/content
```

旧客户端仍可继续使用 `/v1/videos/generations` 和 `/v1/video/generations` 创建接口。

## Authentication

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `seedance2.0`、`seedance2.0-fast` 或 `seedance2.0-mini`。 |
| `resolution` | string | 是 | 所选模型支持的分辨率。 |
| `prompt` | string | 条件必填 | 视频提示词；使用 `content[]` 时改为 `type=text` 项。 |
| `duration` | integer/string | 是 | 输出时长，支持 `4` 到 `15` 秒。 |
| `aspect_ratio` | string | 否 | 输出宽高比；兼容别名为 `ratio`。 |
| `content` | object[] | 否 | 带明确角色的文本、图片、视频和音频多模态输入。 |
| `operation` | string | 条件必填 | `reference_to_video`、`edit_video` 或 `extend_video`。 |
| `generate_audio` | boolean | 否 | 是否生成带音频的视频。 |
| `return_last_frame` | boolean | 否 | 是否返回生成视频的尾帧。 |

## 请求示例

```bash
curl -X POST "https://api.uniall.ai/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0",
    "prompt": "A clean commercial product video with slow camera movement, soft reflections, and realistic lighting.",
    "resolution": "720p",
    "duration": 8,
    "aspect_ratio": "16:9",
    "generate_audio": false,
    "seed": 42,
    "watermark": false
  }'
```

## 多参考图示例

```bash
curl -X POST "https://api.uniall.ai/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0-fast",
    "resolution": "720p",
    "duration": 6,
    "aspect_ratio": "9:16",
    "operation": "reference_to_video",
    "content": [
      {
        "type": "text",
        "text": "制作一段快速时尚 Lookbook 视频，并保持产品外观一致。"
      },
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/model.png"},
        "role": "reference_image"
      },
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/outfit.png"},
        "role": "reference_image"
      }
    ],
    "generate_audio": true
  }'
```

## 任务状态与结果

创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。

## 常见错误

- 新接入仍使用旧创建任务接口。
- 参考图超过 `9` 张。
- 参考视频超过 `3` 个，或总时长超过 `15` 秒。
- `duration` 不在 `4` 到 `15` 范围内。
- 新输入格式和兼容层 `operation` 混用导致路由不明确。

## 相关页面

- [Seedance 2.0 系列调用指南](/zh-CN/models/video/seedance-2-0/series-guide)
- [Seedance 2.0 素材库](/zh-CN/models/video/seedance-2-0/material-library)
- [视频生成概览](/zh-CN/models/video/overview)

---

# Seedance 2.0 素材库

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/seedance-2-0/material-library
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/seedance-2-0/material-library.md
Description: 通过 UniAll.ai API 创建、认证、查询、列出、使用和删除 Seedance 2.0 可复用素材。

素材库用于在提交 Seedance 2.0 视频任务前，准备可重复使用的图片、视频和音频。素材按 UniAll.ai 用户隔离管理；客户端只需要使用自己的 UniAll.ai API Key、本地 `mat_*` 素材 ID，以及接口返回的 `asset://` URI。

本文档对应 2026 年 7 月 29 日更新的公开调用契约。

## 概览

最短接入流程如下：

1. 使用公网 HTTP(S) URL 和 `Idempotency-Key` 创建素材。
2. 使用返回的 `mat_*` ID 查询，直到 `status` 变为 `available`。
3. 从 `uri` 字段读取 `asset://` URI。
4. 将 URI 放入 Seedance 请求对应的结构化图片、视频或音频字段。
5. 不再使用时主动删除，或等待素材自动到期。

当前版本只接受公网可访问的 HTTP(S) URL，不支持直接上传文件。

## Base URL 与接口

本文所有示例使用以下 Base URL：

```uri
https://api.uniall.ai
```

| 操作 | 接口 | 结果 |
| --- | --- | --- |
| 创建素材 | `POST /v1/materials` | 启动处理并返回本地 `mat_*` ID。 |
| 查询素材 | `GET /v1/materials/{material_id}` | 返回当前状态；可用后返回素材 URI。 |
| 列出素材 | `GET /v1/materials` | 返回当前用户可见的素材。 |
| 删除素材 | `DELETE /v1/materials/{material_id}` | 取消或删除素材工作流。 |

## 鉴权与幂等

素材接口与视频接口使用同一个 UniAll.ai API Key：

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

创建素材还必须携带幂等键：

```http
Idempotency-Key: material-order-20260729-0001
```

幂等键必须包含 1 到 200 个可见 ASCII 字符，不能包含空格或控制字符。

- 相同用户使用相同幂等键重试同一个规范化请求时，会返回同一个本地素材工作流。
- 相同幂等键对应不同请求时，返回 `material_idempotency_conflict`。
- 网络超时或结果不确定时，必须使用原键重试，不要生成新键。
- 确实要创建一份新素材时，使用新的幂等键。

## 输入 URL 要求

素材源 URL 必须满足：

- 使用 `http://` 或 `https://`；
- 在素材处理期间保持公网直连；
- 不依赖登录、Cookie、浏览器状态、额外请求头或内网；
- 返回与 `type` 一致的图片、视频或音频；
- 在素材进入终态前保持可访问。

## 快速开始

### 1. 创建素材

```bash
curl -X POST "https://api.uniall.ai/v1/materials" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: material-order-20260729-0001" \
  -d '{
    "url": "https://cdn.example.com/product.png",
    "type": "image",
    "name": "商品参考图"
  }'
```

接口固定返回 HTTP `202` 和本地素材记录：

```json
{
  "id": "mat_xxxxxxxxxxxxx",
  "object": "material",
  "name": "商品参考图",
  "type": "image",
  "status": "processing",
  "uri": null,
  "preview_url": null,
  "created_at": "2026-07-29T10:00:00Z",
  "available_at": null,
  "expires_at": null
}
```

### 2. 等待素材可用

```bash
curl "https://api.uniall.ai/v1/materials/mat_xxxxxxxxxxxxx" \
  -H "Authorization: Bearer sk-***"
```

建议每 3 到 5 秒查询一次。只有 `status` 为 `available` 时才能使用 `uri`：

```json
{
  "id": "mat_xxxxxxxxxxxxx",
  "object": "material",
  "name": "商品参考图",
  "type": "image",
  "status": "available",
  "uri": "asset://asset-xxxxxxxxxxxxx",
  "preview_url": "https://example.com/short-lived-preview.jpg",
  "created_at": "2026-07-29T10:00:00Z",
  "available_at": "2026-07-29T10:01:00Z",
  "expires_at": "2026-07-29T12:01:00Z"
}
```

### 3. 在 Seedance 中使用 URI

将接口返回的 `uri` 放入对应的结构化媒体字段：

```bash
curl -X POST "https://api.uniall.ai/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0",
    "resolution": "720p",
    "duration": 6,
    "content": [
      {
        "type": "text",
        "text": "保持产品外观一致，使用缓慢的电影感镜头运动。"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "asset://asset-xxxxxxxxxxxxx"
        },
        "role": "reference_image"
      }
    ]
  }'
```

不要把 `asset://` URI 写入 `prompt` 或其他普通文本字段。UniAll.ai 会在提交生成前校验用户归属、状态和有效期；未知、已过期、已删除或属于其他用户的素材都会被拒绝。普通 HTTP(S) 媒体输入继续按系列指南中的规则使用。

## 创建素材

```http
POST /v1/materials
```

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `url` | string | 是 | 公网 HTTP(S) 图片、视频或音频 URL。 |
| `type` | string | 是 | `image`、`video` 或 `audio`。 |
| `name` | string | 否 | 用户可见的素材名称。 |
| `real_person` | object | 否 | 真人图片或视频使用的授权声明和回跳配置。 |
| `real_person.consent_confirmed` | boolean | 使用 `real_person` 时必填 | 必须为 JSON 布尔值 `true`，表示接入方已经单独取得真人同意。 |
| `real_person.callback_url` | string | 使用 `real_person` 时必填 | 真人认证完成后的浏览器回跳地址；生产环境必须使用 HTTPS。 |

### 真人素材

真人图片和真人视频必须明确声明已取得授权，并由真人本人完成浏览器活体认证。真人音频暂不支持。

```bash
curl -X POST "https://api.uniall.ai/v1/materials" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: real-person-material-20260729-0001" \
  -d '{
    "url": "https://cdn.example.com/person.jpg",
    "type": "image",
    "name": "已授权真人头像",
    "real_person": {
      "consent_confirmed": true,
      "callback_url": "https://client.example.com/material-complete"
    }
  }'
```

HTTP `202` 可能返回 `verification_pending` 和临时 `verification_url`：

```json
{
  "id": "mat_xxxxxxxxxxxxx",
  "object": "material",
  "name": "已授权真人头像",
  "type": "image",
  "status": "verification_pending",
  "uri": null,
  "preview_url": null,
  "verification_url": "https://example.com/temporary-h5-token",
  "created_at": "2026-07-29T10:00:00Z",
  "available_at": null,
  "expires_at": null,
  "verification_expires_at": "2026-07-29T10:30:00Z"
}
```

让真人本人在浏览器中打开 `verification_url` 并完成 H5 活体认证。认证成功后，UniAll.ai 会在原工作流中自动提交实际素材，不需要再次调用 `POST /v1/materials`。

浏览器随后会跳转到 `real_person.callback_url`，并且只附加以下查询参数：

```uri
material_id=mat_xxxxxxxxxxxxx&material_status=processing
```

回跳时的状态可能是 `creating`、`processing`、`available` 或认证失败状态。回跳只表示已收到认证结果，不代表素材一定已经可用；客户端仍需继续查询素材详情。即使浏览器回跳丢失，后台恢复流程也会继续推进工作流。

`verification_url` 只会出现在创建响应或该请求的幂等重放响应中。查询、列表和删除响应都不会返回它。

## 查询素材

```http
GET /v1/materials/{material_id}
```

只有当前 API Key 所属用户可以查询该素材。响应不会暴露原始输入 URL、真人认证标识、内部素材 ID、内部路由信息、凭证、H5 临时令牌或回调校验状态。

素材目前在变为可用后保留两小时。到达 `expires_at` 后，记录会归档为 `deleted`；之后用户详情接口返回 `404 material_not_found`。

## 列出素材

```http
GET /v1/materials
```

| 查询参数 | 必填 | 说明 |
| --- | --- | --- |
| `type` | 否 | `image`、`video` 或 `audio`。 |
| `status` | 否 | `creating`、`verification_pending`、`processing`、`available` 或 `delete_pending`。 |
| `limit` | 否 | 每页 1 到 100 条，默认 `50`。 |
| `after` | 否 | 上一页返回的不透明游标。 |

```bash
curl "https://api.uniall.ai/v1/materials?type=image&status=available&limit=20" \
  -H "Authorization: Bearer sk-***"
```

```json
{
  "object": "material.list",
  "data": [
    {
      "id": "mat_xxxxxxxxxxxxx",
      "object": "material",
      "name": "商品参考图",
      "type": "image",
      "status": "available",
      "uri": "asset://asset-xxxxxxxxxxxxx",
      "preview_url": "https://example.com/short-lived-preview.jpg",
      "created_at": "2026-07-29T10:00:00Z",
      "available_at": "2026-07-29T10:01:00Z",
      "expires_at": "2026-07-29T12:01:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "opaque-cursor-value"
}
```

请求下一页时，把 `next_cursor` 原样作为 `after` 传入。不要解析或自行构造游标。

用户素材列表会排除失败、认证失败、认证过期、已删除、历史过期，以及已经到期但等待后台归档的记录。这些记录可以继续保留在管理员视图中用于审计和排障。

## 删除素材

```http
DELETE /v1/materials/{material_id}
```

```bash
curl -X DELETE "https://api.uniall.ai/v1/materials/mat_xxxxxxxxxxxxx" \
  -H "Authorization: Bearer sk-***"
```

- HTTP `200` 且 `status=deleted`：删除已经完成。
- HTTP `202` 且 `status=delete_pending`：删除请求已接受，仍在异步处理。
- 真人认证尚未完成时，删除会取消本地工作流。
- 删除操作是幂等的；已删除素材不能再用于生成。

两种成功状态都会返回与详情接口相同的完整素材对象。

## 素材状态

| 状态 | 说明 |
| --- | --- |
| `creating` | UniAll.ai 正在初始化素材工作流。 |
| `verification_pending` | 等待真人完成 H5 认证。 |
| `verification_failed` | 真人认证失败，或认证会话创建结果不确定。 |
| `verification_expired` | 真人认证会话已经过期。 |
| `processing` | 实际素材已经提交，正在处理。 |
| `available` | 素材可以用于生成请求。 |
| `failed` | 素材创建或处理失败。 |
| `delete_pending` | 删除已经提交，仍在处理。 |
| `deleted` | 删除完成；该状态可能出现在删除响应中，但查询和列表不再返回。 |

`verification_failed`、`verification_expired` 和 `failed` 都是失败终态。使用原创建幂等键重放只会返回原失败工作流；要创建新素材，请使用新的 `Idempotency-Key`。

## 安全与生命周期

- `verification_url` 包含 H5 临时令牌，应按机密信息处理。不要写入业务日志、埋点、客服消息或公开页面。
- 不要记录完整的真人回跳 URL、查询参数或回调校验状态。
- `preview_url` 是短期预览地址，不能作为永久存储或稳定的公开链接。
- 不要依赖查询或列表接口返回原始输入 URL。
- 只使用同一用户拥有、当前状态为 `available` 的 `asset://` URI。

## 常见错误

错误使用 OpenAI 兼容结构：

```json
{
  "error": {
    "message": "The material is not available.",
    "type": "invalid_request_error",
    "code": "material_not_available"
  }
}
```

| 错误码 | 说明 |
| --- | --- |
| `invalid_idempotency_key` | 缺少有效的 `Idempotency-Key`，或格式不符合要求。 |
| `invalid_material_request` | URL、类型、名称或查询参数不符合要求。 |
| `invalid_material_cursor` | `after` 不是本接口返回的有效游标。 |
| `material_channel_unavailable` | 素材服务暂不可用，或当前模型暂不支持素材输入。 |
| `material_idempotency_conflict` | 相同幂等键对应了不同请求。 |
| `material_not_found` | 素材不存在、不属于当前用户，或已经到期归档。 |
| `material_not_available` | 素材尚未可用、已经过期或已经删除。 |
| `material_not_managed` | `asset://` URI 未登记在当前用户的 UniAll.ai 素材库中。 |
| `visual_verification_consent_required` | 真人素材没有明确确认授权同意。 |
| `invalid_visual_verification_request` | 真人素材类型或回跳地址不符合要求。 |
| `visual_verification_create_outcome_uncertain` | 首次创建认证会话的结果不确定；系统不会自动创建第二个会话。 |
| `material_create_outcome_uncertain` | 素材创建结果不确定，UniAll.ai 正在后台核对。 |

错误消息只包含可公开信息，不会暴露上游原始错误、内部路由或凭证。

## 相关页面

- [Seedance 2.0 系列调用指南](/zh-CN/models/video/seedance-2-0/series-guide)
- [Seedance 2.0 视频生成](/zh-CN/models/video/seedance-2-0)

---

# Seedance 2.0 系列调用指南

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/seedance-2-0/series-guide
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/seedance-2-0/series-guide.md
Description: 通过 UniAll 调用 Seedance 2.0、Seedance 2.0 Fast 和 Seedance 2.0 Mini，涵盖多模态输入、视频编辑、延长和任务查询。

更新时间：2026-07-29

本文介绍如何通过 UniAll 调用 Seedance 2.0 系列。新接入推荐使用三个稳定公共模型名，通过请求参数选择分辨率和生成能力。

## 1. 模型选择

| 公共模型 | 支持分辨率 | 适用场景 |
| --- | --- | --- |
| `seedance2.0` | `480p`、`720p`、`1080p`、`4k` | 综合质量优先，支持完整能力 |
| `seedance2.0-fast` | `480p`、`720p` | 生成速度优先 |
| `seedance2.0-mini` | `480p`、`720p` | 轻量任务和速度优先 |

三个模型均支持：

- 文生视频；
- 单图生视频；
- 首尾帧生视频；
- 图片、视频和音频多模态参考；
- 视频编辑和视频延长；
- 有声视频、水印和随机种子；
- 纯文本联网搜索；
- 返回生成视频的尾帧；
- 使用已有的 `asset://` 素材 ID。

## 2. 接口与鉴权

推荐使用 OpenAI 兼容视频任务接口：

```http
POST /v1/videos
GET  /v1/videos/{task_id}
GET  /v1/videos/{task_id}/content
```

请求头：

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

以下示例中的 `{BASE_URL}` 使用：

```uri
https://api.uniall.ai
```

同时保留以下兼容接口：

```http
POST /v1/videos/generations
GET  /v1/videos/generations/{task_id}

POST /v1/video/generations
GET  /v1/video/generations/{task_id}
```

新接入建议统一使用 `/v1/videos`。

## 3. 公共参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 三个公共模型之一，或兼容期内的固定分辨率模型名 |
| `prompt` | string | 条件必填 | 视频提示词；使用 `content[]` 时改为至少一个 `type=text` 项 |
| `resolution` | string | 新公共模型必填 | 输出分辨率，取值见模型表 |
| `size` | string | 否 | `resolution` 的兼容别名 |
| `duration` | integer/string | 是 | 输出时长，支持 `4` 到 `15` 秒；兼容值 `auto`，推荐显式传整数 |
| `aspect_ratio` | string | 否 | `auto`、`21:9`、`16:9`、`4:3`、`3:2`、`2:3`、`1:1`、`3:4`、`9:16` |
| `ratio` | string | 否 | `aspect_ratio` 的兼容别名；`adaptive` 等价于 `auto` |
| `content` | object[] | 否 | 推荐的多模态输入格式，详见下一节 |
| `operation` | string | 特定能力必填 | `reference_to_video`、`edit_video` 或 `extend_video` |
| `generate_audio` | boolean | 否 | 是否生成有声视频 |
| `watermark` | boolean | 否 | 是否添加水印 |
| `seed` | integer | 否 | 随机种子 |
| `return_last_frame` | boolean | 否 | 是否在完成结果中返回尾帧 URL |
| `tools` | object[] | 否 | 当前仅支持 `[{"type":"web_search"}]` |

参数兼容规则：

- `resolution` 和 `size` 同时传入时必须相同。
- `aspect_ratio` 和 `ratio` 同时传入时必须表达相同比例。
- `ratio: "adaptive"` 与 `aspect_ratio: "auto"` 视为相同。
- `operation`、`generate_audio`、`watermark`、`seed`、`return_last_frame` 和 `tools` 也兼容放入 `extra_body`；同一参数不要在顶层和 `extra_body` 重复传入。
- `draft`、`frames`、`camera_fixed` 和 `service_tier: "flex"` 不属于当前公共契约。

## 4. `content[]` 多模态格式

复杂输入推荐统一使用 `content[]`：

```json
{
  "content": [
    {
      "type": "text",
      "text": "提示词"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/image.png"
      },
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/video.mp4"
      },
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": {
        "url": "https://example.com/audio.mp3"
      },
      "role": "reference_audio"
    }
  ]
}
```

支持的类型和角色：

| `type` | `role` | 含义 |
| --- | --- | --- |
| `text` | 无 | 提示词，可传多个文本项 |
| `image_url` | `image` | 单图生视频输入图 |
| `image_url` | `reference_image` | 参考图片 |
| `image_url` | `first_frame` | 首帧图片 |
| `image_url` | `last_frame` | 尾帧图片 |
| `video_url` | `source_video` | 编辑或延长的源视频 |
| `video_url` | `reference_video` | 参考视频 |
| `audio_url` | `reference_audio` | 参考音频 |

输入约束：

- `content[]` 至少包含一个非空文本项。
- 图片最多 9 张，视频最多 3 段，音频最多 3 段。
- `first_frame` 和 `last_frame` 必须成对出现，且各只能有 1 张。
- 首尾帧模式不能再混入视频、音频或其他图片。
- `image` 和 `reference_image` 不要在同一请求中混用。
- `source_video` 最多 1 段。
- 参考音频必须同时存在至少一张图片或一段视频；不接受纯音频或“文本 + 音频”。
- 使用多份参考素材时，可在提示词中按顺序使用 `@Image1`、`@Video1`、`@Audio1` 指定素材。

简单请求仍兼容 `image`、`images`、`last_image`、`video`、`videos` 和 `audios` 等字段；新功能和多模态组合建议使用 `content[]`，避免输入角色不明确。

## 5. 请求示例

### 5.1 文生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0",
    "prompt": "雨后的未来城市街道，霓虹倒影，电影感镜头缓慢向前推进。",
    "resolution": "1080p",
    "duration": 5,
    "ratio": "16:9",
    "generate_audio": true
  }'
```

### 5.2 单图生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0-fast",
    "resolution": "720p",
    "duration": 6,
    "content": [
      {
        "type": "text",
        "text": "人物自然转身看向镜头，衣服随风轻微摆动，保持人物身份一致。"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/person.png"
        },
        "role": "image"
      }
    ]
  }'
```

### 5.3 首尾帧生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0",
    "resolution": "720p",
    "duration": 6,
    "content": [
      {
        "type": "text",
        "text": "镜头从白天自然过渡到夜晚，运动连贯，建筑结构保持稳定。"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/first.png"
        },
        "role": "first_frame"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/last.png"
        },
        "role": "last_frame"
      }
    ]
  }'
```

### 5.4 多模态参考生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0-mini",
    "resolution": "720p",
    "duration": 8,
    "operation": "reference_to_video",
    "content": [
      {
        "type": "text",
        "text": "让 @Image1 中的产品按照 @Video1 的镜头运动展示，并参考 @Audio1 的节奏。"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/product.png"
        },
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": {
          "url": "https://example.com/motion.mp4"
        },
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": {
          "url": "https://example.com/music.mp3"
        },
        "role": "reference_audio"
      }
    ]
  }'
```

### 5.5 视频编辑

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0",
    "resolution": "720p",
    "duration": 6,
    "operation": "edit_video",
    "content": [
      {
        "type": "text",
        "text": "把背景替换为雨夜霓虹街道，保留人物动作和主体身份。"
      },
      {
        "type": "video_url",
        "video_url": {
          "url": "https://example.com/source.mp4"
        },
        "role": "source_video"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/style.png"
        },
        "role": "reference_image"
      }
    ]
  }'
```

### 5.6 视频延长

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0-fast",
    "resolution": "720p",
    "duration": 5,
    "operation": "extend_video",
    "content": [
      {
        "type": "text",
        "text": "延续原镜头运动，人物继续向前行走，光线和场景保持一致。"
      },
      {
        "type": "video_url",
        "video_url": {
          "url": "https://example.com/source.mp4"
        },
        "role": "source_video"
      }
    ]
  }'
```

### 5.7 纯文本联网搜索

联网搜索只能用于纯文本请求，不能同时传图片、视频或音频。

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0-mini",
    "prompt": "根据今天公开的科技新闻制作一段简洁的资讯视频，不要显示品牌商标。",
    "resolution": "720p",
    "duration": 5,
    "tools": [
      {
        "type": "web_search"
      }
    ]
  }'
```

`web_search` 表示允许模型检索公开信息，不保证每次生成都会实际产生搜索调用。

### 5.8 返回尾帧

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0",
    "prompt": "一艘纸船缓慢停在石桥旁，最后画面保持稳定。",
    "resolution": "720p",
    "duration": 5,
    "return_last_frame": true
  }'
```

任务完成后，尾帧通过 `result.last_frame_url` 返回，不会混入视频 `outputs`。

### 5.9 使用素材库 URI

通过 [Seedance 2.0 素材库](/zh-CN/models/video/seedance-2-0/material-library) 创建并查询可复用输入。素材达到 `status=available` 后，把普通媒体 URL 替换为接口返回的 `uri`：

```json
{
  "type": "video_url",
  "video_url": {
    "url": "asset://asset-xxxxxxxxxxxxx"
  },
  "role": "source_video"
}
```

URI 只能放入对应的结构化图片、视频或音频字段，不要写入提示词。UniAll.ai 会在创建视频任务前校验当前用户的素材归属、状态和有效期。

## 6. 任务状态与结果

创建成功后返回异步任务：

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "seedance2.0",
  "status": "queued",
  "progress": 0,
  "created_at": 1784640000
}
```

创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。

Seedance 请求生成尾帧时，完成响应还可能包含 `result.last_frame_url`。

## 7. 固定分辨率模型兼容

已有客户端可以继续使用固定分辨率模型名：

| 模型系列 | 兼容模型名 |
| --- | --- |
| Standard | `seedance2.0-480p`、`seedance2.0-720p`、`seedance2.0-1080p`、`seedance2.0-4k` |
| Fast | `seedance2.0-fast-480p`、`seedance2.0-fast-720p` |
| Mini | `seedance2.0-mini-480p`、`seedance2.0-mini-720p` |

更早的以下名称也继续兼容：

- `seedance2.0-video-480p`
- `seedance2.0-video-720p`
- `seedance2.0-fast-video-480p`
- `seedance2.0-fast-video-720p`

固定分辨率模型从模型名确定分辨率，不要求额外传 `resolution`。它们与对应的新公共模型使用相同参数和能力；如仍传 `resolution` 或 `size`，值必须与模型名中的分辨率一致。

新项目建议迁移到三个公共模型名，便于只修改请求参数即可切换输出分辨率。

## 8. 常见错误

| 场景 | 结果 | 修正方式 |
| --- | --- | --- |
| 新公共模型缺少 `resolution`/`size` | HTTP `400` | 显式传入支持的分辨率 |
| `resolution` 与 `size` 不同 | HTTP `400` | 只传一个，或保证值相同 |
| `aspect_ratio` 与 `ratio` 冲突 | HTTP `400` | 只传一个，或保证语义相同 |
| 缺少 `duration` | HTTP `400` | 传 `4` 到 `15` 的整数 |
| `content[]` 没有文本项 | HTTP `400` | 增加非空 `type=text` 项 |
| 首帧和尾帧没有成对传入 | HTTP `400` | 同时传 `first_frame` 和 `last_frame` |
| 纯音频或“文本 + 音频” | HTTP `400` | 至少增加一张图片或一段视频 |
| 联网搜索请求包含媒体 | HTTP `400` | 搜索请求只保留文本输入 |
| 图片、视频或音频数量超限 | HTTP `400` | 分别控制在 9、3、3 个以内 |
| 使用 `draft`、`frames`、`camera_fixed` 或 `service_tier=flex` | HTTP `400` | 删除这些参数 |

遇到安全审核、素材格式或参数错误时，应修改输入后创建新任务，不要对同一无效请求进行高频重复提交。

## 9. 相关页面

- [Seedance 2.0](/zh-CN/models/video/seedance-2-0)
- [Seedance 2.0 素材库](/zh-CN/models/video/seedance-2-0/material-library)
- [视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)

---

# Seedance 2.5

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/seedance-2-5
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/seedance-2-5.md
Description: 通过 UniAll 创建 Seedance 2.5 文生、图生、多模态参考、视频编辑和延长任务。

本页中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

更新时间：2026-08-12

## 概览

UniAll 对外提供一个稳定的 Seedance 2.5 公共模型：`seedance2.5`。该模型支持文生视频、单首帧和首尾帧生视频、多模态参考生成、视频编辑、视频延长、可复用 `asset://` 素材，以及可选的联网搜索。

| 能力 | 必需输入 | 核心规则 |
| --- | --- | --- |
| 文生视频 | 提示词 | 必须传入 `resolution` 和 `duration`。 |
| 单首帧生视频 | 1 张首帧图 | 省略 `aspect_ratio` 或设为 `auto`。 |
| 首尾帧生视频 | 1 张首帧图和 1 张尾帧图 | 省略 `aspect_ratio` 或设为 `auto`。 |
| 多模态参考生成 | 图片、视频或音频 | 文本可省略，也允许仅音频参考。 |
| 视频编辑 | 提示词和 1 个视频 | 必须传 `operation: "edit_video"` 和 `duration: "auto"`。 |
| 视频延长 | 提示词和 1 个视频 | 必须显式传 `operation: "extend_video"`。 |

## 接口与鉴权

| 操作 | 方法 | 路径 |
| --- | --- | --- |
| 创建任务 | `POST` | `/v1/videos` |
| 查询任务 | `GET` | `/v1/videos/{task_id}` |
| 下载完成视频 | `GET` | `/v1/videos/{task_id}/content` |

已有客户端可继续使用以下兼容创建和查询路径：

```http
POST /v1/videos/generations
POST /v1/video/generations
GET  /v1/videos/generations/{task_id}
GET  /v1/video/generations/{task_id}
```

新接入统一使用 `/v1/videos` 和 `/v1/videos/{task_id}`。

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 固定为 `seedance2.5`。 |
| `resolution` | string | 是 | `480p` 或 `720p`。 |
| `size` | string | 否 | `resolution` 的兼容别名；两者同时存在时必须一致。 |
| `duration` | integer/string | 是 | `4` 到 `30` 的整数，或 `auto`；不同操作还有额外限制。 |
| `prompt` | string | 条件必填 | 文本指令。文生、编辑和延长必填；仅媒体参考请求可省略。 |
| `aspect_ratio` | string | 否 | `auto`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4` 或 `9:16`。 |
| `ratio` | string | 否 | `aspect_ratio` 的兼容别名；`adaptive` 会归一为 `auto`。 |
| `output_format` | string | 否 | `mp4` 或 `mov`，默认 `mp4`；兼容客户端也可传 `extra_body.output_format`。 |
| `content` | object[] | 否 | 带明确角色的图片、视频和音频多模态输入。 |
| `operation` | string | 条件必填 | `edit_video` 和 `extend_video` 必须显式传入；多模态参考需要传操作时使用 `reference_to_video`。 |
| `generate_audio` | boolean | 否 | 是否生成音频。 |
| `seed` | integer | 否 | 在支持的场景中控制随机变化。 |
| `watermark` | boolean | 否 | 是否添加水印。 |
| `return_last_frame` | boolean | 否 | 是否在可用时返回生成视频的尾帧。 |
| `tools` | object[] | 否 | 只接受 `[{"type":"web_search"}]`。 |

以下字段不属于 Seedance 2.5 公共契约，传入会被拒绝：`draft`、`frames`、`camera_fixed` 和 `service_tier: "flex"`。

## 最小文生请求

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.5",
    "prompt": "A cinematic city street after rain",
    "resolution": "720p",
    "duration": 8,
    "aspect_ratio": "16:9",
    "output_format": "mp4"
  }'
```

## 媒体输入

新接入建议使用 `content[]` 表达多模态输入。每一项包含一个媒体类型和明确角色。

| 项目类型 | URL 字段 | 支持角色 |
| --- | --- | --- |
| `image_url` | `image_url.url` | `first_frame`、`last_frame`、`reference_image` |
| `video_url` | `video_url.url` | `reference_video` |
| `audio_url` | `audio_url.url` | `reference_audio` |

媒体地址可以是公开 HTTP(S) URL，也可以是有效的 `asset://` 素材地址。HTTP(S) 素材必须能由 UniAll 服务直接访问，不能依赖 Cookie 或自定义请求头。创建可复用 `asset://` 输入的方法见 [Seedance 素材库](/zh-CN/models/video/seedance-2-0/material-library)。

兼容字段 `image`、`images`、`video`、`videos`、`audios` 和 `last_image` 仍可使用。不要同时通过 `content[]` 和兼容字段传入冲突内容。

### 媒体数量限制

- 图片最多 `30` 张。
- 视频最多 `10` 个。
- 音频最多 `10` 个。
- 所有媒体合计最多 `50` 个。
- 多模态请求可以不包含文本。
- 允许仅音频参考请求。

## 操作规则

| 模式 | `operation` | `duration` | `aspect_ratio` |
| --- | --- | --- | --- |
| 文生视频 | 省略 | `auto` 或整数 `4..30` | 任意支持值 |
| 单首帧生视频 | 省略 | `auto` 或整数 `4..30` | 省略或 `auto` |
| 首尾帧生视频 | 省略 | `auto` 或整数 `4..30` | 省略或 `auto` |
| 多模态参考生成 | 需要传时使用 `reference_to_video` | `auto` 或整数 `4..30` | 由媒体模式决定；帧输入只能使用 `auto` |
| 视频编辑 | 必须为 `edit_video` | 只能为 `auto` | 省略或 `auto` |
| 视频延长 | 必须为 `extend_video` | `auto` 或整数 `4..30` | 省略或 `auto` |

不要通过提示词关键词推断编辑或延长。两种请求都必须显式传入 `operation`。

## 请求示例

### 首尾帧生视频

```json
{
  "model": "seedance2.5",
  "prompt": "Move naturally from the first composition to the last while preserving the subject.",
  "resolution": "720p",
  "duration": 10,
  "aspect_ratio": "auto",
  "content": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/first.png"
      },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/last.png"
      },
      "role": "last_frame"
    }
  ]
}
```

单首帧模式只传 `first_frame` 项。两种帧模式都不能使用固定画幅，因为画面构图由源图片决定。

### 多模态参考生成

```json
{
  "model": "seedance2.5",
  "operation": "reference_to_video",
  "resolution": "720p",
  "duration": 12,
  "content": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/product.png"
      },
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/motion.mp4"
      },
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": {
        "url": "https://example.com/music.mp3"
      },
      "role": "reference_audio"
    }
  ]
}
```

### 视频编辑

```json
{
  "model": "seedance2.5",
  "prompt": "Replace the sky and preserve the subject",
  "video": "https://example.com/source.mp4",
  "operation": "edit_video",
  "resolution": "720p",
  "duration": "auto",
  "aspect_ratio": "auto"
}
```

### 视频延长

```json
{
  "model": "seedance2.5",
  "prompt": "Continue the camera movement into the illuminated square.",
  "video": "asset://mat_xxxxxxxxxxxxx",
  "operation": "extend_video",
  "resolution": "720p",
  "duration": 8,
  "aspect_ratio": "auto",
  "output_format": "mov"
}
```

### 联网搜索

```json
{
  "model": "seedance2.5",
  "prompt": "Create a concise visual recap of the latest public spaceflight milestone.",
  "resolution": "720p",
  "duration": 8,
  "tools": [
    {
      "type": "web_search"
    }
  ]
}
```

联网搜索可以与媒体输入组合。其他 `tools` 结构不受支持。

## 创建响应与任务生命周期

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "seedance2.5",
  "status": "queued",
  "progress": 0,
  "created_at": 1786492800
}
```

保存公开 `id` 或 `task_id`。建议每 2 到 5 秒调用一次 `GET /v1/videos/{task_id}`，当 `status` 变为 `completed` 或 `failed` 后停止。完成任务会返回公开结果 URL，也可以通过需要鉴权的 `/v1/videos/{task_id}/content` 获取文件。

公共状态字段、完成和失败响应示例、下载处理见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。客户端只应使用 UniAll 文档公开的任务 ID、状态、结果、用量和错误字段。

## 计费说明

Seedance 2.5 按任务完成后的有效完成 Token 用量结算。预扣只是估算，最终金额以完成任务返回的有效 `usage` 和结算记录为准。

| 输入类型 | 每百万完成 Token 参考基础价 |
| --- | --- |
| 输入不包含视频 | 约 `$10.294117647`（`70 CNY / 6.8`） |
| 输入包含视频 | 约 `$6.176470588`（`42 CNY / 6.8`） |

- `480p` 与 `720p` 使用相同的 Token 单价。
- 上述金额是完成 Token 参考价，不是每秒固定价格。
- 账号与分组价格会影响最终用户价格，以 UniAll 当前价格页和任务结算记录为准。

## 常见错误

| 错误 | 原因 | 处理方式 |
| --- | --- | --- |
| 缺少参数 | 未传 `resolution` 或 `duration` | 同时传入两个必填字段。 |
| 分辨率无效 | 传入 `1080p`、`4k` 或其他不支持值 | 使用 `480p` 或 `720p`。 |
| 兼容别名冲突 | `resolution` 和 `size` 的值不同 | 删除 `size` 或确保两者完全一致。 |
| 编辑时长无效 | `edit_video` 使用整数时长 | 把 `duration` 设为 `auto`。 |
| 画幅无效 | 首帧、首尾帧、编辑或延长请求使用固定比例 | 省略 `aspect_ratio` 或设为 `auto`。 |
| 媒体数量超限 | 单类型或媒体总数超过限制 | 按文档限制减少媒体数量。 |
| 素材不可访问 | URL 私有、过期或无法从公网访问 | 使用稳定公开 URL 或可用的 `asset://` 素材。 |
| 联网工具无效 | `tools` 不是唯一支持的联网搜索结构 | 传 `[{"type":"web_search"}]` 或省略 `tools`。 |
| 字段不支持 | 传入 `draft`、`frames`、`camera_fixed` 或 `service_tier: "flex"` | 删除不支持字段。 |

## 相关页面

- [视频生成概览](/zh-CN/models/video/overview)
- [Seedance 2.0](/zh-CN/models/video/seedance-2-0)
- [Seedance 素材库](/zh-CN/models/video/seedance-2-0/material-library)
- [模型列表](/zh-CN/models)

---

# Sora 2

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/sora-2
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/sora-2.md
Description: 通过 UniAll 视频 API 调用 Sora 2 模型生成视频。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

Sora 2 支持基于提示词的视频生成，并可选择参考图输入。来源范围同时包含 UniAll 视频生成接口和 OpenAI 原生兼容格式页面。

## 支持模型

| 模型 | 说明 |
| --- | --- |
| `sora2-landscape-4s` | 横版输出，4 秒。 |
| `sora2-landscape-8s` | 横版输出，8 秒。 |
| `sora2-landscape-12s` | 横版输出，12 秒。 |
| `sora2-portrait-4s` | 竖版输出，4 秒。 |
| `sora2-portrait-8s` | 竖版输出，8 秒。 |
| `sora2-portrait-12s` | 竖版输出，12 秒。 |
| `sora2-pro-720p` | Pro 公共模型，720p。 |
| `sora2-pro-1080p` | Pro 公共模型，1080p。 |
| `sora2-pro-true-1080p` | 账号启用时可用的 Pro true-1080p 模型。 |

## Endpoint

```http
POST /v1/video/generations
GET  /v1/videos/{task_id}
```

来源还包含原生 OpenAI 格式页面，供需要 OpenAI 兼容请求格式的客户端使用。

## Authentication

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | Sora 2 模型 ID。 |
| `prompt` | string | 是 | 视频提示词。 |
| `image_url` | string | 否 | 公开可访问的参考图 URL。 |
| `aspect_ratio` | string | 否 | `16:9` 或 `9:16`。 |
| `duration` | integer/string | 否 | 来源描述列出 `4`、`8`、`12`、`16`、`20`；模型名本身可能已编码时长。 |

## 请求示例

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora2-portrait-12s",
    "prompt": "A cat running through grass",
    "image_url": "https://example.com/image.jpg"
  }'
```

## 提交响应

```json
{
  "id": "gen_xxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "sora2",
  "status": "queued",
  "progress": 0,
  "created_at": 1770405483,
  "seconds": "12"
}
```

## 任务状态与结果

创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。

## 计费说明

Sora 2 计费与模型、时长、横竖版、分辨率以及是否使用 Pro 模型有关。当前模型价格和任务结算记录是最终依据。

## 常见错误

- 传入不支持的 Sora 2 模型 ID。
- `image_url` 私有或已过期。
- `aspect_ratio` 与 landscape 或 portrait 模型名冲突。
- 任务仍在队列中就当作完成处理。
- 在同一请求里混用 UniAll 任务格式和原生 OpenAI 格式。

## 相关页面

- [视频生成概览](/zh-CN/models/video/overview)
- [Wan 2.6 视频生成](/zh-CN/models/video/wan-2-6)
- [模型列表](/zh-CN/models)

---

# 创建视频生成任务

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/sora-2/create-task
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/sora-2/create-task.md
Description: Sora 2 创建视频生成任务接口。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

## 说明

新增sora2 Pro 公共模型`sora2-pro-720p`,`sora2-pro-1080p`,`sora2-pro-true-1080p`

## Endpoint


```http
POST /v1/video/generations
```
## Header 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No |  | Bearer &#123;your_token&#125; |
## 请求体参数

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `model` | string | Yes | 模型名称 | 可选：sora2-landscape-4s，sora2-landscape-8s，sora2-landscape-12s，sora2-portrait-4s，sora2-portrait-8s，sora2-portrait-12s, sora2-pro-720p, sora2-pro-1080p |
| `prompt` | string | Yes | 提示词 |  |
| `image_url` | string | Yes | 参考图URL | 必须是公开可访问的URL图片链接 |
| `aspect_ratio` | string | No | 画幅比例 | “16:9”, "9:16" |
| `duration` | string | No | 输出描述 | 4, 8, 12, 16, 20 |

## 请求示例

### 示例 1

```json
{
    "model": "sora2-portrait-12s",
    "prompt": "一只猫在草地上奔跑",
    "image_url": "https://example.com/image.jpg" // 可选
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora2-portrait-12s",
    "prompt": "一只猫在草地上奔跑",
    "image_url": "https://example.com/image.jpg" // 可选
}'
```
## 响应字段

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `id` | string | Yes | 任务ID |  |
| `object` | string | Yes | 任务类型 |  |
| `model` | string | Yes | 模型名称 |  |
| `status` | string | Yes | 状态 |  |
| `progress` | string | Yes | 进度 |  |
| `created_at` | string | Yes | 创建时间 |  |
| `seconds` | string | Yes | 秒数 |  |

## 响应示例

### 示例 1

```json
{
  "id": "gen_xxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "sora2",
  "status": "queued",
  "progress": 0,
  "created_at": 1770405483,
  "seconds": "12"
}
```

## 任务状态与结果

创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。

---

# 原生 OpenAI 格式

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/sora-2/openai-format
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/sora-2/openai-format.md
Description: Sora 2 原生 OpenAI 格式接口。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

## Endpoint


```http
POST /v1/chat/completions
```
## Header 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No |  | Bearer &#123;your_token&#125; |
## 请求体参数

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `model` | string | Yes | 模型名称 | 可选：sora2-landscape-4s，sora2-landscape-8s，sora2-landscape-12s，sora2-portrait-4s，sora2-portrait-8s，sora2-portrait-12s |

## 请求示例

### 示例 1

```json
// 文生视频
{
    "model": "sora2-landscape-4s",
    "messages": [
        {
            "role": "user",
            "content": "一只猫在草地奔跑"
        }
    ],
    "stream": true
}
// 图生视频
{
    "model": "sora2-landscape-4s",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "让图中的人物动起来"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/portrait.jpg"
                    }
                }
            ]
        }
    ],
    "stream": true
}
```

```bash
curl -X POST "{BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '// 文生视频
{
    "model": "sora2-landscape-4s",
    "messages": [
        {
            "role": "user",
            "content": "一只猫在草地奔跑"
        }
    ],
    "stream": true
}
// 图生视频
{
    "model": "sora2-landscape-4s",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "让图中的人物动起来"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/portrait.jpg"
                    }
                }
            ]
        }
    ],
    "stream": true
}'
```
## 响应字段

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |


## 响应示例

### 示例 1

```json
{
  "id": "xxxxxxxxxxxxxxxxxxxxx",
  "object": "chat.completion.chunk",
  "created": 1770408254,
  "model": "sora2",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "\n\n✅ **视频生成完成！**\n\n**视频链接**: https://xxxx.xxxx.cn/xxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.mp4\n**任务用时**: 127秒\n"
      },
      "finish_reason": null
    }
  ]
}
```
### 示例 2

```json
{
  "id": "chatcmpl-b5e9c8b352cc4dcc81815884ab943",
  "object": "chat.completion.chunk",
  "created": 1770408254,
  "model": "sora2",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "\n🖼️ 正在处理输入内容... (50%)"
      },
      "finish_reason": null
    }
  ]
}
```

---

# Veo 3.1

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/veo-3-1
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/veo-3-1.md
Description: 通过 UniAll 视频 API 调用 Veo 3.1 模型生成视频。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

Veo 3.1 支持文生视频、图生视频、首尾帧、多图参考和视频续写。公共模型名同时表达分辨率和速度档位。

## 支持模型

| 模型 | 档位 |
| --- | --- |
| `veo3.1-video-720p` | 标准 720p。 |
| `veo3.1-video-1080p` | 标准 1080p。 |
| `veo3.1-video-4k` | 标准 4K。 |
| `veo3.1-fast-video-720p` | 快速 720p。 |
| `veo3.1-fast-video-1080p` | 快速 1080p。 |
| `veo3.1-fast-video-4k` | 快速 4K。 |

## Endpoint

```http
POST /v1/video/generations
GET  /v1/videos/{task_id}
```

## Authentication

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | Veo 3.1 公共模型 ID。 |
| `prompt` | string | 强烈建议 | 主提示词。Schema 不强制，但生产请求应传。 |
| `image` | string | 条件必填 | 图生视频的单张源图 URL。 |
| `images` | string[] | 条件必填 | 多图参考生视频，`2` 到 `3` 张图。 |
| `last_image` | string | 条件必填 | 目标尾帧图 URL，与 `image` 配合使用。 |
| `video` | string | 条件必填 | 视频续写的源视频 URL。 |
| `size` | string | 建议 | 分辨率提示，应与所选模型档位一致。 |
| `aspect_ratio` | string | 否 | 文生视频允许 `16:9` 或 `9:16`；图生和续写不一定生效。 |
| `duration` | integer | 条件必填 | 输出秒数，允许值为 `4`、`6`、`8`；视频续写不使用。 |
| `extra_body.generate_audio` | boolean | 否 | 是否生成声音，上游通常默认 `true`。 |
| `extra_body.negative_prompt` | string | 否 | 不希望出现的内容。 |
| `extra_body.seed` | integer | 否 | 随机种子。 |

## 文生视频示例

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-video-1080p",
    "prompt": "A golden-hour street interview shot, slight handheld movement, natural city ambience, realistic human speech.",
    "size": "1080p",
    "aspect_ratio": "16:9",
    "duration": 8,
    "extra_body": {
      "generate_audio": true,
      "negative_prompt": "watermark, blur",
      "seed": 7
    }
  }'
```

## 图生视频示例

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-video-720p",
    "prompt": "A product slowly rotates on a clean studio desk with soft reflected light.",
    "image": "https://example.com/keyframe.png",
    "size": "720p",
    "aspect_ratio": "16:9",
    "duration": 6,
    "extra_body": {
      "generate_audio": false,
      "negative_prompt": "artifacts, camera shake"
    }
  }'
```

## 首尾帧示例

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-fast-video-1080p",
    "prompt": "Transition naturally from the first frame to the last frame, preserving subject identity and camera continuity.",
    "image": "https://example.com/start-frame.png",
    "last_image": "https://example.com/end-frame.png",
    "size": "1080p",
    "aspect_ratio": "16:9",
    "duration": 6
  }'
```

## 任务状态与结果

创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。

## 计费说明

Veo 计费与模型档位、速度档、分辨率、输出时长和是否生成音频有关。最终以任务结算记录和当前产品价格为准。

## 常见错误

- `duration` 不在 `4`、`6`、`8` 允许值中。
- `size` 与所选模型档位不一致。
- 期望图生视频或续写一定遵循 `aspect_ratio`。
- 参考图超过 `3` 张。
- 传入 `video` 但没有通过提示词或扩展字段说明续写意图。

## 相关页面

- [视频生成概览](/zh-CN/models/video/overview)
- [Kling 视频生成](/zh-CN/models/video/kling)
- [Vidu 视频生成](/zh-CN/models/video/vidu)

---

# 创建视频生成任务

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/veo-3-1/create-task
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/veo-3-1/create-task.md
Description: Veo 3.1 创建视频生成任务接口。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

## 说明

| 公共模型名 | 当前支持的视频生成能力 |
|---|---|
| `veo3.1-video-720p`  | 文生视频、单图生视频、首尾帧、多图参考生视频、视频续写 |
| `veo3.1-video-1080p` | 文生视频、单图生视频、首尾帧、多图参考生视频、视频续写 |
| `veo3.1-video-4k`  | 文生视频、单图生视频、首尾帧、多图参考生视频、视频续写 |
| `veo3.1-fast-video-720p`  | 文生视频、单图生视频、首尾帧、视频续写 |
| `veo3.1-fast-video-1080p` | 文生视频、单图生视频、首尾帧、视频续写 |
| `veo3.1-fast-video-4k` | 文生视频、单图生视频、首尾帧、视频续写 |

## Endpoint


```http
POST /v1/video/generations
```
## Query 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No |  | Bearer &#123;your_token&#125; |
## 请求体参数

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `model` | string | Yes | 公共模型名 |  |
| `prompt` | string | Yes | 主提示词 | 结构上不是绝对必填，但实际强烈建议传 |
| `image` | string | Yes | 单张源图 URL | 图生视频 |
| `images` | string | Yes | 多张参考图 URL 列表 | 2 到 3 张图会触发多图参考生视频 |
| `last_image` | string | Yes | 目标尾帧图 URL | 首尾帧，与image配合使用 |
| `video` | string | Yes | 源视频 UR | 触发视频续写 |
| `size` | string | Yes | 分辨率提示 | 必须与所选公共模型档位保持一致 |
| `aspect_ratio` | string | Yes | 输出比例 | 文生视频允许值：`16:9`、`9:16`；图生视频，视频续写不使用，可传输出不保证效果 |
| `duration` | string | Yes | 输出时长，单位秒 | 允许值：`4`、`6`、`8`；视频续写不使用 |
| `extra_body` | object | Yes | 扩展字段 |  |

## 请求示例

### 文生视频

```json
{
  "model": "veo3.1-video-1080p",
  "prompt": "黄金时刻的街头采访镜头，镜头轻微手持晃动，人物真实发声，环境中有自然城市背景音。",
  "size": "1080p",
  "aspect_ratio": "16:9",
  "duration": 8,
  "extra_body": {
    "generate_audio": true,
    "negative_prompt": "水印, 模糊",
    "seed": 7
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-video-1080p",
    "prompt": "黄金时刻的街头采访镜头，镜头轻微手持晃动，人物真实发声，环境中有自然城市背景音。",
    "size": "1080p",
    "aspect_ratio": "16:9",
    "duration": 8,
    "extra_body": {
        "generate_audio": true,
        "negative_prompt": "水印, 模糊",
        "seed": 7
    }
}'
```
### 单图生视频

```json
{
  "model": "veo3.1-video-720p",
  "prompt": "商品在干净的摄影棚桌面上缓慢旋转，伴随柔和反射光。",
  "image": "https://example.com/keyframe.png",
  "size": "720p",
  "aspect_ratio": "16:9",
  "duration": 6,
  "extra_body": {
    "generate_audio": false,
    "negative_prompt": "伪影, 抖动"
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-video-720p",
    "prompt": "商品在干净的摄影棚桌面上缓慢旋转，伴随柔和反射光。",
    "image": "https://example.com/keyframe.png",
    "size": "720p",
    "aspect_ratio": "16:9",
    "duration": 6,
    "extra_body": {
        "generate_audio": false,
        "negative_prompt": "伪影, 抖动"
    }
}'
```
### 首尾帧

```json
{
  "model": "veo3.1-fast-video-1080p",
  "prompt": "让画面从首帧自然过渡到尾帧，保持主体身份一致、镜头语言连贯。",
  "image": "https://example.com/start-frame.png",
  "last_image": "https://example.com/end-frame.png",
  "size": "1080p",
  "aspect_ratio": "16:9",
  "duration": 6,
  "extra_body": {
    "generate_audio": true
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-fast-video-1080p",
    "prompt": "让画面从首帧自然过渡到尾帧，保持主体身份一致、镜头语言连贯。",
    "image": "https://example.com/start-frame.png",
    "last_image": "https://example.com/end-frame.png",
    "size": "1080p",
    "aspect_ratio": "16:9",
    "duration": 6,
    "extra_body": {
        "generate_audio": true
    }
}'
```
### 多图参考一致性生视频

```json
{
  "model": "veo3.1-video-1080p",
  "prompt": "保持同一角色的脸、服装和身份一致，在雨夜小巷中向前行走。",
  "images": [
    "https://example.com/ref-1.png",
    "https://example.com/ref-2.png"
  ],
  "size": "1080p",
  "aspect_ratio": "9:16",
  "duration": 6,
  "extra_body": {
    "generate_audio": true,
    "seed": 11
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-video-1080p",
    "prompt": "保持同一角色的脸、服装和身份一致，在雨夜小巷中向前行走。",
    "images": [
        "https://example.com/ref-1.png",
        "https://example.com/ref-2.png"
    ],
    "size": "1080p",
    "aspect_ratio": "9:16",
    "duration": 6,
    "extra_body": {
        "generate_audio": true,
        "seed": 11
    }
}'
```
### 视频续写

```json
{
  "model": "veo3.1-video-720p",
  "prompt": "自然续接原视频中的动作，并保持同样的场景风格。",
  "video": "https://example.com/source.mp4",
  "size": "720p",
  "duration": 6,
  "extra_body": {
    "negative_prompt": "闪烁, 故障感",
    "seed": 9
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-video-720p",
    "prompt": "自然续接原视频中的动作，并保持同样的场景风格。",
    "video": "https://example.com/source.mp4",
    "size": "720p",
    "duration": 6,
    "extra_body": {
        "negative_prompt": "闪烁, 故障感",
        "seed": 9
    }
}'
```
## 响应字段

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |


## 响应示例

### 示例 1

```json
{}
```

## 任务状态与结果

创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。

---

# Vidu Q3

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/vidu
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/vidu.md
Description: 通过 UniAll 调用 Vidu Q3 系列，创建文生、单图、首尾帧和多参考图视频。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

更新时间：2026-08-04

## 概览

Vidu Q3 系列只使用两个稳定公共模型名，通过请求体顶层的 `resolution` 参数选择输出分辨率，不再把分辨率写进模型名。

| 公共模型 | 系列 | 文生视频 | 单图生视频 | 首尾帧 | 多参考图 |
| --- | --- | --- | --- | --- | --- |
| `viduq3p` | Q3 Pro | 支持 | 支持 | 支持 | 支持 1 至 4 张 |
| `viduq3t` | Q3 Turbo | 支持 | 支持 | 支持 | 支持 1 至 4 张 |

两个模型均支持 `540p`、`720p` 和 `1080p`，这两个 ID 是 Vidu Q3 对外唯一保留的公共模型名。

## 适用场景

Vidu Q3 适合以下任务：

- 根据文字提示词生成视频；
- 让一张可公开访问的图片动起来；
- 根据首帧和尾帧生成连续视频；
- 使用 1 至 4 张参考图约束人物、主体或视觉风格。

客户端只需选择公共模型并传入请求参数。不要传入渠道名、上游模型名、上游任务字段或路由控制参数。

## 接口

新接入统一使用以下接口：

| 用途 | 方法 | 路径 |
| --- | --- | --- |
| 创建视频任务 | `POST` | `/v1/videos` |
| 查询视频任务 | `GET` | `/v1/videos/{task_id}` |
| 下载视频文件 | `GET` | `/v1/videos/{task_id}/content` |

以下兼容接口仍可使用：

| 用途 | 方法 | 路径 |
| --- | --- | --- |
| 创建视频任务 | `POST` | `/v1/videos/generations` |
| 查询视频任务 | `GET` | `/v1/videos/generations/{task_id}` |
| 创建视频任务 | `POST` | `/v1/video/generations` |
| 查询视频任务 | `GET` | `/v1/video/generations/{task_id}` |

新接入建议统一使用 `/v1/videos`。

## 鉴权

所有请求均使用 UniAll Bearer Token：

```http
Authorization: Bearer sk-***
```

创建任务时还需发送：

```http
Content-Type: application/json
```

## 请求体参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `viduq3p` 或 `viduq3t`。 |
| `prompt` | string | 是 | 视频生成提示词。 |
| `duration` | integer | 是 | 输出时长，范围为 `1` 至 `16` 秒。 |
| `aspect_ratio` | string | 否 | `16:9`、`9:16`、`3:4`、`4:3` 或 `1:1`。 |
| `image` | string | 条件必填 | 单图模式的输入图或首尾帧模式的首帧，必须是公开可访问的 HTTP(S) URL。 |
| `last_image` | string | 条件必填 | 尾帧图片的公开 HTTP(S) URL，必须与 `image` 一起传入。 |
| `reference_image_urls` | string[] | 条件必填 | 多参考图模式的 1 至 4 个公开 HTTP(S) 图片 URL。 |
| `resolution` | string | 是 | `540p`、`720p` 或 `1080p`。 |
| `audio` | boolean | 否 | 是否生成声音。 |
| `bgm` | boolean | 否 | 文生视频的背景音乐控制。 |
| `seed` | integer | 否 | 随机种子。 |

根据生成模式选择输入字段：

| 模式 | 输入字段 |
| --- | --- |
| 文生视频 | `prompt` |
| 单图生视频 | `prompt` + `image` |
| 首尾帧生视频 | `prompt` + `image` + `last_image` |
| 多参考图生视频 | `prompt` + `reference_image_urls` |

字段约束：

- 每次请求都必须传入顶层 `resolution`。
- `image` 与 `reference_image_urls` 不能同时传入。
- `last_image` 不能单独使用，必须与 `image` 组成首尾帧。
- 首尾帧和多参考图模式不要使用 `images` 或 `image_urls`。
- `resolution`、`audio`、`bgm` 和 `seed` 都直接放在请求体顶层，不要包在 `extra_body` 中。
- `size` 不是 `resolution` 的兼容别名。

## 请求示例

### 文生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3p",
    "prompt": "A cinematic aerial shot over a futuristic coastal city at sunrise, soft light, slow camera push-in.",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "audio": false,
    "bgm": false,
    "seed": 42
  }'
```

### 单图生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3t",
    "prompt": "The person slowly raises their head and looks at the camera while the camera gently moves forward.",
    "image": "https://example.com/source.png",
    "duration": 5,
    "aspect_ratio": "9:16",
    "resolution": "540p",
    "audio": false,
    "seed": 42
  }'
```

### 首尾帧生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3p",
    "prompt": "The person turns naturally from a front view to a side view while identity and motion remain consistent.",
    "image": "https://example.com/head.png",
    "last_image": "https://example.com/tail.png",
    "duration": 6,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "audio": false,
    "seed": 42
  }'
```

### 多参考图生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3p",
    "prompt": "A @Image1 walking through a beach in the visual style of @Image2",
    "reference_image_urls": [
      "https://example.com/ref-1.png",
      "https://example.com/ref-2.png"
    ],
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "audio": false,
    "seed": 42
  }'
```

两个公共模型都支持 `reference_image_urls`。参考图提示词可以按数组顺序使用 `@Image1`、`@Image2` 等标记。

## 响应示例

### 任务创建成功

请保存 `id` 或兼容字段 `task_id`，用于后续查询：

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "viduq3p",
  "status": "queued",
  "progress": 0,
  "created_at": 1785772800
}
```

公共响应不会返回渠道标识、上游任务 ID、凭证信息或上游原始响应。

## 任务状态与结果

创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。

## 计费说明

计费取决于公共模型、请求的 `resolution` 和实际输出视频秒数。模型名本身不承载分辨率或时段计费档位。

百度 VOD/BV 渠道当前正常时段的参考消耗如下，适用于文生视频、单图生视频和首尾帧视频：

| 公共模型 | `540p` | `720p` | `1080p` |
| --- | ---: | ---: | ---: |
| `viduq3p`（Q3 Pro） | 0.28125 元/秒 | 0.625 元/秒 | 0.75 元/秒 |
| `viduq3t`（Q3 Turbo） | 0.21875 元/秒 | 0.375 元/秒 | 0.40625 元/秒 |

渠道消耗 = 单价 × 实际输出时长。多参考图请求可能选择其他符合条件的渠道，不能直接套用这张百度 VOD 表。最终对外价格和结算以 UniAll 模型页及消费日志为准。

## 常见错误

以下情况会在任务创建前被拒绝：

- 使用 `viduq3p` 或 `viduq3t` 之外的模型名；
- 缺少 `resolution`，或传入 `540p`、`720p`、`1080p` 以外的值；
- 使用 `size` 代替 `resolution`；
- 缺少 `duration`，或传入 `1` 至 `16` 之外的值；
- 使用 `21:9`、`1920x1080` 等不支持的画幅比例；
- `reference_image_urls` 为空或超过 4 张；
- 同时传入 `image` 与 `reference_image_urls`，或单独传入 `last_image`；
- 图片 URL 无法由服务端公开访问；
- 把支持的顶层参数放进 `extra_body`。

## 相关页面

- [视频生成概览](/zh-CN/models/video/overview)
- [模型列表](/zh-CN/models)

---

# Wan 2.6

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/wan-2-6
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/wan-2-6.md
Description: 通过 UniAll 视频 API 调用 Wan 2.6 模型生成视频。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

Wan 2.6 覆盖文生视频、图生视频和参考生视频模型家族。来源范围还包含 Wan 2.6 公共模型秒数参照表。

## 支持模型

| 模型 | 类型 | 秒数规则 |
| --- | --- | --- |
| `wan2.6-video-720p` | 文生视频 / 图生视频 | 必传；`5`、`10` 或 `15`。 |
| `wan2.6-video-1080p` | 文生视频 / 图生视频 | 必传；`5`、`10` 或 `15`。 |
| `wan2.6-i2v-flash-720p-audio` | 图生视频有声 | 必传；`5` 到 `15` 的任意整数。 |
| `wan2.6-i2v-flash-720p-silent` | 图生视频无声 | 必传；`5` 到 `15` 的任意整数。 |
| `wan2.6-i2v-flash-1080p-audio` | 图生视频有声 | 必传；`5` 到 `15` 的任意整数。 |
| `wan2.6-i2v-flash-1080p-silent` | 图生视频无声 | 必传；`5` 到 `15` 的任意整数。 |
| `wan2.6-r2v-720p` | 参考生视频 | 必传；以账号模型配置为准。 |
| `wan2.6-r2v-1080p` | 参考生视频 | 必传；以账号模型配置为准。 |
| `wan2.6-r2v-flash-720p-audio` | 参考生视频有声 | 必传；以账号模型配置为准。 |
| `wan2.6-r2v-flash-720p-silent` | 参考生视频无声 | 必传；以账号模型配置为准。 |
| `wan2.6-r2v-flash-1080p-audio` | 参考生视频有声 | 必传；以账号模型配置为准。 |
| `wan2.6-r2v-flash-1080p-silent` | 参考生视频无声 | 必传；以账号模型配置为准。 |

## Endpoint

```http
POST /v1/video/generations
GET  /v1/videos/{task_id}
```

## Authentication

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | Wan 2.6 模型 ID。 |
| `prompt` | string | 是 | 提示词。 |
| `image` | string | 条件必填 | 图生视频参考图。 |
| `images` | string[] | 条件必填 | R2V 模型参考图。 |
| `videos` | string[] | 条件必填 | R2V 模型参考视频。 |
| `duration` | integer | 是 | 参照支持模型表。 |
| `size` | string | 否 | 输出尺寸。文生视频可用它控制横版或竖版；图生视频跟随参考图方向。 |
| `extra_body.negative_prompt` | string | 否 | 不希望出现的内容。 |
| `extra_body.shot_type` | string | 否 | `single` 或 `multi`。 |
| `extra_body.seed` | integer | 否 | `-1` 表示随机；固定值更利于复现。 |
| `extra_body.audio` | string | 否 | 公开可访问的音频 URL。 |
| `extra_body.enable_prompt_expansion` | boolean | 否 | R2V 模型提示词扩展开关。 |

常见 `size` 包括 `1280*720`、`720*1280`、`1920*1080` 和 `1080*1920`。

## 文生视频示例

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-video-1080p",
    "prompt": "sunrise",
    "duration": 5,
    "size": "1080*1920",
    "extra_body": {
      "negative_prompt": "blur, watermark",
      "shot_type": "multi",
      "seed": -1
    }
  }'
```

## 参考视频示例

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-r2v-flash-720p-audio",
    "prompt": "Keep the same subject identity and cinematic style, generate a faster-paced new shot.",
    "videos": [
      "https://example.com/reference-shot-1.mp4"
    ],
    "size": "1280*720",
    "duration": 5,
    "extra_body": {
      "negative_prompt": "watermark, blur, flicker",
      "audio": "https://example.com/guide-audio.mp3",
      "shot_type": "single",
      "enable_prompt_expansion": false,
      "seed": -1
    }
  }'
```

## 多图参考示例

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-r2v-flash-1080p-silent",
    "prompt": "Keep the same product identity and style, generate a clean marketing video.",
    "images": [
      "https://example.com/ref-1.png",
      "https://example.com/ref-2.png"
    ],
    "size": "1920*1080",
    "duration": 10,
    "extra_body": {
      "negative_prompt": "watermark, blur",
      "shot_type": "multi",
      "enable_prompt_expansion": true,
      "seed": 42
    }
  }'
```

## 任务状态与结果

创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。

## 计费说明

Wan 2.6 计费与模型家族、输出分辨率、时长、音频模式，以及任务是文生、图生还是参考生视频有关。最终以结算记录为准。

## 常见错误

- 使用所选模型不允许的秒数。
- 期望图生视频通过 `size` 控制横竖版；图生通常跟随参考图方向。
- 传入私有媒体 URL。
- 用非 R2V 模型传 R2V 字段。
- 静音模型中传入 `audio`。

## 相关页面

- [视频生成概览](/zh-CN/models/video/overview)
- [Vidu 视频生成](/zh-CN/models/video/vidu)
- [Sora 2 视频生成](/zh-CN/models/video/sora-2)

---

# 创建视频生成任务

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/wan-2-6/create-task
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/wan-2-6/create-task.md
Description: Wan 2.6 创建视频生成任务接口。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

## Endpoint


```http
POST /v1/video/generations
```
## Header 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No |  | Bearer &#123;your_token&#125; |
## 请求体参数

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `model` | string | Yes | 模型名称 | “wan2.6-video-720p”，“wan2.6-video-1080p” |
| `prompt` | string | Yes | 提示词 |  |
| `image` | string | Yes | 参考图 |  |
| `duration` | string | Yes | 秒数 |  |
| `size` | string | Yes | 产出视频尺寸 | "1280*720", "720*1280", "1920*1080", "1080*1920", 注意：文生视频时可选size控制横版竖版，图生视频时size参数无效，但仍然可以传入，但是产出视频横版竖版跟随参考图 |
| `extra_body` | object | Yes |  |  |

## 请求示例

### 示例 1

```json
{
  "model": "wan2.6-video-1080p",
  "prompt": "日出",
  "duration": 5,
  "size": "1080*1920",
  "extra_body": {
    "negative_prompt": "不要出现模糊, 不要出现水印",
    "shot_type": "multi",
    "seed": -1
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-video-1080p",
    "prompt": "日出",
    "duration": 5,
    "size": "1080*1920",
    "extra_body": {
        "negative_prompt": "不要出现模糊, 不要出现水印",
        "shot_type": "multi",
        "seed": -1
    }
}'
```
## 响应字段

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |


## 响应示例

### 成功

```json
{
  "id": "task_xxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "wan2.6-video-1080p",
  "status": "in_progress",
  "progress": 5,
  "created_at": 1773984104
}
```

## 任务状态与结果

创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。

---

# Wan 系列模型秒数参照表

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/wan-2-6/duration-table
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/wan-2-6/duration-table.md
Description: Wan 模型秒数来源参照表。

## WAN 2.6

| 公共模型 | 类型 | 秒数要求 | 当前允许值 |
|---|---|---|---|
| `wan2.6-video-720p` | 文生视频 / 图生视频 | 必传 | `5`、`10`、`15` |
| `wan2.6-video-1080p` | 文生视频 / 图生视频 | 必传 | `5`、`10`、`15` |
| `wan2.6-i2v-flash-720p-audio` | 图生视频 有声 | 必传 | `5` 到 `15` 的任意整数 |
| `wan2.6-i2v-flash-720p-silent` | 图生视频 无声 | 必传 | `5` 到 `15` 的任意整数 |
| `wan2.6-i2v-flash-1080p-audio` | 图生视频 有声 | 必传 | `5` 到 `15` 的任意整数 |
| `wan2.6-i2v-flash-1080p-silent` | 图生视频 无声 | 必传 | `5` 到 `15` 的任意整数 |
| `wan2.6-r2v-720p` | 参考生视频 | 必传 | `5`、`10` |
| `wan2.6-r2v-1080p` | 参考生视频 | 必传 | `5`、`10` |
| `wan2.6-r2v-flash-720p-audio` | 参考生视频 有声 | 必传 | `5`、`10` |
| `wan2.6-r2v-flash-720p-silent` | 参考生视频 无声 | 必传 | `5`、`10` |
| `wan2.6-r2v-flash-1080p-audio` | 参考生视频 有声 | 必传 | `5`、`10` |
| `wan2.6-r2v-flash-1080p-silent` | 参考生视频 无声 | 必传 | `5`、`10` |


## 一句话总结

- `wan2.6-video-*`：`5 / 10 / 15`
- `wan2.6-i2v-flash-*`：`5~15` 任意整数
- `wan2.6-r2v-*`：`5 / 10`
- `wan2.6-r2v-flash-*`：`5 / 10`

---

# Wan 2.6 R2V 系列创建视频任务

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/wan-2-6/r2v-create-task
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/wan-2-6/r2v-create-task.md
Description: Wan 2.6 R2V 创建视频任务接口。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

## Endpoint


```http
POST /v1/video/generations
```
## 请求体参数

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `model` | string | No | Example field | Appears in a request example; no separate field description is provided. |
| `prompt` | string | No | Example field | Appears in a request example; no separate field description is provided. |
| `videos` | array | No | Example field | Appears in a request example; no separate field description is provided. |
| `size` | string | No | Example field | Appears in a request example; no separate field description is provided. |
| `duration` | number | No | Example field | Appears in a request example; no separate field description is provided. |
| `extra_body` | object | No | Example field | Appears in a request example; no separate field description is provided. |
| `images` | array | No | Example field | Appears in a request example; no separate field description is provided. |

## 请求示例

### 示例 1：视频参考

```json
{
  "model": "wan2.6-r2v-flash-720p-audio",
  "prompt": "保持相同主体身份与电影感风格，生成一段更快节奏的新镜头。",
  "videos": [
    "https://example.com/reference-shot-1.mp4"
  ],
  "size": "1280*720",
  "duration": 5,
  "extra_body": {
    "negative_prompt": "watermark, blur, flicker",
    "audio": "https://example.com/guide-audio.mp3",
    "shot_type": "single",
    "enable_prompt_expansion": false,
    "seed": -1
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-r2v-flash-720p-audio",
    "prompt": "保持相同主体身份与电影感风格，生成一段更快节奏的新镜头。",
    "videos": [
        "https://example.com/reference-shot-1.mp4"
    ],
    "size": "1280*720",
    "duration": 5,
    "extra_body": {
        "negative_prompt": "watermark, blur, flicker",
        "audio": "https://example.com/guide-audio.mp3",
        "shot_type": "single",
        "enable_prompt_expansion": false,
        "seed": -1
    }
}'
```
### 示例 2：多图参考

```json
{
  "model": "wan2.6-r2v-flash-1080p-silent",
  "prompt": "保持相同产品身份与风格，生成一段干净的营销视频。",
  "images": [
    "https://example.com/ref-1.png",
    "https://example.com/ref-2.png"
  ],
  "size": "1920*1080",
  "duration": 10,
  "extra_body": {
    "negative_prompt": "watermark, blur",
    "shot_type": "multi",
    "enable_prompt_expansion": true,
    "seed": 42
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-r2v-flash-1080p-silent",
    "prompt": "保持相同产品身份与风格，生成一段干净的营销视频。",
    "images": [
        "https://example.com/ref-1.png",
        "https://example.com/ref-2.png"
    ],
    "size": "1920*1080",
    "duration": 10,
    "extra_body": {
        "negative_prompt": "watermark, blur",
        "shot_type": "multi",
        "enable_prompt_expansion": true,
        "seed": 42
    }
}'
```
## 响应字段

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |


## 响应示例

### 示例 1

```json
{}
```

## 任务状态与结果

创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。

---

# Wan 2.2 Animate 视频编辑

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/wan-2-6/wan-2-2-animate
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/wan-2-6/wan-2-2-animate.md
Description: Wan 2.2 Animate 视频编辑接口。

本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。

## 说明

它支持两种工作模式：

- `animate`
  - 用输入视频里的动作，驱动输入图片中的人物或主体动起来
- `replace`
  - 用输入图片中的人物或主体，替换输入视频里的主体

换成更直白的话：

- `animate` 更接近“动作驱动 / 动作替换”
- `replace` 更接近“视频换人 / 角色替换”

## Endpoint


```http
POST /v1/video/generations
```
## Header 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No |  | Bearer &#123;your_token&#125; |
## 请求体参数

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `model` | string | Yes | 公共模型名 | 使用 `wan2.2-animate-480p` 或 `wan2.2-animate-720p` |
| `prompt` | string | Yes | 补充提示词 | 可选，但建议填写风格、场景、镜头意图 |
| `image` | string | Yes | 参考图URL | 实际上建议必填 \| 源角色图片 \| 只能一张 |
| `video` | string | Yes | 视频URL | 实际上建议必填 \| 源动作或替换视频 \| 只能一段 |
| `duration` | string | Yes | 目标时长，单位秒 | 必填 |
| `mode` | string | Yes | 工作模式 | 允许值：`animate`、`replace`（归一化字段，可不在extra_body中传递） |
| `seed` | string | Yes | 随机种子 | 随机种子，（归一化字段，可不在extra_body中传递） |
| `extra_body` | object | Yes |  |  |

## 请求示例

### 示例

```json
{
  "model": "string",
  "prompt": "string",
  "image": "string",
  "video": "string",
  "duration": "string",
  "mode": "string",
  "seed": "string",
  "extra_body": {
    "mode": "string",
    "seed": "string"
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "string",
    "prompt": "string",
    "image": "string",
    "video": "string",
    "duration": "string",
    "mode": "string",
    "seed": "string",
    "extra_body": {
        "mode": "string",
        "seed": "string"
    }
}'
```
## 响应字段

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |


## 响应示例

### 示例 1

```json
{}
```

## 任务状态与结果

创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。