# 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 | Examples use `{BASE_URL}` as a placeholder. |
| 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.

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, GPT-Image-2, Nano Series | `POST /v1/images/tasks` or `POST /v1/images/generations` |
| Video Generation | Happy-Horse, Seedance 2.0, Grok Imagine, Veo 3.1, Vidu, Kling, Wan 2.6, Sora 2 | `POST /v1/video/generations` or `POST /v1/videos` |
| 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",
      "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 [Grok Imagine Video Generation](/models/video/grok-imagine) when the model ID is `grok-imagine`.
- 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)
- [Grok Imagine Video Generation](/models/video/grok-imagine)

---

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

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 Generation

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.

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: Kling Avatar v2 digital human source documentation.

This document explains how to use Kling Avatar v2 async digital human video generationEndpoint.

Supported models:

| Model name | Type | Suitable scenarios | Billing mode |
|---|---|---|---|
| `kling-avatar-v2-standard` | digital human video | standard narration, customer-service explanation, course introduction, marketing short video | billed by output video duration |
| `kling-avatar-v2-pro` | digital human video | higher-quality digital-human narration, formal promotional video, brand video, important course content | billed by output video duration |

Endpoint async task mode:

| Operation | Method | Path |
|---|---|---|
| submitdigital human videotask | `POST`|`/v1/video/generations` |
| querydigital human videotask | `GET`|`/v1/video/generations/{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

Kling Avatar v2 imageandaudio generationdigital human video. userrequiresprovidesone imageandaaudio, Model generation and action video.

supports:

| Model | Note |
|---|---|
| `kling-avatar-v2-standard` | standard, standard narrationand generation |
| `kling-avatar-v2-pro` | Pro, stable |

---

## 3. submitdigital human videotask

```http
POST https://api.xxx.xx/v1/video/generations
```

### 3.1 Request Parameters

| Parameters | Type | Required | Note |
|---|---|---|---|
| `model`| string | Yes |`kling-avatar-v2-standard` or `kling-avatar-v2-pro` |
| `image_url` | string | Yes | image URL |
| `audio_url` | string | Yes | audio URL, |
| `audio_duration_seconds` | number | Yes | audioduration, submit billing |
| `prompt` | string | No | style, scenario, Status, camera |

Note:

- `audio_duration_seconds` pass.
- Field submit, billing.
- pass inaudio duration, cost and task.

### 3.2 submitResponse Examples

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.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. querydigital human videotask

```http
GET https://api.xxx.xx/v1/video/generations/{task_id}
```

queryExample:

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

Completed Response Example:

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "status": "completed",
  "video_url": "https://api.xxx.xx/media/xxxxx.mp4",
  "result": {
    "outputs": [
      "https://api.xxx.xx/media/xxxxx.mp4"
    ]
  }
}
```

---

## 5. Request Examples

### 5.1 Standard generationcustomer-service explanationvideo

```bash
curl -X POST "https://api.xxx.xx/v1/video/generations" \
 -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
 -H "Content-Type: application/json" \
 -d '{"model": "kling-avatar-v2-standard",
 "image_url": "https://cdn.example.com/avatar/customer-service.png",
 "audio_url": "https://cdn.example.com/audio/customer-intro.mp3",
 "audio_duration_seconds": 12,
 "prompt": "friendly customer service presenter, natural expression, clean studio lighting"}'
```

### 5.2 Standard generationcourse introduction

```bash
curl -X POST "https://api.xxx.xx/v1/video/generations" \
 -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
 -H "Content-Type: application/json" \
 -d '{"model": "kling-avatar-v2-standard",
 "image_url": "https://cdn.example.com/avatar/teacher.png",
 "audio_url": "https://cdn.example.com/audio/course-opening.mp3",
 "audio_duration_seconds": 18.5,
 "prompt": "professional teacher, warm smile, stable camera, natural lip sync"}'
```

### 5.3 Pro generation video

```bash
curl -X POST "https://api.xxx.xx/v1/video/generations" \
 -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
 -H "Content-Type: application/json" \
 -d '{"model": "kling-avatar-v2-pro",
 "image_url": "https://cdn.example.com/avatar/brand-host.png",
 "audio_url": "https://cdn.example.com/audio/brand-message.mp3",
 "audio_duration_seconds": 24,
 "prompt": "premium corporate spokesperson video, clean studio background, confident expression"}'
```

### 5.4 Pro generationnews broadcast

```bash
curl -X POST "https://api.xxx.xx/v1/video/generations" \
 -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
 -H "Content-Type: application/json" \
 -d '{"model": "kling-avatar-v2-pro",
 "image_url": "https://cdn.example.com/avatar/news-anchor.png",
 "audio_url": "https://cdn.example.com/audio/news-briefing.mp3",
 "audio_duration_seconds": 32.7,
 "prompt": "news anchor style, formal tone, stable frontal shot, neutral expression"}'
```

---


## 6. Common Errors

### 6.1 image_url

digital human video provides image:

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

### 6.2 audio_url

digital human video provides audio:

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

### 6.3 audio_duration_seconds

Error:

```json
{
  "model": "kling-avatar-v2-standard",
  "image_url": "https://cdn.example.com/avatar.png",
  "audio_url": "https://cdn.example.com/voice.mp3"
}
```
audioduration:

```json
{
  "audio_duration_seconds": 12.5
}
```

---

## 7. recommended

1. image.
2. use TTS or generate aaudio.
3. audio duration.
4. submit `/v1/video/generations`, pass in `image_url`, `audio_url`, `audio_duration_seconds`.
5. poll `/v1/video/generations/{task_id}`.
6. task completed read `video_url`.

---

## 8. Minimum Valid Request

### 8.1 Avatar Standard

```bash
curl -X POST "https://api.xxx.xx/v1/video/generations" \
 -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
 -H "Content-Type: application/json" \
 -d '{"model": "kling-avatar-v2-standard",
 "image_url": "https://cdn.example.com/avatar.png",
 "audio_url": "https://cdn.example.com/voice.mp3",
 "audio_duration_seconds": 10}'
```

### 8.2 Avatar Pro

```bash
curl -X POST "https://api.xxx.xx/v1/video/generations" \
 -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
 -H "Content-Type: application/json" \
 -d '{"model": "kling-avatar-v2-pro",
 "image_url": "https://cdn.example.com/avatar.png",
 "audio_url": "https://cdn.example.com/voice.mp3",
 "audio_duration_seconds": 10}'
```

---

# 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 item from the source menu.

## Included Pages

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

## Integration Guidance

Digital-human narration uses Kling Avatar v2 models. Submit a video generation task with the avatar, voice, and script inputs, then poll the returned `task_id` until the output video is available.

Use [Speech Synthesis](/models/audio/speech-synthesis) first when the workflow requires a custom `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.

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 Image Generation

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.

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)

---

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

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

---

# Nano Series Image Generation

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

Nano Series covers the NanoBanana family. Use it when you need a concrete Nano model tier and `aspect_ratio`-based shape control. The source scope includes both OpenAI-compatible and Gemini-compatible entry points, but new general integrations can start from the async image task flow.

## Supported Models

| Model family | Example IDs | Notes |
| --- | --- | --- |
| NanoBanana | `NanoBanana` | Base NanoBanana model. |
| NanoBanana Pro | `NanoBananaPro-*` | Pro tier variants. |
| NanoBanana 2 | `NanoBanana2-0.5K`, `NanoBanana2-1K` | Resolution-tiered NanoBanana 2 variants. |

Actual availability depends on account channel and model-price configuration.

## Recommended Endpoint

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

The Apifox source also exposes OpenAI-compatible image endpoints for Nano:

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

and a Gemini-compatible format for Gemini-style clients. Use the format that matches your client. The request concepts below stay the same.

## Authentication

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

## Request Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | Concrete Nano model ID, such as `NanoBanana2-0.5K`. |
| `prompt` | string | Yes | Generation or editing prompt. |
| `task_type` | string | No | `text2image` or `image2image`. Can be inferred from image input. |
| `image` | string/object | Conditional | Single reference image for editing. |
| `images` | string[] | Conditional | Multiple reference image URLs. |
| `aspect_ratio` | string | No | Recommended shape control, such as `1:1`, `16:9`, `9:16`, `4:3`, or `3:4`. |
| `output_format` | string | No | `NanoBanana` supports `png`, `jpeg`, `webp`; Pro and NanoBanana 2 variants support `png` and `jpeg` in the current source scope. |
| `n` | integer | No | Output count. Default is `1`; maximum depends on upstream limits. |
| `response_format` | string | No | Prefer `url`. |

## Text-To-Image Example

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

## Image-To-Image Example

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

## Query Task Status

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

## Billing Notes

NanoBanana family models are billed by configured model unit price multiplied by `n` or the actual returned result count. `aspect_ratio` and `output_format` control output shape and format, but are not separate billing dimensions in the current source scope.

## Common Errors

- Passing a Nano model ID that is not enabled for the current account.
- Mixing `image` and `images` with compatibility image fields.
- Treating `size` as the primary Nano control; use `aspect_ratio` instead.
- Requesting an unsupported output format for the selected Nano family.
- Polling before the task has been created.

## Related Pages

- [Async Image Generation](/models/image/async-image-generation)
- [GPT-Image-2 Image Generation](/models/image/gpt-image-2)
- [Seedream Image Generation](/models/image/seedream)

---

# Native Gemini 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: Nano Series native Gemini format endpoint.

## Endpoint


```http
POST /v1beta/models/{modeName}:generateContent
```
## Header Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No | | Bearer &#123;your_token&#125; |
## Path Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `modeName` | string | Yes | gemini-3-pro-image-preview-1k, gemini-3-pro-image-preview-2k, gemini-3-pro-image-preview-4k, gemini-3.1-flash-image-preview-512, gemini-3.1-flash-image-preview-1k, gemini-3.1-flash-image-preview-2k, gemini-3.1-flash-image-preview-4k | Model name: |
## Request Body Parameters

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `generationConfig.imageConfig.aspectRatio` | string | Yes | Ratio | Optional values:1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 |
| `generationConfig.imageConfig.outputFormat` | string | Yes | format | Optional values: jpeg, png |
| `contents` | array | No | Example field | Appears in a request example; no separate field description is provided. |
| `generationConfig` | object | No | Example field | Appears in a request example; no separate field description is provided. |

## Request Examples

### default

```json
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": " "
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "IMAGE"
    ]
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1beta/models/{modeName}:generateContent" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"contents": [{"role": "user",
 "parts": [{"text": " "}]}],
 "generationConfig": {"responseModalities": ["IMAGE"]}}'
```
###

```json
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "[] HA[style], []and[]. [style]and[style].. "
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "IMAGE"
    ],
    "imageConfig": {
      "aspectRatio": "9:16",
      "imageSize": "1K"
    }
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1beta/models/{modeName}:generateContent" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"contents": [{"role": "user",
 "parts": [{"text": "[] HA[style], []and[]. [style]and[style].. "}]}],
 "generationConfig": {"responseModalities": ["IMAGE"],
 "imageConfig": {"aspectRatio": "9:16",
 "imageSize": "1K"}}}'
```
### image editing

```json
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": " [] [] one[styledescription]. reserved [], [new /]"
        },
        {
          "inline_data": {
            "mime_type": "image/jpeg",
            "data": "image_base64"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "IMAGE"
    ],
    "imageConfig": {
      "aspectRatio": "9:16",
      "imageSize": "1K"
    }
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1beta/models/{modeName}:generateContent" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"contents": [{"role": "user",
 "parts": [{"text": " [] [] one[styledescription]. reserved [], [new /]"},
 {"inline_data": {"mime_type": "image/jpeg",
 "data": "image_base64"}}]}],
 "generationConfig": {"responseModalities": ["IMAGE"],
 "imageConfig": {"aspectRatio": "9:16",
 "imageSize": "1K"}}}'
```
###

```json
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "useprovides image, [image2items in] [image1items in]. [image1items in]. [description]. "
        },
        {
          "inline_data": {
            "mime_type": "image/jpeg",
            "data": "image_base64_1"
          }
        },
        {
          "inline_data": {
            "mime_type": "image/jpeg",
            "data": "image_base64_2"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "IMAGE"
    ],
    "imageConfig": {
      "aspectRatio": "9:16",
      "imageSize": "1K"
    }
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1beta/models/{modeName}:generateContent" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"contents": [{"role": "user",
 "parts": [{"text": "useprovides image, [image2items in] [image1items in]. [image1items in]. [description]. "},
 {"inline_data": {"mime_type": "image/jpeg",
 "data": "image_base64_1"}},
 {"inline_data": {"mime_type": "image/jpeg",
 "data": "image_base64_2"}}]}],
 "generationConfig": {"responseModalities": ["IMAGE"],
 "imageConfig": {"aspectRatio": "9:16",
 "imageSize": "1K"}}}'
```
## Response Fields

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


## Response Examples

### Success

```json
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/jpeg",
              "data": "image_base64"
            }
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": []
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 0,
    "candidatesTokenCount": 0,
    "totalTokenCount": 0
  }
}
```

---

# Native OpenAI 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: Nano Series native OpenAI format endpoint.

## 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:NanoBanana, NanoBananaPro-1K, NanoBananaPro-2K, NanoBananaPro-4K, NanoBanana2-0.5K, NanoBanana2-1K, NanoBanana2-2K, NanoBanana2-4K |
| `--aspect_ratio` | string | Yes | aspect ratio | Optional values:1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 |
| `--output_format` | string | Yes | image type | Optional values:"jpeg", "png", "webp" |
| `messages` | array | 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. |
| `stream` | boolean | No | Example field | Appears in a request example; no separate field description is provided. |

## Request Examples

###

```json
{
  "model": "NanoBananaPro-1K",
  "messages": [
    {
      "role": "user",
      "content": "a cute cat"
    }
  ],
  "extra_body": {
    "google": {
      "image_config": {
        "aspect_ratio": "16:9"
      }
    }
  },
  "stream": true
}
```

```bash
curl -X POST "{BASE_URL}/v1/chat/completions" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "NanoBananaPro-1K",
 "messages": [{"role": "user",
 "content": "a cute cat"}],
 "extra_body": {"google": {"image_config": {"aspect_ratio": "16:9"}}},
 "stream": true}'
```
###

```json
{
  "model": "NanoBananaPro-1K",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": ", generation, "
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/xxxxxxx.jpg"
          }
        }
      ]
    }
  ],
  "extra_body": {
    "google": {
      "image_config": {
        "aspect_ratio": "16:9"
      }
    }
  },
  "stream": true
}
```

```bash
curl -X POST "{BASE_URL}/v1/chat/completions" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "NanoBananaPro-1K",
 "messages": [{"role": "user",
 "content": [{"type": "text",
 "text": ", generation, "},
 {"type": "image_url",
 "image_url": {"url": "https://example.com/xxxxxxx.jpg"}}]}],
 "extra_body": {"google": {"image_config": {"aspect_ratio": "16:9"}}},
 "stream": true}'
```
## Response Fields

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


## Response Examples

### generationSuccess

```json
{
  "id": "chatcmpl_3a72451d018247b6a14adb45275c2433",
  "object": "chat.completion.chunk",
  "created": 1773835762,
  "model": "NanoBananaPro-8K",
  "choices": [
    {
      "index": 0,
      "delta": {
        "role": "assistant",
        "content": "https://xxx.xxx.cn/output/38fa5bcb-d055-40b0-9f04-5ef259c9131c-u2_307ace79-d89b-4075-9e71-8180774947c4.jpeg"
      },
      "finish_reason": "stop"
    }
  ],
  "media": {
    "outputs": [
      "https://xxx.xxx.cn/output/38fa5bcb-d055-40b0-9f04-5ef259c9131c-u2_307ace79-d89b-4075-9e71-8180774947c4.jpeg"
    ]
  }
}
```

---

# 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 only the selected image pages from the source menu.

## Included Pages

- [Async Image Generation](/models/image/async-image-generation)
- [Seedream Image Generation](/models/image/seedream)
- [GPT-Image-2 Image Generation](/models/image/gpt-image-2)
- [Nano Series Image Generation](/models/image/nano-series)

## Integration Guidance

Start with the async image generation page when the selected model uses a polling flow. Seedream and OpenAI-compatible image pages document their synchronous generation and edit endpoints separately.

---

# Seedream Image Generation

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

---

# Grok Imagine Video Generation

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.

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. Query Taskand video

### 8.1 queryStatus

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

In progress:

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

completed:

```json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video",
  "model": "grok-imagine",
  "status": "completed",
  "progress": 100,
  "created_at": 1773980459,
  "completed_at": 1773980519,
  "seconds": "6",
  "size": "720p",
  "metadata": {
    "url": "https://example.com/result.mp4"
  }
}
```

Failed:

```json
{
  "id": "task_xxx",
  "object": "video",
  "model": "grok-imagine",
  "status": "failed",
  "progress": 100,
  "created_at": 1773980459,
  "error": {
    "code": "task_failed",
    "message": "request rejected"
  }
}
```

recommended `2-5` poll,`status` `completed` or `failed`.

### 8.2 Get Video File

```bash
curl "{BASE_URL}/v1/videos/task_xxx/content" \
 -H "Authorization: Bearer sk-***" \
 -o result.mp4
```

 Endpointreturn `video/mp4` file. usequeryresponses `metadata.url`.

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

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.

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 Video Generation

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: Grok Video 1.5 source documentation.

Updated: 2026-06-26

This document explains how to use aijisu call `grok-video-1.5`. Model single-image-to-video: userprovidesoneInput imageandaprompt, the platformcreates an async video generation task.

## 1. Model

| Model | Capability | Input image | Output resolution |
| --- | --- | --- | --- |
| `grok-video-1.5`| single-image-to-video | supports 1 |`480p`, `720p`, `1080p` |

Note:

- `grok-video-1.5` Yes Model, do notand legacy `grok-imagine`.
- Currently only supportssingle-image-to-video, does not supporttext-to-video, multiple reference images, video input, video editingorvideo extension.
- the input image must be a URL accessible by the platform and upstream service.
- There is no separate landscape/portrait parameter currently; requires landscape passLandscape, requires portrait passPortrait.

## 2. Endpoint

### 2.1 Create Video Task

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

request headers:

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

### 2.2 Query Video Task

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

compatibilityqueryEndpoint:

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

### 2.3 Get Video File

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

task completed, readqueryresponses `video_url`, `/content` endpoint to get Video File.

## 3. Parameter Reference

| Parameters | Type | Required | Note |
| --- | --- | --- | --- |
| `model`| string | Yes | always pass `grok-video-1.5` |
| `prompt` | string | Yes | video generationprompt, recommended: describe the subject, action, camera, styleand |
| `image`| string | one of two required | Input image URL; and `image_url` one of two required |
| `image_url`| string | one of two required | Input image URL; and `image` one of two required |
| `duration`| integer | No | Output video duration, supports `1-15`, recommended pass in |
| `seconds`| string | No | Output video duration compatibility field; prefer using `duration` |
| `size`| string | No | Output resolution, supports `480p`, `720p`, `1080p` |
| `resolution`| string | No | Output resolution compatibility field; prefer using `size` |

Field Constraints:

- `image` and `image_url` only pass.
- do not pass both `images`, `image_urls`, `reference_image_urls` Field.
- do not pass `video`, `video_url`, `videos`, `video_urls` video inputField.
- do not pass `aspect_ratio`.
- do not pass `extra_body.operation` editing, reference video or text-to-video capability.
- `size`/`resolution` Resolution tier, landscape or portrait; control orientation through the input image aspect ratio.
- If you pass both `size` and `resolution`, recommended value.

## 4. Request Examples

In the examples below, `{BASE_URL}` can be replaced with `https://api.aijisu.cn`.

### 4.1 use `image_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": "A cinematic close-up of a glass perfume bottle on a marble table, soft morning light, slow camera push-in, elegant product video, no text, no logo.",
 "image_url": "https://example.com/source.jpg",
 "duration": 6,
 "size": "720p"}'
```

### 4.2 use `image`

```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 landscape photo becomes a gentle animated scene, leaves moving in the wind, soft natural lighting, stable camera, no text.",
 "image": "https://example.com/landscape.png",
 "duration": 8,
 "size": "1080p"}'
```

### 4.3 480p fast

```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 simple product shot, the object slowly rotates on a clean white background, smooth motion, no text.",
 "image_url": "https://example.com/product.jpg",
 "duration": 4,
 "size": "480p"}'
```

## 5. Create Response Example

A successful create request returns a task object. At this point, the video is usually queued or generating.

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

Save `id` or `task_id`, for later task polling.

## 6. Query Task

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

In-progress Response Example:

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "grok-video-1.5",
  "status": "in_progress",
  "progress": 35,
  "created_at": 1782400000
}
```

Completed Response Example:

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "grok-video-1.5",
  "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"
    ]
  }
}
```

## 7. Download Video

Method 1: use the value returned by the query response directly `video_url`.

Method 2: use the task content endpoint to get the file stream.

```bash
curl -L "{BASE_URL}/v1/videos/task_xxxxxxxxxxxxx/content" \
 -H "Authorization: Bearer sk-***" \
 -o grok-video-1.5-output.mp4
```

## 8. Status Values

| Status | Note |
| --- | --- |
| `queued` | Task created and waiting for processing |
| `in_progress` | Task is processing |
| `completed` | Task is complete and the video URL can be read |
| `failed`| taskFailed, responses `error.message` |

Clients should poll every 3 to 10 seconds, until the task enters `completed` or `failed`.

## 9. Common Errors

### sending the model to an image endpoint

`grok-video-1.5` Yesvideo model, call `/v1/videos`, do not `/v1/images/generations`.

### missing input image

 Model pass `image` or `image_url`. only pass `prompt`.

### multiple images were passed

 Model supportsoneInput image. do not pass `images`, `image_urls` or `reference_image_urls`.

### video input was passed

 Modeldoes not supportvideo input. do not pass `video`, `video_url`, `videos` or `video_urls`.

### invalid resolution format

`size` or `resolution` only pass:

- `480p`
- `720p`
- `1080p`

do not pass `1920x1080`, `1280x720`, `4k` or sizestring.

### `aspect_ratio` controlLandscapeportrait

 Model does not support `aspect_ratio`. submit change the input image Orientation, landscapeuseLandscapeimage, portraitusePortraitimage.

### requesting edit or extension capabilities

`grok-video-1.5` does not supporteditingand. do not pass:

```json
{
  "extra_body": {
    "operation": "edit_video"
  }
}
```

or:

```json
{
  "extra_body": {
    "operation": "video_extend"
  }
}
```

## 10. Prompt Guidance

Prompt Guidance:

- subject: object.
- action: subject.
- camera:.
- style:.
- constraints: no text, no logo, no people.

Example:

```markdown
A cinematic product video of the object slowly rotating on a clean studio background, soft natural light, smooth camera push-in, realistic texture, no text, no logo.
```

## 11. Minimum Valid Request

```json
{
  "model": "grok-video-1.5",
  "prompt": "A calm product video, slow camera movement, soft light, no text.",
  "image_url": "https://example.com/source.jpg",
  "duration": 6,
  "size": "720p"
}
```

---

# Create Video Generation Task (Old)

Locale: en
URL: https://docs.uniall.ai/models/video/grok/legacy-create-video
Source: site-docs/models/video/grok/legacy-create-video.md
Description: Legacy Grok create video generation task endpoint.

## Overview

### `grok-imagine`

 scenario:

- text-to-video
- single-image-to-video

 Rules:

- only `prompt` -> text-to-video
- `prompt + image` -> image-to-video

## 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 |
| `duration`| string | Yes |, | allowed values:`6`, `10` |
| `size`| string | Yes | output resolution | allowed values:`480p`, `720p` |
| `aspect_ratio`| string | Yes | output aspect ratio | allowed values:`16:9`, `1:1`, `9:16` |

## Request Examples

### text-to-video

```json
{
  "model": "grok-imagine",
  "prompt": " camera, fast, camera. ",
  "size": "720p",
  "aspect_ratio": "16:9",
  "duration": 6
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -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}'
```
### single-image-to-video

```json
{
  "model": "grok-imagine",
  "prompt": " camera, camera. ",
  "image": "https://example.com/portrait.png",
  "size": "480p",
  "aspect_ratio": "9:16",
  "duration": 10
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -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": "9:16",
 "duration": 10}'
```
## Response Fields

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


## Response Examples

### Example 1

```json
{}
```

---

# Query Video Task

Locale: en
URL: https://docs.uniall.ai/models/video/grok/legacy-query-video
Source: site-docs/models/video/grok/legacy-query-video.md
Description: Legacy Grok query video task endpoint.

## Endpoint


```http
GET /v1/videos/{task_id}
```
## Header Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No | | Bearer &#123;your_token&#125; |
## Path Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `task_id` | string | Yes | | |
## Response Fields

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


## Response Examples

### Example 1

```json
{
  "id": "task_xxxxxxxxxx",
  "model": "grok-imagine",
  "object": "video",
  "status": "completed",
  "seconds": "8",
  "task_id": "5c9e83c9-1044-46cd-8cff-b2c4cb90efba",
  "progress": 100,
  "video_url": "https://xxxxxx/r/xxxxxx.mp4",
  "created_at": 1774102861000
}
```

---

# Happy-Horse Video Generation

Locale: en
URL: https://docs.uniall.ai/models/video/happy-horse
Source: site-docs/models/video/happy-horse.md
Description: Generate videos with Happy-Horse models through UniAll video APIs.

Happy-Horse supports text-to-video, image-to-video, multi-reference video generation, and video editing. Use the unified video generation endpoint to submit a task, then poll the task ID until a result URL is available.

## Supported Models

| Model | Use case |
| --- | --- |
| `happy-horse-720p` | Text-to-video, image-to-video, and multi-reference generation at 720p. |
| `happy-horse-1080p` | Text-to-video, image-to-video, and multi-reference generation at 1080p. |
| `happy-horse-edit-720p` | Video editing at 720p. |
| `happy-horse-edit-1080p` | Video editing at 1080p. |

## 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 | One of the Happy-Horse public model IDs. |
| `prompt` | string | Yes | Prompt text. Maximum source limit: `2500` characters. |
| `aspect_ratio` | string | No | `16:9`, `9:16`, `1:1`, `4:3`, or `3:4`. |
| `duration` | integer | Conditional | Output seconds. Source range: `3` to `15`. |
| `seed` | integer | No | Random seed from `0` to `2147483647`. |
| `image` | string | Conditional | Single publicly accessible source image URL. |
| `images` | string[] | Conditional | `1` to `9` public reference image URLs. |
| `video` | string | Conditional | Source video URL for edit models. |
| `reference_image_urls` | string[] | No | Reference images for video editing. |
| `audio_setting` | string | No | `auto` or `origin`; default follows the upstream provider. |

## Text-To-Video Example

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse-720p",
    "prompt": "A cinematic wide shot of a white horse running across a misty grassland at sunrise, realistic motion, soft rim light.",
    "duration": 4,
    "aspect_ratio": "16:9",
    "size": "720p",
    "seed": 12345
  }'
```

## Image-To-Video Example

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse-1080p",
    "prompt": "Animate the subject naturally, with subtle camera push-in and realistic cloth movement.",
    "image": "https://example.com/source-frame.png",
    "duration": 6,
    "size": "1080p",
    "seed": 67890
  }'
```

## Multi-Reference Example

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse-1080p",
    "prompt": "character1 rides character2 through a futuristic city street, keep both identities consistent.",
    "images": [
      "https://example.com/character1.png",
      "https://example.com/character2.png"
    ],
    "duration": 8,
    "aspect_ratio": "9:16",
    "seed": 24680
  }'
```

## Video Editing Example

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse-edit-720p",
    "prompt": "Change the actor jacket into a red leather jacket while preserving motion, face identity, camera movement, and background.",
    "video": "https://example.com/source-video.mp4",
    "reference_image_urls": [
      "https://example.com/jacket-reference.png"
    ],
    "duration": 4,
    "size": "720p"
  }'
```

## Query Task Status

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

```json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video.generation.job",
  "model": "happy-horse-720p",
  "status": "completed",
  "progress": 100,
  "video_url": "https://example.com/output.mp4"
}
```

Poll every 2 to 5 seconds. Stop when `status` is `completed` or `failed`.

## Billing Notes

Happy-Horse billing depends on model tier, output resolution, output seconds, and operation type. Video editing can include source video handling. Use the current product pricing surface as the final price source.

## Common Errors

- Passing an edit model without `video`.
- Requesting a `duration` outside `3` to `15`.
- Sending private or expired media URLs.
- Passing more than `9` reference images.
- Using a 720p model while requesting a 1080p `size`.

## Related Pages

- [Video Generation Overview](/models/video/overview)
- [Seedance 2.0 Video Generation](/models/video/seedance-2-0)
- [Veo 3.1 Video Generation](/models/video/veo-3-1)

---

# Create Video Generation 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: Happy-Horse create video generation task endpoint.

This document explains Happy Horse video model call.

## Public Models

| Public Models | Capability | Resolution tier |
|---|---|---:|
| `happy-horse-720p` | text-to-video, image-to-video, reference-image-to-video | 720p |
| `happy-horse-1080p` | text-to-video, image-to-video, reference-image-to-video | 1080p |
| `happy-horse-edit-720p` | video editing | 720p |
| `happy-horse-edit-1080p` | video editing | 1080p |


Note:

- `duration` Happy Horse Public Models Yesrequired parameter,`3` `15`.
- video editingModel, `duration` billing detail andtask, editing video, up toprocessing `15`.
- generation model `aspect_ratio` text-to-videoandreference-image-to-video; image-to-video Input image.
- video editingModeldoes not support `aspect_ratio`.

## Endpoint

submit task:

```http
POST /v1/videos/generations
Authorization: Bearer <api-key>
Content-Type: application/json
```

Query Task:

```http
GET /v1/videos/generations/{task_id}
Authorization: Bearer <api-key>
```

## Parameter Reference

| Parameters | Type | Required | Model | Note |
|---|---|---:|---|---|
| `model` | string | Yes | all | Public model name |
| `prompt`| string | Yes | all | prompt, up to `2500` |
| `duration`| integer | Yes | all |`3` `15`; editingModel billing detail |
| `size`| string | No | all | Optional values: pass value: 720p Modelpass `720p`, 1080p Modelpass `1080p` |
| `seed`| integer | No | all | random seed, range `0` `2147483647` |
| `aspect_ratio`| string | No | text-to-video, reference-image-to-video | Optional values `16:9`, `9:16`, `1:1`, `4:3`, `3:4` |
| `image` | string | image-to-videoRequired | image-to-video | single source image URL |
| `images` | string[] | reference-image-to-videoRequired | reference-image-to-video | 1 9 reference image URL |
| `reference_image_urls`| string[] | reference-image-to-video | reference-image-to-video |`images` |

imageconstraints:

- image-to-video `image` supports `jpeg`, `jpg`, `png`, `bmp`, `webp`, imagesize `300px`, Ratio `1:2.5` `2.5:1`, `10MB`.
- reference-image-to-video `images` supports `jpeg`, `jpg`, `png`, `webp`, 1 9, `400px`, recommended 720p, `10MB`.
- reference-image-to-videoprompt use `character1` `character9` image.

### video editingParameters

| Parameters | Type | Required | Note |
|---|---|---:|---|
| `video` | string | Yes | video URL |
| `reference_image_urls` | string[] | No | reference image URL, up to 5 |
| `audio_setting`| string | No | Optional values `auto` or `origin`, default follows the upstream default `auto` |

 videoconstraints:

- supports `mp4`, `mov`, recommended H.264.
- video `3` `60`.
- `2160px`, `320px`.
- Ratio `1:2.5` `2.5:1`.
- `8fps`, file `100MB`.

reference imageconstraints:

- up to 5.
- supports `jpeg`, `jpg`, `png`, `webp`.
- size `300px`, Ratio `1:2.5` `2.5:1`.
- `10MB`.

## API Parameters and Examples

### 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 | Public model name |
| `prompt`| string | Yes | prompt | prompt, up to `2500` |
| `image` | string | Yes | reference URL | single source image URL, must be public URLimage URL |
| `images` | string | Yes | reference-image-to-video | 1 9 reference image URL |
| `aspect_ratio`| string | No | Ratio | Optional values `16:9`, `9:16`, `1:1`, `4:3`, `3:4` |
| `duration`| string | No | description |`3` `15`; editingModel billing detail |
| `seed`| string | Yes | random seed | random seed, range `0` `2147483647` |
| `video` | string | Yes | video URL | must be public URL URL |
| `audio_setting`| string | Yes | | Optional values `auto` or `origin`, default follows the upstream default `auto` |
| `size` | string | No | Example field | Appears in a request example; no separate field description is provided. |
| `reference_image_urls` | array | No | Example field | Appears in a request example; no separate field description is provided. |

### Request Examples

#### text-to-video

```json
{
  "model": "happy-horse-720p",
  "prompt": "A cinematic wide shot of a white horse running across a misty grassland at sunrise, realistic motion, soft rim light.",
  "duration": 4,
  "aspect_ratio": "16:9",
  "size": "720p",
  "seed": 12345
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "happy-horse-720p",
 "prompt": "A cinematic wide shot of a white horse running across a misty grassland at sunrise, realistic motion, soft rim light.",
 "duration": 4,
 "aspect_ratio": "16:9",
 "size": "720p",
 "seed": 12345}'
```
#### image-to-video

```json
{
  "model": "happy-horse-1080p",
  "prompt": "Animate the subject naturally, with subtle camera push-in and realistic cloth movement.",
  "image": "https://example.com/source-frame.png",
  "duration": 6,
  "size": "1080p",
  "seed": 67890
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "happy-horse-1080p",
 "prompt": "Animate the subject naturally, with subtle camera push-in and realistic cloth movement.",
 "image": "https://example.com/source-frame.png",
 "duration": 6,
 "size": "1080p",
 "seed": 67890}'
```
#### reference-image-to-video

```json
{
  "model": "happy-horse-1080p",
  "prompt": "character1 rides character2 through a futuristic city street, keep both identities consistent.",
  "images": [
    "https://example.com/character1.png",
    "https://example.com/character2.png"
  ],
  "duration": 8,
  "aspect_ratio": "9:16",
  "seed": 24680
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "happy-horse-1080p",
 "prompt": "character1 rides character2 through a futuristic city street, keep both identities consistent.",
 "images": ["https://example.com/character1.png",
 "https://example.com/character2.png"],
 "duration": 8,
 "aspect_ratio": "9:16",
 "seed": 24680}'
```
#### video editing

```json
{
  "model": "happy-horse-edit-720p",
  "prompt": "Change the actor jacket into a red leather jacket while preserving motion, face identity, camera movement, and background.",
  "video": "https://example.com/source-video.mp4",
  "reference_image_urls": [
    "https://example.com/jacket-reference.png"
  ],
  "duration": 4,
  "size": "720p",
  "audio_setting": "origin",
  "seed": 13579
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "happy-horse-edit-720p",
 "prompt": "Change the actor jacket into a red leather jacket while preserving motion, face identity, camera movement, and background.",
 "video": "https://example.com/source-video.mp4",
 "reference_image_urls": ["https://example.com/jacket-reference.png"],
 "duration": 4,
 "size": "720p",
 "audio_setting": "origin",
 "seed": 13579}'
```
### 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

#### Success

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "happy-horse-edit-720p",
  "status": "queued",
  "progress": 0,
  "created_at": 1777355454
}
```

---

# Query Video Generation Task

Locale: en
URL: https://docs.uniall.ai/models/video/happy-horse/query-task
Source: site-docs/models/video/happy-horse/query-task.md
Description: Happy-Horse query video generation task endpoint.

## Endpoint


```http
GET /v1/videos/{task_id}
```
## Header Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No | | Bearer &#123;your_token&#125; |
## Path Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `task_id` | string | Yes | | |
## Response Fields

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `id` | string | Yes | task ID | |
| `model` | string | Yes | Model name | |
| `object` | string | Yes | Task type | |
| `prompt` | string | Yes | prompt | |
| `status` | string | Yes | Status | queued:, in_progress: generation, completed: completed, failed: Failed |
| `duration` | string | Yes | task | |
| `metadata` | string | Yes | // | |
| `progress` | string | Yes | | |
| `video_url` | string | Yes | video URL | |
| `created_at` | string | Yes | Created time | |
| `thumbnail_url` | string | Yes | | |

## Response Examples

### Example 1

```json
{
  "id": "task_xxxxxxxxxxxxxxx",
  "error": null,
  "model": "happy-horse-edit-720p",
  "object": "video.generation.job",
  "result": {
    "outputs": [
      "https://xxxxxxxxxxx.cn/xxxxxxxx.mp4"
    ],
    "video_url": "https://xxxxxxxxxxx.cn/xxxxxxxx.mp4"
  },
  "status": "completed",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxx",
  "progress": 100,
  "video_url": "https://xxxxxxxxxxx.cn/xxxxxxxx.mp4",
  "created_at": 1777355454,
  "raw_status": "COMPLETED"
}
```

---

# Kling Video Generation

Locale: en
URL: https://docs.uniall.ai/models/video/kling
Source: site-docs/models/video/kling.md
Description: Generate videos with Kling v3 models through UniAll video APIs.

Kling supports text-to-video, image-to-video, first-last-frame generation, and advanced prompt controls. Select the public model ID for standard or pro quality and silent or audio output.

## Supported Models

| Model | Tier | Audio |
| --- | --- | --- |
| `kling-v3-std-silent` | Standard | Silent output. |
| `kling-v3-std-audio` | Standard | Audio output. |
| `kling-v3-pro-silent` | Pro | Silent output. |
| `kling-v3-pro-audio` | Pro | Audio output. |

## 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 | One of the Kling v3 model IDs. |
| `prompt` | string | Yes | Main prompt. In image mode, do not pass it together with `extra_body.multi_prompt`. |
| `image` | string | Conditional | Reference image URL. If `last_image` is present, this is the first frame. |
| `last_image` | string | Conditional | Last-frame image URL. |
| `aspect_ratio` | string | No | `16:9`, `9:16`, or `1:1`; image-to-video may not guarantee this ratio. |
| `duration` | integer | No | Source range: `3` to `15` seconds. |
| `extra_body.negative_prompt` | string | No | Content to avoid. |
| `extra_body.cfg_scale` | number | No | Prompt adherence strength. Higher values generally follow the prompt more closely. |
| `extra_body.multi_prompt` | array | No | Multi-shot prompt list for advanced image mode. |
| `extra_body.element_list` | array | No | Element references. |
| `extra_body.shot_type` | string | No | `customize` or `intelligent`. |

## Text-To-Video Example

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-std-silent",
    "prompt": "A wide cinematic shot of a traveler walking through dusty desert ruins, cloak moving in the wind, slow pullback, natural motion.",
    "aspect_ratio": "16:9",
    "duration": 5,
    "extra_body": {
      "cfg_scale": 0.5,
      "shot_type": "customize",
      "negative_prompt": "blur, low detail"
    }
  }'
```

## Image-To-Video Example

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-pro-audio",
    "prompt": "The person writes naturally in a notebook, subtle hand detail, small thoughtful pauses, soft classroom depth of field.",
    "image": "https://example.com/start-frame.png",
    "aspect_ratio": "16:9",
    "duration": 6,
    "extra_body": {
      "cfg_scale": 0.6,
      "shot_type": "intelligent",
      "negative_prompt": "artifacts, distortion"
    }
  }'
```

## First-Last-Frame Example

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-pro-silent",
    "prompt": "The portrait subject slowly turns toward the camera while keeping identity stable and motion natural.",
    "image": "https://example.com/first-frame.png",
    "last_image": "https://example.com/last-frame.png",
    "duration": 8
  }'
```

## Query Task Status

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

```json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video.generation.job",
  "model": "kling-v3-pro-audio",
  "status": "completed",
  "progress": 100,
  "video_url": "https://example.com/output.mp4"
}
```

## Billing Notes

Kling billing depends on model tier, audio mode, output seconds, and generation mode. The task settlement record and current product pricing are the final billing source.

## Common Errors

- Passing both `prompt` and `extra_body.multi_prompt` in image mode.
- Requesting a duration outside `3` to `15`.
- Assuming `aspect_ratio` is guaranteed in image-to-video mode.
- Using an audio model when silent output is expected.
- Passing private media URLs.

## Related Pages

- [Video Generation Overview](/models/video/overview)
- [Veo 3.1 Video Generation](/models/video/veo-3-1)
- [Digital Human Video](/models/avatar/digital-human)

---

# Create Video Task

Locale: en
URL: https://docs.uniall.ai/models/video/kling/create-task
Source: site-docs/models/video/kling/create-task.md
Description: Kling create video task endpoint.

## 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 | kling-v3-std-silent, kling-v3-std-audio, kling-v3-pro-silent, kling-v3-pro-audio |
| `prompt`| string | Yes | prompt | mode and `extra_body.multi_prompt` pass both |
| `image` | string | Yes | reference URL | pass for image-to-video, pass/text-to-video (: last_image, Yes) |
| `last_image` | string | Yes | URL | |
| `aspect_ratio`| string | Yes | Ratio | allowed values:`16:9`, `9:16`, `1:1`, (: image-to-videomode, video) |
| `duration`| string | Yes | video () | allowed values:`3` `15` |
| `extra_body` | object | Yes | | |

## Request Examples

### text-to-video

```json
{
  "model": "kling-v3-std-silent",
  "prompt": " camera, Yes, camera, action. ",
  "aspect_ratio": "16:9",
  "duration": 5,
  "extra_body": {
    "cfg_scale": 0.5,
    "shot_type": "customize",
    "negative_prompt": "blur, "
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "kling-v3-std-silent",
 "prompt": " camera, Yes, camera, action. ",
 "aspect_ratio": "16:9",
 "duration": 5,
 "extra_body": {"cfg_scale": 0.5,
 "shot_type": "customize",
 "negative_prompt": "blur, "}}'
```
### image-to-video

```json
{
  "model": "kling-v3-pro-audio",
  "prompt": ", action, and. ",
  "image": "https://example.com/start-frame.png",
  "aspect_ratio": "16:9",
  "duration": 6,
  "extra_body": {
    "cfg_scale": 0.6,
    "shot_type": "intelligent",
    "negative_prompt": "artifacts, "
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "kling-v3-pro-audio",
 "prompt": ", action, and. ",
 "image": "https://example.com/start-frame.png",
 "aspect_ratio": "16:9",
 "duration": 6,
 "extra_body": {"cfg_scale": 0.6,
 "shot_type": "intelligent",
 "negative_prompt": "artifacts, "}}'
```
### first-and-last-frameimage-to-video

```json
{
  "model": "kling-v3-pro-silent",
  "prompt": " camera, keep identity stable, natural motion. ",
  "image": "https://example.com/first-frame.png",
  "last_image": "https://example.com/last-frame.png",
  "duration": 8,
  "extra_body": {
    "cfg_scale": 0.5,
    "shot_type": "customize"
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "kling-v3-pro-silent",
 "prompt": " camera, keep identity stable, natural motion. ",
 "image": "https://example.com/first-frame.png",
 "last_image": "https://example.com/last-frame.png",
 "duration": 8,
 "extra_body": {"cfg_scale": 0.5,
 "shot_type": "customize"}}'
```
### Use `multi_prompt` image-to-video

```json
{
  "model": "kling-v3-std-audio",
  "image": "https://example.com/source-image.png",
  "duration": 10,
  "extra_body": {
    "multi_prompt": [
      {
        "prompt": "camera. "
      },
      {
        "prompt": " camera. "
      }
    ],
    "shot_type": "customize"
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "kling-v3-std-audio",
 "image": "https://example.com/source-image.png",
 "duration": 10,
 "extra_body": {"multi_prompt": [{"prompt": "camera. "},
 {"prompt": " camera. "}],
 "shot_type": "customize"}}'
```
## Response Fields

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


## Response Examples

### Example 1

```json
{}
```

---

# Query Video Task

Locale: en
URL: https://docs.uniall.ai/models/video/kling/query-task
Source: site-docs/models/video/kling/query-task.md
Description: Kling query video task endpoint.

## Endpoint


```http
GET /v1/videos/{task_id}
```
## Header Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No | | Bearer &#123;your_token&#125; |
## Path Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `task_id` | string | Yes | | |
## Response Fields

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


## Response Examples

### Example 1

```json
{
  "id": "task_xxxxxxxxxx",
  "model": "kling-v3-std-silent",
  "object": "video",
  "status": "completed",
  "seconds": "8",
  "task_id": "5c9e83c9-1044-46cd-8cff-b2c4cb90efba",
  "progress": 100,
  "video_url": "https://xxxxxx/r/xxxxxx.mp4",
  "created_at": 1774102861000
}
```

---

# Video Generation Overview

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

Video generation docs cover only the selected video pages from the source menu.

## Included Pages

- [Happy-Horse Video Generation](/models/video/happy-horse)
- [Seedance 2.0 Video Generation](/models/video/seedance-2-0)
- [Grok Imagine Video Generation](/models/video/grok-imagine)
- [Veo 3.1 Video Generation](/models/video/veo-3-1)
- [Vidu Video Generation](/models/video/vidu)
- [Kling Video Generation](/models/video/kling)
- [Wan 2.6 Video Generation](/models/video/wan-2-6)
- [Sora 2 Video Generation](/models/video/sora-2)

## Integration Guidance

Video APIs are usually asynchronous. Clients should submit a task, poll for status, and read the result URL or download the result content after completion.

---

# Seedance 2.0 Video Generation

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-last-frame generation, multi-reference generation, and compatible edit or extension modes. New integrations should use the new create task page, not the deprecated old task interface.

## Supported Models

| Model | Notes |
| --- | --- |
| `seedance2.0-480p` | Standard tier. |
| `seedance2.0-720p` | Standard tier. |
| `seedance2.0-1080p` | Standard tier. |
| `seedance2.0-4k` | 4K tier when enabled. |
| `seedance2.0-fast-480p` | Fast tier. |
| `seedance2.0-fast-720p` | Fast tier. |
| `seedance2.0-mini-480p` | Mini tier. |
| `seedance2.0-mini-720p` | Mini tier. |

## Endpoint

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

Some compatibility clients may see `/v1/videos/generations`, but the selected source page uses `/v1/video/generations` for task creation.

## Authentication

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

## Request Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | Seedance 2.0 model ID. |
| `prompt` | string | Yes | Prompt. Prompt-only requests are text-to-video. |
| `duration` | integer/string | Conditional | Source range: any value from `5` to `15`. |
| `aspect_ratio` | string | No | `9:16`, `1:1`, or `16:9`. |
| `image` | string | Conditional | Single source image for image-to-video. |
| `last_image` | string | Conditional | Last frame image; use with `image`. |
| `images` | string[] | Conditional | Reference image URLs for all-purpose reference mode. Maximum `9`. |
| `videos` | string[] | Conditional | Reference video URLs. Maximum `3`; each `2` to `15` seconds; total duration no more than `15` seconds. |
| `audios` | string[] | No | Reference audio URLs. |
| `extra_body.generate_audio` | boolean | No | Whether to generate video with audio. |
| `extra_body.seed` | integer | No | Random seed. |
| `extra_body.watermark` | boolean/string | No | Watermark switch. |
| `extra_body.camera_fixed` | boolean/string | No | Fixed camera switch. |
| `extra_body.return_last_frame` | boolean/string | No | Whether to return the last frame. |
| `extra_body.operation` | string | Compatibility only | `reference_to_video`, `edit_video`, `extend_video`, or `first_last_frame`; ignored by content-array style clients. |

## Request Example

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0-720p",
    "prompt": "A clean commercial product video with slow camera movement, soft reflections, and realistic lighting.",
    "duration": 8,
    "aspect_ratio": "16:9",
    "extra_body": {
      "generate_audio": false,
      "seed": 42,
      "watermark": false
    }
  }'
```

## Multi-Reference Example

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0-fast-720p",
    "prompt": "Create a fast fashion lookbook clip while preserving the product identity.",
    "images": [
      "https://example.com/model.png",
      "https://example.com/outfit.png"
    ],
    "duration": 6,
    "aspect_ratio": "9:16",
    "extra_body": {
      "generate_audio": true,
      "camera_fixed": false
    }
  }'
```

## Query Task Status

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

```json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video.generation.job",
  "model": "seedance2.0-720p",
  "status": "completed",
  "progress": 100,
  "video_url": "https://example.com/output.mp4"
}
```

## Billing Notes

Seedance billing depends on the selected model tier, output resolution, duration, and whether reference media or audio generation is used. Final billing should follow the platform settlement record.

## Common Errors

- Using the deprecated 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 `5` to `15`.
- Passing incompatible operation hints together with the new input format.

## Related Pages

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

---

# Create Video Task (New)

Locale: en
URL: https://docs.uniall.ai/models/video/seedance-2-0/create-task
Source: site-docs/models/video/seedance-2-0/create-task.md
Description: Seedance 2.0 create video task endpoint.

## 1. Public Models

- `seedance2.0-480p`
- `seedance2.0-720p`
- `seedance2.0-1080p`
- `seedance2.0-4k`
- `seedance2.0-fast-480p`
- `seedance2.0-fast-720p`
- `seedance2.0-mini-480p`
- `seedance2.0-mini-720p`

Current unified public endpoint:

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

## 2. Design Principles

### 2.1 Prefer Volcano Native Format

If you already use the Volcano-native `content[]`, the platform prioritizes `content[]` processing.

This means:

- `content[]` is the primary protocol
- `type`/`role` is the primary semantic meaning
- **If you pass `content[]`, the platform ignores self-wrapped `extra_body.operation`**

### 2.2 Legacy Fields Are Compatibility Only

The following legacy fields remain compatible:

- `prompt`
- `image`
- `images`
- `video`
- `videos`
- `audios`
- `last_image`

These legacy fields are compatibility fields only and are no longer the recommended integration pattern.

### 2.3 `extra_body.operation` reserved compatibility

Only when you**do not pass `content[]`**, and use the legacy-field compatibility format, should you use:

- `reference_to_video`
- `edit_video`
- `extend_video`
- `first_last_frame`

If you already pass `content[]`:

- even if you also pass `extra_body.operation`
- the platform ignores it

## 3. Models and Allowed Values

| Model | Type | resolution | `duration`|`aspect_ratio` |
|---|---|---|---|---|
| `seedance2.0-480p`| standard |`480p`|`4` `15` integer |`auto`/`21:9`/`16:9`/`4:3`/`1:1`/`3:4`/`9:16`|
| `seedance2.0-720p`| standard |`720p`|`4` `15` integer |`auto`/`21:9`/`16:9`/`4:3`/`1:1`/`3:4`/`9:16`|
| `seedance2.0-1080p`| standard |`1080p`|`4` `15` integer |`auto`/`21:9`/`16:9`/`4:3`/`1:1`/`3:4`/`9:16`|
| `seedance2.0-fast-480p`| Fast |`480p`|`4` `15` integer |`auto`/`21:9`/`16:9`/`4:3`/`1:1`/`3:4`/`9:16`|
| `seedance2.0-fast-720p`| Fast |`720p`|`4` `15` integer |`auto`/`21:9`/`16:9`/`4:3`/`1:1`/`3:4`/`9:16`|

Additional notes:

- Resolution is locked by the selected model.
- Do not use `size` to change `480p` model to `720p`.
- If you need to pass `size`:
 - `seedance2.0-480p`/`seedance2.0-fast-480p` only pass `480p`
 - `seedance2.0-720p`/`seedance2.0-fast-720p` only pass `720p`
 - `seedance2.0-1080p`/ only pass `1080p`
## 4. Top-level Parameters

### 4.1 Required Parameters

| Parameters | Type | Required | allowed values | Note |
|---|---|---|---|---|
| `model` | string | Yes | 4 one of the public models | Public model name |
| `duration`| integer | Yes |`4` `15` integer | video duration |

### 4.2 Primary Parameters

| Parameters | Type | Required | allowed values | Note |
|---|---|---|---|---|
| `content` | array | Recommended | see below | Volcano-native input |
| `aspect_ratio`| string | No |`auto`/`21:9`/`16:9`/`4:3`/`1:1`/`3:4`/`9:16` | aspect ratio |
| `prompt`| string | No | any non-empty string | If `new-api`, recommended to pass both |

### 4.3 Compatibility Parameters

| Parameters | Type | Required | allowed values | Note |
|---|---|---|---|---|
| `image` | string / object | No | single image URL | legacy-field compatibility |
| `images`| array | No |`1` `9` image URLs | legacy-field compatibility |
| `video` | string | No | single video URL | legacy-field compatibility |
| `videos`| array | No |`1` `3` video URLs | legacy-field compatibility |
| `audios`| array | No |`1` `3` audio URLs | legacy-field compatibility |
| `last_image` | string / object | No | single image URL | legacy-field compatibility |

### 4.4 `extra_body` Parameters

| Parameters | Type | Required | allowed values | Note |
|---|---|---|---|---|
| `extra_body.generate_audio`| boolean | No |`true`/`false` | whether to generate audio |
| `extra_body.seed` | integer | No | any integer | random seed |
| `extra_body.watermark`| boolean | No |`true`/`false` | whether to add a watermark |
| `extra_body.camera_fixed`| boolean | No |`true`/`false` | whether to keep the camera fixed |
| `extra_body.service_tier` | string | No | the platform does not enumerate fixed values currently | passed through to upstream |
| `extra_body.execution_expires_after` | integer | No | positive integer | passed through to upstream |
| `extra_body.draft`| boolean | No |`true`/`false` | draft mode |
| `extra_body.return_last_frame`| boolean | No |`true`/`false` | whether to return the last frame |
| `extra_body.frames` | integer | No | positive integer | frame count |
| `extra_body.operation`| string | compatibility layer only |`reference_to_video`/`edit_video`/`extend_video`/`first_last_frame`| **use only in legacy-field mode;`content[]` mode ignores it** |

## 5. `content[]` Structure

### 5.1 Text Item

```json
{
  "type": "text",
  "text": "A futuristic city with advanced transportation"
}
```

Rules:

- `type` must be `text`
- `text` must be string
- 1 Text Item

### 5.2 Image Item

```json
{
  "type": "image_url",
  "url": "https://example.com/ref.png",
  "role": "reference_image"
}
```

image `role` allowed values:

- `image`
- `reference_image`
- `first_frame`
- `last_frame`

### 5.3 Video Item

```json
{
  "type": "video_url",
  "url": "https://example.com/ref.mp4",
  "role": "reference_video"
}
```

video `role` allowed values:

- `reference_video`
- `source_video`

### 5.4 Audio Item

```json
{
  "type": "audio_url",
  "url": "https://example.com/ref.mp3",
  "role": "reference_audio"
}
```

audio `role` allowed values:

- `reference_audio`

## 6. `content[]` mode Capability

 Yes:

- userpass `content[]`
- the platform `content[]` `type + role` Capability
- **do not pass `extra_body.operation`**
- pass, ignores

### 6.1 text-to-video

```json
{
  "model": "seedance2.0-720p",
  "content": [
    {
      "type": "text",
      "text": ", slow camera push-in"
    }
  ],
  "duration": 5,
  "aspect_ratio": "16:9"
}
```

### 6.2 single-image-to-video

```json
{
  "model": "seedance2.0-fast-720p",
  "content": [
    {
      "type": "text",
      "text": ", camera, style"
    },
    {
      "type": "image_url",
      "url": "https://example.com/product.png",
      "role": "image"
    }
  ],
  "duration": 5,
  "aspect_ratio": "16:9",
  "extra_body": {
    "generate_audio": false,
    "watermark": false
  }
}
```

### 6.3 first-and-last-frame

```json
{
  "model": "seedance2.0-720p",
  "content": [
    {
      "type": "text",
      "text": ", subject "
    },
    {
      "type": "image_url",
      "url": "https://example.com/start.png",
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "url": "https://example.com/end.png",
      "role": "last_frame"
    }
  ],
  "duration": 6,
  "aspect_ratio": "16:9"
}
```

### 6.4 image reference mode

```json
{
  "model": "seedance2.0-720p",
  "content": [
    {
      "type": "text",
      "text": ", generate a video"
    },
    {
      "type": "image_url",
      "url": "https://example.com/ref-1.png",
      "role": "reference_image"
    },
    {
      "type": "image_url",
      "url": "https://example.com/ref-2.png",
      "role": "reference_image"
    }
  ],
  "duration": 8,
  "aspect_ratio": "9:16"
}
```

### 6.5 omni-reference mode

```json
{
  "model": "seedance2.0-720p",
  "content": [
    {
      "type": "text",
      "text": ", referenceactionandaudio, generate a video"
    },
    {
      "type": "image_url",
      "url": "https://example.com/product.png",
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "url": "https://example.com/motion-guide.mp4",
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "url": "https://example.com/music-guide.mp3",
      "role": "reference_audio"
    }
  ],
  "duration": 10,
  "aspect_ratio": "16:9",
  "extra_body": {
    "generate_audio": true,
    "seed": 88,
    "watermark": false
  }
}
```

### 6.6 video editing

```json
{
  "model": "seedance2.0-720p",
  "content": [
    {
      "type": "text",
      "text": "to change videointo style"
    },
    {
      "type": "video_url",
      "url": "https://example.com/source.mp4",
      "role": "source_video"
    }
  ],
  "duration": 5,
  "aspect_ratio": "16:9",
  "extra_body": {
    "watermark": false
  }
}
```

### 6.7 video extension

```json
{
  "model": "seedance2.0-720p",
  "content": [
    {
      "type": "text",
      "text": " camera andscenariostyle, subject "
    },
    {
      "type": "video_url",
      "url": "https://example.com/source.mp4",
      "role": "source_video"
    }
  ],
  "duration": 5,
  "aspect_ratio": "16:9",
  "extra_body": {
    "watermark": false
  }
}
```

## 7. legacy-field compatibility format

 or compatibilityuse.

### 7.1 compatibility

```json
{
  "model": "seedance2.0-fast-480p",
  "prompt": " ",
  "image": "https://example.com/product.png",
  "duration": 5,
  "aspect_ratio": "16:9"
}
```

### 7.2 first-and-last-framecompatibility

```json
{
  "model": "seedance2.0-720p",
  "prompt": " ",
  "image": "https://example.com/start.png",
  "last_image": "https://example.com/end.png",
  "duration": 6,
  "aspect_ratio": "16:9",
  "extra_body": {
    "operation": "first_last_frame"
  }
}
```

### 7.3 referencecompatibility

```json
{
  "model": "seedance2.0-720p",
  "prompt": "generate a referenceactionandaudio video",
  "images": [
    "https://example.com/ref-1.png"
  ],
  "videos": [
    "https://example.com/ref.mp4"
  ],
  "audios": [
    "https://example.com/ref.mp3"
  ],
  "duration": 8,
  "aspect_ratio": "16:9",
  "extra_body": {
    "operation": "reference_to_video"
  }
}
```

### 7.4 Fieldvideo editing / compatibility

```json
{
  "model": "seedance2.0-720p",
  "prompt": "to change videointo style",
  "video": "https://example.com/source.mp4",
  "duration": 5,
  "aspect_ratio": "16:9",
  "extra_body": {
    "operation": "edit_video"
  }
}
```

## 8. this site new-apicall

 recommended to pass both `prompt` and `content[0].text`.:

- openaistyle, `prompt` FieldRequired, No Volcano service

recommendedcompatibility:

```json
{
  "model": "seedance2.0-fast-480p",
  "prompt": "A futuristic city with advanced transportation",
  "content": [
    {
      "type": "text",
      "text": "A futuristic city with advanced transportation"
    }
  ],
  "duration": 5,
  "aspect_ratio": "16:9",
  "extra_body": {
    "generate_audio": false,
    "watermark": false
  }
}
```

## 9. Common Errors

### Error 1: `new-api` only pass `content[]`, pass `prompt`:

- `prompt is required`:

- `prompt` and `content[0].text` pass both

### Error 2: `content[]` `role`

image `role`:

- `image`
- `reference_image`
- `first_frame`
- `last_frame`

video `role`:

- `reference_video`
- `source_video`

audio `role`:

- `reference_audio`

### Error 3: legacy-field compatibilitymode pass `operation`

Note:

- Field
- the platformrequires:

- `video` compatibilitymode `edit_video` or `extend_video`
- `videos / audios` compatibilitymode `reference_to_video`

### Error 4: resolution

Note:

- Modelresolution Public model name:

- `seedance2.0-fast-480p` into `720p`
- `seedance2.0-720p` into `480p`

## 10. responsesNote

submit return async taskobject,:

```json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video.generation.job",
  "model": "seedance2.0-720p",
  "status": "queued",
  "raw_status": "PENDING",
  "progress": 0,
  "created_at": 1773980459,
  "video_url": null
}
```

 poll:

- `GET /v1/videos/generations/{task_id}`

 Status:

- `completed`
- or `failed`

## 11. recommended:

- **If `content[]`, Volcanonativestyle, pass `extra_body.operation`**
- **If legacy-field compatibility format, pass `extra_body.operation`**
- **If `new-api`, recommended to pass both `prompt` and `content[0].text`**

## API Parameters and Examples

### 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 | |
| `prompt`| string | Yes | prompt | only `prompt` -&gt; text-to-video |
| `image` | string | Yes | single source image | image-to-video |
| `last_image` | string | Yes | | first-and-last-frameandimage use |
| `images` | string | Yes | reference URL array | reference, 'omni-reference mode', imageup to9 |
| `audios` | string | Yes | reference audio URL array | omni-reference mode, up to 3, each 2~15s, &lt;= 15s |
| `videos` | string | Yes | reference video URL array | omni-reference mode, up to 3, each 2~15s, &lt;= 15s |
| `duration` | string | Yes | duration | 5 15 value |
| `aspect_ratio`| string | Yes | Ratio |`9:16`, `1:1`, `16:9` |
| `extra_body` | object | No | | |

### Request Examples

#### Example

```json
{
  "model": "string",
  "prompt": "string",
  "image": "string",
  "last_image": "string",
  "images": "string",
  "audios": "string",
  "videos": "string",
  "duration": "string",
  "aspect_ratio": "string",
  "extra_body": {
    "generate_audio": true,
    "seed": "string",
    "watermark": "string",
    "camera_fixed": "string",
    "service_tier": "string",
    "execution_expires_after": "string",
    "draft": "string",
    "return_last_frame": "string",
    "frames": "string",
    "operation": "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",
 "last_image": "string",
 "images": "string",
 "audios": "string",
 "videos": "string",
 "duration": "string",
 "aspect_ratio": "string",
 "extra_body": {"generate_audio": true,
 "seed": "string",
 "watermark": "string",
 "camera_fixed": "string",
 "service_tier": "string",
 "execution_expires_after": "string",
 "draft": "string",
 "return_last_frame": "string",
 "frames": "string",
 "operation": "string"}}'
```
### Response Fields

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


### Response Examples

#### Example 1

```json
{
  "id": "task_xxx",
  "error": null,
  "model": "seedance2.0-720p",
  "object": "video.generation.job",
  "result": {
    "outputs": [
      "https://xxx.aijisu.cn/video/xxxx.mp4"
    ],
    "video_url": "https://xxx.aijisu.cn/video/xxx.mp4"
  },
  "status": "completed",
  "task_id": "task_xxxxx",
  "progress": 100,
  "video_url": "https://xxx.aijisu.cn/video/xxx.mp4",
  "created_at": 1774405050,
  "raw_status": "COMPLETED"
}
```

---

# Create Video Task (Old, Deprecated)

Locale: en
URL: https://docs.uniall.ai/models/video/seedance-2-0/legacy-create-task
Source: site-docs/models/video/seedance-2-0/legacy-create-task.md
Description: Deprecated Seedance 2.0 create video task endpoint.

## Overview

| input form | actual capability |
|---|---|
| only `prompt`|`text-to-video` |
| only pass `image`|`image-to-video` |
| pass both `image` and `last_image`|`first-and-last-frame` |
| pass `images`/`videos`/`audios` any one or combination |`omni-reference mode` |

## 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 | jisudance2.0-480p, jisudance2.0-720p, jisudance2.0-fast-480p, jisudance2.0-fast-720p |
| `prompt`| string | Yes | prompt | only `prompt` -&gt; text-to-video |
| `image` | string | Yes | single source image | image-to-video |
| `last_image` | string | Yes | | first-and-last-frameandimage use |
| `images` | string | Yes | reference URL array | reference, 'omni-reference mode', imageup to9 |
| `audios` | string | Yes | reference audio URL array | omni-reference mode, up to 3, each 2~15s, &lt;= 15s |
| `videos` | string | Yes | reference video URL array | omni-reference mode, up to 3, each 2~15s, &lt;= 15s |
| `duration` | string | Yes | duration | 5 15 value |
| `aspect_ratio`| string | Yes | Ratio |`9:16`, `1:1`, `16:9` |
| `extra_body` | object | No | | |

## Request Examples

### test

```json
{
  "model": "jisudance2.0-480p",
  "prompt": " ",
  "duration": 5,
  "aspect_ratio": "9:16"
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "jisudance2.0-480p",
 "prompt": " ",
 "duration": 5,
 "aspect_ratio": "9:16"}'
```
## Response Fields

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


## Response Examples

### Example 1

```json
{
  "id": "task_xxx",
  "error": null,
  "model": "jisudance2.0-720p",
  "object": "video.generation.job",
  "result": {
    "outputs": [
      "https://xxx.aijisu.cn/video/xxxx.mp4"
    ],
    "video_url": "https://xxx.aijisu.cn/video/xxx.mp4"
  },
  "status": "completed",
  "task_id": "task_xxxxx",
  "progress": 100,
  "video_url": "https://xxx.aijisu.cn/video/xxx.mp4",
  "created_at": 1774405050,
  "raw_status": "COMPLETED"
}
```

---

# Query Video Task

Locale: en
URL: https://docs.uniall.ai/models/video/seedance-2-0/query-task
Source: site-docs/models/video/seedance-2-0/query-task.md
Description: Seedance 2.0 query video task endpoint.

## Endpoint


```http
GET /v1/videos/{task_id}
```
## Header Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No | | Bearer &#123;your_token&#125; |
## Path Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `task_id` | string | Yes | | |
## Response Fields

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


## Response Examples

### Example 1

```json
{
  "id": "task_xxxxxxxxxx",
  "model": "jisudance-2.0-720p",
  "object": "video",
  "status": "completed",
  "seconds": "8",
  "task_id": "5c9e83c9-1044-46cd-8cff-b2c4cb90efba",
  "progress": 100,
  "video_url": "https://xxxxxx/r/xxxxxx.mp4",
  "created_at": 1774102861000
}
```

---

# Sora 2 Video Generation

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.

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

## Query Task Status

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

```json
{
  "id": "gen_xxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "sora2-portrait-12s",
  "status": "completed",
  "progress": 100,
  "video_url": "https://example.com/output.mp4",
  "seconds": "12"
}
```

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

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

---

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

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

---

# Query Video Generation Task

Locale: en
URL: https://docs.uniall.ai/models/video/sora-2/query-task
Source: site-docs/models/video/sora-2/query-task.md
Description: Sora 2 query video generation task endpoint.

## Endpoint


```http
GET /v1/videos/{task_id}
```
## Header Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No | | Bearer &#123;your_token&#125; |
## Path Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `task_id` | string | Yes | | |
## Response Fields

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `id` | string | Yes | task ID | |
| `model` | string | Yes | Model name | |
| `object` | string | Yes | Task type | |
| `prompt` | string | Yes | prompt | |
| `status` | string | Yes | Status | queued:, in_progress: generation, completed: completed, failed: Failed |
| `duration` | string | Yes | task | |
| `metadata` | string | Yes | // | |
| `progress` | string | Yes | | |
| `video_url` | string | Yes | video URL | |
| `created_at` | string | Yes | Created time | |
| `thumbnail_url` | string | Yes | | |

## Response Examples

### Example 1

```json
{
  "id": "gen_xxxxxxx",
  "model": "sora2",
  "object": "video.generation.job",
  "prompt": "xxxxxxxxxxxxxx",
  "status": "completed",
  "duration": 89,
  "metadata": {
    "total_time": 89.550817778,
    "predict_time": 89.537048777
  },
  "progress": 100,
  "video_url": "https://xx.xxxxxx.cn/xxxx/xxxxxxxxxxxxxxxxxxxxxxxx.mp4",
  "created_at": 1770405484,
  "thumbnail_url": null
}
```

---

# Veo 3.1 Video Generation

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.

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

## Query Task Status

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

```json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video.generation.job",
  "model": "veo3.1-video-1080p",
  "status": "completed",
  "progress": 100,
  "video_url": "https://example.com/output.mp4"
}
```

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

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

---

# Query Video Task

Locale: en
URL: https://docs.uniall.ai/models/video/veo-3-1/query-task
Source: site-docs/models/video/veo-3-1/query-task.md
Description: Veo 3.1 query video task endpoint.

## Endpoint


```http
GET /v1/videos/{task_id}
```
## Header Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No | | Bearer &#123;your_token&#125; |
## Path Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `task_id` | string | Yes | | |
## Response Fields

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


## Response Examples

### Example 1

```json
{
  "id": "task_xxxxxxxxxx",
  "model": "viduq3p-1080p",
  "object": "video",
  "status": "completed",
  "seconds": "8",
  "task_id": "5c9e83c9-1044-46cd-8cff-b2c4cb90efba",
  "progress": 100,
  "video_url": "https://xxxxxx/r/xxxxxx.mp4",
  "created_at": 1774102861000
}
```

---

# Vidu Video Generation

Locale: en
URL: https://docs.uniall.ai/models/video/vidu
Source: site-docs/models/video/vidu.md
Description: Vidu source documentation.

video generationusercall

Updated: 2026-06-03, this site Vidu Q3 Pro / Q3 Turbo video model call. user requires using this site stable model and video task endpoint, do not upstream or Field.

## 1. Model

| Model | | text-to-video | single-image-to-video | first-and-last-frame | multiple reference images |
| --- | --- | --- | --- | --- | --- |
| `viduq3p-540p`| Q3 Pro | supports | supports | supports, use `image`+`last_image`| supports, use `reference_image_urls`, up to 4 |
| `viduq3p-720p`| Q3 Pro | supports | supports | supports, use `image`+`last_image`| supports, use `reference_image_urls`, up to 4 |
| `viduq3p-1080p`| Q3 Pro | supports | supports | supports, use `image`+`last_image`| supports, use `reference_image_urls`, up to 4 |
| `viduq3t-540p`| Q3 Turbo | supports | supports | supports, use `image`+`last_image`| supports, use `reference_image_urls`, up to 4 |
| `viduq3t-720p`| Q3 Turbo | supports | supports | supports, use `image`+`last_image`| supports, use `reference_image_urls`, up to 4 |
| `viduq3t-1080p`| Q3 Turbo | supports | supports | supports, use `image`+`last_image`| supports, use `reference_image_urls`, up to 4 |

Note:

- Modellist 6 Model.
- Create Task use Model.
- Q3 Turbo or use; multiple reference images use Q3 Pro.

## 2. Endpoint

### 2.1 Create Video Task

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

request headers:

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

### 2.2 Query Video Task

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

compatibilityqueryEndpoint:

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

## 3. Parameter Reference

| Parameters | Type | Required | Note |
| --- | --- | --- | --- |
| `model` | string | Yes | use 6 Modelone of |
| `prompt` | string | Yes | video generationprompt |
| `duration`| integer/string | Yes | Output video duration, recommended to pass `1-16` integer |
| `aspect_ratio`| string | recommended to pass | Ratio,`16:9`, `9:16`, `1:1` |
| `image` | string | /first-and-last-frame required | public image URL; single-image-to-video only pass one |
| `last_image`| string | first-and-last-frame required | image URL; and `image` use, legacy Field |
| `reference_image_urls` | string[] | multiple reference imagesRequired | Q3 Pro multiple reference imagesField, up to 4 public image URL |
| `extra_body.audio`| boolean | No | Whether to generate; requires pass `false` |
| `extra_body.seed` | integer | No | random seed |
| `extra_body.bgm`| boolean | No | Whether music; requires pass `false` |

Fielduseconstraints:

- text-to-video: only pass `prompt`, `model`, `duration`, Optional values `aspect_ratio`.
- single-image-to-video: pass `image`, do not pass both array.
- first-and-last-frame: pass `image`+`last_image`, do not use first-and-last-frame `images` array.
- multiple reference images: pass `reference_image_urls`, do not pass both `images`, `image_urls` or pass image.
- `reference_image_urls` recommended `viduq3p-*`, do not `viduq3t-*`.

## 4. Request Examples

In the examples below, `{BASE_URL}` can be replaced with `https://api.aijisu.cn`.

### 4.1 text-to-video

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "viduq3p-720p",
 "prompt": " camera, and, slow camera push-in. ",
 "aspect_ratio": "16:9",
 "duration": 5,
 "extra_body": {"audio": false,
 "seed": 42,
 "bgm": false}}'
```

### 4.2 single-image-to-video

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "viduq3t-540p",
 "prompt": " camera, natural motion, camera. ",
 "image": "https://example.com/source.png",
 "duration": 5,
 "extra_body": {"seed": 42}}'
```

### 4.3 first-and-last-frame video

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "viduq3p-720p",
 "prompt": ", keep identity stable, action. ",
 "image": "https://example.com/head.png",
 "last_image": "https://example.com/tail.png",
 "duration": 6,
 "extra_body": {"seed": 42}}'
```

### 4.4 reference-image-to-video

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "viduq3p-720p",
 "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"],
 "aspect_ratio": "16:9",
 "duration": 5,
 "extra_body": {"audio": false,
 "seed": 42,
 "bgm": false}}'
```

## 5. Response Examples

Create TaskSuccess:

```json
{
  "id": "task_xxxxx",
  "task_id": "task_xxxxx",
  "object": "video.generation.job",
  "model": "viduq3p-720p",
  "status": "queued",
  "progress": 0,
  "created_at": 1774507626
}
```

Query Task completed:

```json
{
  "id": "task_xxxxx",
  "task_id": "task_xxxxx",
  "object": "video.generation.job",
  "model": "viduq3p-720p",
  "status": "completed",
  "progress": 100,
  "video_url": "https://example.com/output.mp4",
  "created_at": 1774507626
}
```

 Status:

| Status | |
| --- | --- |
| `queued` | |
| `in_progress` | generation |
| `completed` | completed |
| `failed` | Failed |

## 6. Common Errors

### 6.1 to change `images`

do not pass:

```json
{
  "model": "viduq3p-720p",
  "prompt": "first-and-last-frame ",
  "images": [
    "https://example.com/head.png",
    "https://example.com/tail.png"
  ],
  "duration": 6
}
```
`images` reference. first-and-last-frame use `image`+`last_image`; multiple reference images use `reference_image_urls`.

### 6.2 Q3 Turbo use multiple reference images

do not `viduq3t-*` pass `reference_image_urls`. Q3 Turbo or use.

### 6.3 use Model

Create Task use Model 6 Model. Model Model do not `model` Parameterspass in.

## 7. and legacy

| | legacy | |
| --- | --- | --- |
| text-to-videoNote | `prompt` Fielddescription "only pass prompt image-to-video" | only pass `prompt` text-to-video |
| RequiredField | OpenAPI schema to change `image`, `last_image`, `reference_image_urls`, `aspect_ratio`, `extra_body` Required | only `model`, `prompt`, `duration` Required; imageField scenarioConditional |
| first-and-last-frame field | use `image`+`last_image`|`image`+`last_image`, user requires Field |
| first-and-last-framepass | Notedo not pass `images`| do not use first-and-last-frame `images` array;`images` Yesfirst-and-last-frame |
| multiple reference imagesModel | legacyExample Model Model | use `viduq3p-*`+`reference_image_urls` |
| multiple reference images | Note | recommendedup to 4 |
| Q3 Turbo multiple reference images | constraints | `viduq3t-*` multiple reference images |
| ExampleModel | legacyExample Model Model | user reserved 6 Model |
| `duration` Type | schema string, Examplepass number | recommended to passinteger; compatibility string |
| `extra_body.bgm` Type | schema string | boolean use |
| Query Task | createEndpoint | `GET /v1/video/generations/{task_id}` andcompatibility `GET /v1/videos/{task_id}` |

---

# Create Video Task (Old)

Locale: en
URL: https://docs.uniall.ai/models/video/vidu/create-task-old
Source: site-docs/models/video/vidu/create-task-old.md
Description: Vidu legacy create video task endpoint.

## 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 | viduq3p-540p, viduq3p-720p, viduq3p-1080p, viduq3t-540p, viduq3t-720p, viduq3t-1080p |
| `prompt` | string | Yes | prompt | only passprompt image-to-video |
| `image`| string | Yes | reference / reference | only pass image, pass `last_image`, image-to-video |
| `reference_image_urls` | array | Yes | mixmodereference | only mixmode, stringarray: Example: [, "https://example.com/ref-1.png", "https://example.com/ref-2.png"] |
| `last_image` | string | Yes | reference | pass both imageandlast_image first-and-last-frame video, does not supportonly pass last_image |
| `aspect_ratio` | string | Yes | Ratio | text-to-video; image-to-video pass in, result |
| `duration`| string | Yes | video () | allowed values:`1` `16` |
| `extra_body` | object | Yes | Parameters | |

## Request Examples

### text-to-video

```json
{
  "model": "viduq3p-720p",
  "prompt": " camera, and, slow camera push-in. ",
  "aspect_ratio": "16:9",
  "duration": 5,
  "extra_body": {
    "audio": false,
    "seed": 42,
    "bgm": false
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "viduq3p-720p",
 "prompt": " camera, and, slow camera push-in. ",
 "aspect_ratio": "16:9",
 "duration": 5,
 "extra_body": {"audio": false,
 "seed": 42,
 "bgm": false}}'
```
### single-image-to-video

```json
{
  "model": "viduq3t-540p",
  "prompt": " camera, natural motion, camera. ",
  "image": "https://example.com/source.png",
  "duration": 5,
  "extra_body": {
    "seed": 42
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "viduq3t-540p",
 "prompt": " camera, natural motion, camera. ",
 "image": "https://example.com/source.png",
 "duration": 5,
 "extra_body": {"seed": 42}}'
```
### first-and-last-frame video

```json
{
  "model": "viduq3p-1080p-offpeak",
  "prompt": ", keep identity stable, action. ",
  "image": "https://example.com/head.png",
  "last_image": "https://example.com/tail.png",
  "duration": 6
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "viduq3p-1080p-offpeak",
 "prompt": ", keep identity stable, action. ",
 "image": "https://example.com/head.png",
 "last_image": "https://example.com/tail.png",
 "duration": 6}'
```
### reference-image-to-video

```json
{
  "model": "viduq3p-mix-720p",
  "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"
  ],
  "aspect_ratio": "16:9",
  "duration": 5,
  "extra_body": {
    "audio": false,
    "seed": 42
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "viduq3p-mix-720p",
 "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"],
 "aspect_ratio": "16:9",
 "duration": 5,
 "extra_body": {"audio": false,
 "seed": 42}}'
```
## Response Fields

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


## Response Examples

### Success

```json
{
  "id": "task_xxxxx",
  "task_id": "task_xxxxx",
  "object": "video.generation.job",
  "model": "viduq3p-540p",
  "status": "queued",
  "progress": 0,
  "created_at": 1774507626
}
```

---

# Query Video Task

Locale: en
URL: https://docs.uniall.ai/models/video/vidu/query-task
Source: site-docs/models/video/vidu/query-task.md
Description: Vidu query video task endpoint.

## Endpoint


```http
GET /v1/videos/{task_id}
```
## Header Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No | | Bearer &#123;your_token&#125; |
## Path Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `task_id` | string | Yes | | |
## Response Fields

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


## Response Examples

### Example 1

```json
{
  "id": "task_xxxxxxxxxx",
  "model": "viduq3p-1080p",
  "object": "video",
  "status": "completed",
  "seconds": "8",
  "task_id": "5c9e83c9-1044-46cd-8cff-b2c4cb90efba",
  "progress": 100,
  "video_url": "https://xxxxxx/r/xxxxxx.mp4",
  "created_at": 1774102861000
}
```

---

# Wan 2.6 Video Generation

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.

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

## Query Task Status

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

```json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video.generation.job",
  "model": "wan2.6-video-1080p",
  "status": "completed",
  "progress": 100,
  "video_url": "https://example.com/output.mp4"
}
```

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

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

---

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

---

# Query Video Task

Locale: en
URL: https://docs.uniall.ai/models/video/wan-2-6/query-task
Source: site-docs/models/video/wan-2-6/query-task.md
Description: Wan 2.6 query video task endpoint.

## Endpoint


```http
GET /v1/videos/{task_id}
```
## Header Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No | | Bearer &#123;your_token&#125; |
## Path Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `task_id` | string | Yes | | |
## Response Fields

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


## Response Examples

### Example 1

```json
{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxx",
  "error": null,
  "model": "wan2.6-video-1080p",
  "object": "video.generation.job",
  "result": {
    "outputs": [
      "https://xxxxxxx.cn/predictions/xxxxx/1.mp4"
    ],
    "video_url": "https://xxxxxxx.cn/predictions/xxxxx/1.mp4"
  },
  "status": "completed",
  "task_id": "xxxxxxxxxxxxxxxxxxxxxxx",
  "progress": 100,
  "video_url": "https://xxxxxxx.cn/predictions/xxxxx/1.mp4",
  "created_at": 1773984104,
  "raw_status": "COMPLETED"
}
```

---

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

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

---

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

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

---

# 文档概览

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 | 示例使用 `{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 模型文档入口，并说明模型列表接口。

模型列表是当前 UniAll 选定模型文档的统一入口。这里按能力组织页面，而不是沿用原始 Apifox 菜单顺序。

当客户端需要在运行时发现当前 API Key 可用的模型时，可以调用模型列表接口。

## 能力分类

| 分类 | 页面 | 常用接口 |
| --- | --- | --- |
| 图像生成 | 通用异步图像生成、Seedream、GPT-Image-2、Nano 系列 | `POST /v1/images/tasks` 或 `POST /v1/images/generations` |
| 视频生成 | Happy-Horse、Seedance 2.0、Grok Imagine、Veo 3.1、Vidu、Kling、Wan 2.6、Sora 2 | `POST /v1/video/generations` 或 `POST /v1/videos` |
| 语音与音乐 | 音乐生成、语音合成 | 模型专属音频接口 |
| 数字人 | 数字人口播 | 模型专属数字人视频接口 |

## 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",
      "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)。
- 当模型 ID 为 `grok-imagine` 时，使用 [Grok Imagine 视频生成](/zh-CN/models/video/grok-imagine)。
- 能力专属页面会说明模型字段、计费说明和任务生命周期。
- `/v1/models` 适合运行时发现模型，不应作为唯一集成规则来源。

## Common Errors

| HTTP 状态 | 含义 |
| --- | --- |
| `401` | 缺少认证或认证无效。 |
| `403` | 当前 API Key 已禁用，或没有访问模型列表权限。 |

## Related Pages

- [文档概览](/zh-CN/)
- [查询余额](/zh-CN/balance)
- [通用异步图像生成](/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/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 音色。

使用 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 语音生成来源文档。

本文档介绍如何在 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: Kling Avatar v2 数字人口播来源文档。

本文档介绍如何在 aijisu 中使用 Kling Avatar v2 异步数字人视频生成接口。

当前支持模型：

| 模型名称 | 类型 | 适合场景 | 计费方式 |
|---|---|---|---|
| `kling-avatar-v2-standard` | 数字人视频 | 常规口播、客服讲解、课程导语、营销短视频 | 按输出视频秒数计费 |
| `kling-avatar-v2-pro` | 数字人视频 | 更高质量数字人口播、正式宣传片、品牌视频、重要课程内容 | 按输出视频秒数计费 |

接口采用异步任务模式：

| 操作 | 方法 | 路径 |
|---|---|---|
| 提交数字人视频任务 | `POST` | `/v1/video/generations` |
| 查询数字人视频任务 | `GET` | `/v1/video/generations/{task_id}` |

---

## 1. 通用鉴权

所有接口都需要在请求头中携带 API Key：

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

示例域名：

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

---

## 2. 模型简介

Kling Avatar v2 用于根据人物图片和音频生成数字人口播视频。用户需要提供一张人物图片和一段音频，模型会生成带口型和面部动作的视频。

支持两个版本：

| 模型 | 说明 |
|---|---|
| `kling-avatar-v2-standard` | 标准版本，适合常规口播和批量生成 |
| `kling-avatar-v2-pro` | Pro 版本，适合对画面、表情、稳定性要求更高的正式内容 |

---

## 3. 提交数字人视频任务

```http
POST https://api.xxx.xx/v1/video/generations
```

### 3.1 请求参数

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | 是 | `kling-avatar-v2-standard` 或 `kling-avatar-v2-pro` |
| `image_url` | string | 是 | 人物图片 URL |
| `audio_url` | string | 是 | 音频 URL，用于驱动口型 |
| `audio_duration_seconds` | number | 是 | 音频秒数，用于提交前预扣费估算 |
| `prompt` | string | 否 | 风格提示，例如场景、人物状态、镜头感觉 |

注意：

- `audio_duration_seconds` 必须传。
- 该字段用于提交前估价，避免无法预扣费。
- 请尽量传入音频真实秒数，避免费用预估和实际任务时长差异过大。

### 3.2 提交响应示例

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

字段说明：

| 字段 | 说明 |
|---|---|
| `id` / `task_id` | 异步任务 ID，用于查询结果 |
| `status` | 任务状态，常见值为 `queued`、`processing`、`completed`、`failed` |

---

## 4. 查询数字人视频任务

```http
GET https://api.xxx.xx/v1/video/generations/{task_id}
```

查询示例：

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

完成响应示例：

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "status": "completed",
  "video_url": "https://api.xxx.xx/media/xxxxx.mp4",
  "result": {
    "outputs": [
      "https://api.xxx.xx/media/xxxxx.mp4"
    ]
  }
}
```

---

## 5. 请求示例

### 5.1 Standard 生成客服讲解视频

```bash
curl -X POST "https://api.xxx.xx/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-avatar-v2-standard",
    "image_url": "https://cdn.example.com/avatar/customer-service.png",
    "audio_url": "https://cdn.example.com/audio/customer-intro.mp3",
    "audio_duration_seconds": 12,
    "prompt": "friendly customer service presenter, natural expression, clean studio lighting"
  }'
```

### 5.2 Standard 生成课程导语

```bash
curl -X POST "https://api.xxx.xx/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-avatar-v2-standard",
    "image_url": "https://cdn.example.com/avatar/teacher.png",
    "audio_url": "https://cdn.example.com/audio/course-opening.mp3",
    "audio_duration_seconds": 18.5,
    "prompt": "professional teacher, warm smile, stable camera, natural lip sync"
  }'
```

### 5.3 Pro 生成品牌口播视频

```bash
curl -X POST "https://api.xxx.xx/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-avatar-v2-pro",
    "image_url": "https://cdn.example.com/avatar/brand-host.png",
    "audio_url": "https://cdn.example.com/audio/brand-message.mp3",
    "audio_duration_seconds": 24,
    "prompt": "premium corporate spokesperson video, clean studio background, confident expression"
  }'
```

### 5.4 Pro 生成新闻播报

```bash
curl -X POST "https://api.xxx.xx/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-avatar-v2-pro",
    "image_url": "https://cdn.example.com/avatar/news-anchor.png",
    "audio_url": "https://cdn.example.com/audio/news-briefing.mp3",
    "audio_duration_seconds": 32.7,
    "prompt": "news anchor style, formal tone, stable frontal shot, neutral expression"
  }'
```

---


## 6. 常见错误

### 6.1 缺少 image_url

数字人视频必须提供人物图片：

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

### 6.2 缺少 audio_url

数字人视频必须提供驱动口型的音频：

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

### 6.3 缺少 audio_duration_seconds

错误请求：

```json
{
  "model": "kling-avatar-v2-standard",
  "image_url": "https://cdn.example.com/avatar.png",
  "audio_url": "https://cdn.example.com/voice.mp3"
}
```

修复方式：补充音频秒数：

```json
{
  "audio_duration_seconds": 12.5
}
```

---

## 7. 推荐工作流

1. 准备人物图片。
2. 使用 TTS 或录音生成一段音频。
3. 获取音频实际秒数。
4. 提交 `/v1/video/generations`，传入 `image_url`、`audio_url`、`audio_duration_seconds`。
5. 轮询 `/v1/video/generations/{task_id}`。
6. 任务完成后读取 `video_url`。

---

## 8. 最小可用请求

### 8.1 Avatar Standard

```bash
curl -X POST "https://api.xxx.xx/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-avatar-v2-standard",
    "image_url": "https://cdn.example.com/avatar.png",
    "audio_url": "https://cdn.example.com/voice.mp3",
    "audio_duration_seconds": 10
  }'
```

### 8.2 Avatar Pro

```bash
curl -X POST "https://api.xxx.xx/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-avatar-v2-pro",
    "image_url": "https://cdn.example.com/avatar.png",
    "audio_url": "https://cdn.example.com/voice.mp3",
    "audio_duration_seconds": 10
  }'
```

---

# 数字人概览

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 数字人口播文档入口。

本分类整理来源菜单中的数字人口播。

## 包含页面

- [数字人口播](/zh-CN/models/avatar/digital-human)

## 接入建议

数字人口播使用 Kling Avatar v2 模型。提交视频生成任务时传入数字人、音色和脚本文案，随后根据返回的 `task_id` 轮询，直到输出视频可用。

如果流程需要自定义 `voice_id`，先阅读 [语音合成](/zh-CN/models/audio/speech-synthesis)。

---

# 通用异步图像生成

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: 通用异步图像生成来源文档。

更新时间：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 生成或编辑图片。

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

---

# 编辑图像

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 生成图像接口。

公共模型名称为`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"
    }
  ]
}
```

---

# 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: 通过 UniAll 图像 API 调用 NanoBanana 系列模型生成或编辑图片。

Nano 系列覆盖 NanoBanana 模型家族。适合需要指定 Nano 模型档位，并使用 `aspect_ratio` 控制输出比例的场景。来源范围同时包含 OpenAI 兼容和 Gemini 兼容入口，新集成可以优先从通用异步图像任务流程开始。

## 支持模型

| 模型家族 | 示例 ID | 说明 |
| --- | --- | --- |
| NanoBanana | `NanoBanana` | 基础 NanoBanana 模型。 |
| NanoBanana Pro | `NanoBananaPro-*` | Pro 档位变体。 |
| NanoBanana 2 | `NanoBanana2-0.5K`、`NanoBanana2-1K` | 按分辨率档位区分的 NanoBanana 2 变体。 |

实际可用模型取决于账号通道和模型价格配置。

## 推荐 Endpoint

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

Apifox 来源也提供 Nano 的 OpenAI 兼容图像接口：

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

并提供 Gemini 兼容格式给 Gemini 风格客户端使用。选择与客户端格式一致的入口即可，下方请求概念保持一致。

## Authentication

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

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 具体 Nano 模型 ID，例如 `NanoBanana2-0.5K`。 |
| `prompt` | string | 是 | 生成或编辑提示词。 |
| `task_type` | string | 否 | `text2image` 或 `image2image`，也可以由图片输入推断。 |
| `image` | string/object | 条件必填 | 编辑任务的单张参考图。 |
| `images` | string[] | 条件必填 | 多张参考图 URL。 |
| `aspect_ratio` | string | 否 | 推荐的比例控制字段，例如 `1:1`、`16:9`、`9:16`、`4:3` 或 `3:4`。 |
| `output_format` | string | 否 | `NanoBanana` 支持 `png`、`jpeg`、`webp`；Pro 和 NanoBanana 2 变体在当前来源范围内支持 `png` 和 `jpeg`。 |
| `n` | integer | 否 | 输出数量，默认 `1`；最大值取决于上游限制。 |
| `response_format` | string | 否 | 生成资产建议使用 `url`。 |

## 文生图示例

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

## 图生图示例

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

## 查询任务状态

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

## 计费说明

NanoBanana 系列按配置模型单价乘以 `n` 或实际返回结果数量计费。`aspect_ratio` 和 `output_format` 控制输出形态和格式，但在当前来源范围内不是独立计费维度。

## 常见错误

- 使用当前账号未启用的 Nano 模型 ID。
- 将 `image`、`images` 和兼容图像字段混用。
- 把 `size` 当作 Nano 的主要控制字段；Nano 优先使用 `aspect_ratio`。
- 为所选 Nano 家族请求不支持的输出格式。
- 任务还没有创建成功就开始轮询。

## 相关页面

- [通用异步图像生成](/zh-CN/models/image/async-image-generation)
- [GPT-Image-2 图像生成](/zh-CN/models/image/gpt-image-2)
- [Seedream 图像生成](/zh-CN/models/image/seedream)

---

# 原生 Gemini 格式

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: Nano 系列原生 Gemini 格式接口。

## Endpoint


```http
POST /v1beta/models/{modeName}:generateContent
```
## Header 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No |  | Bearer &#123;your_token&#125; |
## Path 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `modeName` | string | Yes | gemini-3-pro-image-preview-1k, gemini-3-pro-image-preview-2k, gemini-3-pro-image-preview-4k, gemini-3.1-flash-image-preview-512, gemini-3.1-flash-image-preview-1k, gemini-3.1-flash-image-preview-2k, gemini-3.1-flash-image-preview-4k | 模型名称： |
## 请求体参数

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `generationConfig.imageConfig.aspectRatio` | string | Yes | 画幅比例 | 可选:1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 |
| `generationConfig.imageConfig.outputFormat` | string | Yes | 输出格式 | 可选：jpeg，png |
| `contents` | array | No | Example field | Appears in a request example; no separate field description is provided. |
| `generationConfig` | object | No | Example field | Appears in a request example; no separate field description is provided. |

## 请求示例

### 默认

```json
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "一直可爱的小狗"
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "IMAGE"
    ]
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1beta/models/{modeName}:generateContent" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "一直可爱的小狗"
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "IMAGE"
    ]
  }
}'
```
### 文生图

```json
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "[主题]的HA[风格]贴纸，具有[关键特征]和[色调]。设计应采用[线条风格]和[阴影风格]。背景必须透明。"
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "IMAGE"
    ],
    "imageConfig": {
      "aspectRatio": "9:16",
      "imageSize": "1K"
    }
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1beta/models/{modeName}:generateContent" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
        {
            "role": "user",
            "parts": [
                {
                    "text": "[主题]的HA[风格]贴纸，具有[关键特征]和[色调]。设计应采用[线条风格]和[阴影风格]。背景必须透明。"
                }
            ]
        }
    ],
    "generationConfig": {
        "responseModalities": [
            "IMAGE"
        ],
        "imageConfig": {
            "aspectRatio": "9:16",
            "imageSize": "1K"
        }
    }
}'
```
### 图片编辑

```json
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "将这幅关于[主题]的粗略[中等]草图转换成一张[风格描述]照片。保留草图中的[特定特征]，但添加[新的细节/材料]"
        },
        {
          "inline_data": {
            "mime_type": "image/jpeg",
            "data": "image_base64"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "IMAGE"
    ],
    "imageConfig": {
      "aspectRatio": "9:16",
      "imageSize": "1K"
    }
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1beta/models/{modeName}:generateContent" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
        {
            "role": "user",
            "parts": [
                {
                    "text": "将这幅关于[主题]的粗略[中等]草图转换成一张[风格描述]照片。保留草图中的[特定特征]，但添加[新的细节/材料]"
                },
                {
                    "inline_data": {
                        "mime_type": "image/jpeg",
                        "data": "image_base64"
                    }
                }
            ]
        }
    ],
    "generationConfig": {
        "responseModalities": [
            "IMAGE"
        ],
        "imageConfig": {
            "aspectRatio": "9:16",
            "imageSize": "1K"
        }
    }
}'
```
### 多图生图

```json
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "使用提供的图片，将[图片2中的元素]放置到[图片1中的元素]上。确保[图片1中的元素]的特征保持完全不变。添加的元素应[描述元素应如何整合]。"
        },
        {
          "inline_data": {
            "mime_type": "image/jpeg",
            "data": "image_base64_1"
          }
        },
        {
          "inline_data": {
            "mime_type": "image/jpeg",
            "data": "image_base64_2"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "IMAGE"
    ],
    "imageConfig": {
      "aspectRatio": "9:16",
      "imageSize": "1K"
    }
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1beta/models/{modeName}:generateContent" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
        {
            "role": "user",
            "parts": [
                {
                    "text": "使用提供的图片，将[图片2中的元素]放置到[图片1中的元素]上。确保[图片1中的元素]的特征保持完全不变。添加的元素应[描述元素应如何整合]。"
                },
                {
                    "inline_data": {
                        "mime_type": "image/jpeg",
                        "data": "image_base64_1"
                    }
                },
                {
                    "inline_data": {
                        "mime_type": "image/jpeg",
                        "data": "image_base64_2"
                    }
                }
            ]
        }
    ],
    "generationConfig": {
        "responseModalities": [
            "IMAGE"
        ],
        "imageConfig": {
            "aspectRatio": "9:16",
            "imageSize": "1K"
        }
    }
}'
```
## 响应字段

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


## 响应示例

### 成功

```json
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/jpeg",
              "data": "image_base64"
            }
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": []
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 0,
    "candidatesTokenCount": 0,
    "totalTokenCount": 0
  }
}
```

---

# 原生 OpenAI 格式

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: Nano 系列原生 OpenAI 格式接口。

## 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 | 模型名称 | 可选:NanoBanana，NanoBananaPro-1K，NanoBananaPro-2K，NanoBananaPro-4K，NanoBanana2-0.5K，NanoBanana2-1K，NanoBanana2-2K，NanoBanana2-4K |
| `--aspect_ratio` | string | Yes | 宽高比 | 可选:1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 |
| `--output_format` | string | Yes | 图片类型 | 可选:"jpeg"，“png”，“webp” |
| `messages` | array | 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. |
| `stream` | boolean | No | Example field | Appears in a request example; no separate field description is provided. |

## 请求示例

### 文生图

```json
{
  "model": "NanoBananaPro-1K",
  "messages": [
    {
      "role": "user",
      "content": "a cute cat"
    }
  ],
  "extra_body": {
    "google": {
      "image_config": {
        "aspect_ratio": "16:9"
      }
    }
  },
  "stream": true
}
```

```bash
curl -X POST "{BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "NanoBananaPro-1K",
    "messages": [
        {
            "role": "user",
            "content": "a cute cat"
        }
    ],
    "extra_body": {
        "google": {
            "image_config": {
                "aspect_ratio": "16:9"
            }
        }
    },
    "stream": true
}'
```
### 图生图

```json
{
  "model": "NanoBananaPro-1K",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "在同一画布下，生成此物品的三视图，必须白色背景"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/xxxxxxx.jpg"
          }
        }
      ]
    }
  ],
  "extra_body": {
    "google": {
      "image_config": {
        "aspect_ratio": "16:9"
      }
    }
  },
  "stream": true
}
```

```bash
curl -X POST "{BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "NanoBananaPro-1K",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "在同一画布下，生成此物品的三视图，必须白色背景"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/xxxxxxx.jpg"
                    }
                }
            ]
        }
    ],
    "extra_body": {
        "google": {
            "image_config": {
                "aspect_ratio": "16:9"
            }
        }
    },
    "stream": true
}'
```
## 响应字段

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


## 响应示例

### 生成成功

```json
{
  "id": "chatcmpl_3a72451d018247b6a14adb45275c2433",
  "object": "chat.completion.chunk",
  "created": 1773835762,
  "model": "NanoBananaPro-8K",
  "choices": [
    {
      "index": 0,
      "delta": {
        "role": "assistant",
        "content": "https://xxx.xxx.cn/output/38fa5bcb-d055-40b0-9f04-5ef259c9131c-u2_307ace79-d89b-4075-9e71-8180774947c4.jpeg"
      },
      "finish_reason": "stop"
    }
  ],
  "media": {
    "outputs": [
      "https://xxx.xxx.cn/output/38fa5bcb-d055-40b0-9f04-5ef259c9131c-u2_307ace79-d89b-4075-9e71-8180774947c4.jpeg"
    ]
  }
}
```

---

# 图像生成概览

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)
- [GPT-Image-2 图像生成](/zh-CN/models/image/gpt-image-2)
- [Nano 系列图像生成](/zh-CN/models/image/nano-series)

## 接入建议

如果所选模型使用轮询流程，先阅读通用异步图像生成页面。Seedream 和 OpenAI 兼容图像页面会分别说明同步生成与编辑接口。

---

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

---

# 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 视频来源文档。

更新时间：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. 查询任务和获取视频

### 8.1 查询状态

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

处理中：

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

完成：

```json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video",
  "model": "grok-imagine",
  "status": "completed",
  "progress": 100,
  "created_at": 1773980459,
  "completed_at": 1773980519,
  "seconds": "6",
  "size": "720p",
  "metadata": {
    "url": "https://example.com/result.mp4"
  }
}
```

失败：

```json
{
  "id": "task_xxx",
  "object": "video",
  "model": "grok-imagine",
  "status": "failed",
  "progress": 100,
  "created_at": 1773980459,
  "error": {
    "code": "task_failed",
    "message": "request rejected"
  }
}
```

建议客户端每 `2-5` 秒轮询一次，直到 `status` 为 `completed` 或 `failed`。

### 8.2 代理获取视频文件

```bash
curl "{BASE_URL}/v1/videos/task_xxx/content" \
  -H "Authorization: Bearer sk-***" \
  -o result.mp4
```

该接口返回 `video/mp4` 文件流。也可以直接使用查询响应中的 `metadata.url`。

## 9. 计费说明

Grok 视频在本站使用组件式计费，公开价格以模型广场展示为准。

| 场景 | 主要计费项 |
| --- | --- |
| 文生视频 | 清晰度档、输出视频秒数 |
| 单图生视频 | 清晰度档、输出视频秒数 |
| 多参考图生视频 | 清晰度档、输出视频秒数 |
| 视频编辑 | 清晰度档、输入视频秒数、输出视频秒数 |
| 视频续写 | 输入视频秒数、输出视频秒数 |

公开展示会显示“按实际参数计算”和组件单价，例如：

- 输入视频：按秒
- 输出视频 480P：按秒
- 输出视频 720P：按秒

图生视频和多参考图生视频中的输入图片数量可能出现在结算 facts 里，但第一版 Grok 视频规则不应把它配置成单独收费组件。

提交时可能有预扣。预扣用于任务提交阶段的余额锁定，不是把某个最大值当成单次公开售价。

## 10. 常见错误

### 把视频模型发到图片接口

`grok-imagine` 应调用 `/v1/videos`，不要发到 `/v1/images/generations`。

### 编辑和续写都只传了 `video`

这会产生歧义。编辑传：

---

# Grok Imagine 图片生成

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 图片来源文档。

更新时间：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: Grok Video 1.5 来源文档。

更新时间：2026-06-26

本文介绍如何在 aijisu 中调用 `grok-video-1.5`。该模型用于单图生视频：用户提供一张输入图片和一段提示词，平台异步生成视频任务。

## 1. 可用模型

| 模型 | 能力 | 输入图片 | 输出清晰度 |
| --- | --- | --- | --- |
| `grok-video-1.5` | 单图生视频 | 仅支持 1 张 | `480p`、`720p`、`1080p` |

说明：

- `grok-video-1.5` 是独立模型名，不要和旧版 `grok-imagine` 混用。
- 当前只支持单图生视频，不支持文生视频、多参考图、视频输入、视频编辑或视频续写。
- 输入图片必须是平台和上游服务可访问的图片 URL。
- 当前没有独立的横屏/竖屏参数；需要横屏请传横向输入图，需要竖屏请传竖向输入图。

## 2. 接口

### 2.1 创建视频任务

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

请求头：

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

### 2.2 查询视频任务

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

兼容查询接口：

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

### 2.3 获取视频文件

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

任务完成后，可以直接读取查询响应中的 `video_url`，也可以通过 `/content` 接口获取视频文件流。

## 3. 参数说明

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 固定传 `grok-video-1.5` |
| `prompt` | string | 是 | 视频生成提示词，建议描述主体、动作、镜头、风格和禁止项 |
| `image` | string | 二选一 | 输入图片 URL；和 `image_url` 二选一 |
| `image_url` | string | 二选一 | 输入图片 URL；和 `image` 二选一 |
| `duration` | integer | 否 | 输出视频秒数，支持 `1-15`，建议显式传入 |
| `seconds` | string | 否 | 输出视频秒数的兼容字段；优先推荐使用 `duration` |
| `size` | string | 否 | 输出清晰度，支持 `480p`、`720p`、`1080p` |
| `resolution` | string | 否 | 输出清晰度的兼容字段；优先推荐使用 `size` |

字段约束：

- `image` 和 `image_url` 只传一个即可。
- 不要同时传 `images`、`image_urls`、`reference_image_urls` 等多图字段。
- 不要传 `video`、`video_url`、`videos`、`video_urls` 等视频输入字段。
- 不要传 `aspect_ratio`。
- 不要传 `extra_body.operation` 来请求编辑、续写、参考视频或文生视频能力。
- `size` / `resolution` 只表示清晰度档，不表示横屏或竖屏；画面方向请通过输入图片比例控制。
- 如果同时传 `size` 和 `resolution`，建议保持二者值一致。

## 4. 请求示例

以下示例中的 `{BASE_URL}` 可替换为 `https://api.aijisu.cn`。

### 4.1 使用 `image_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": "A cinematic close-up of a glass perfume bottle on a marble table, soft morning light, slow camera push-in, elegant product video, no text, no logo.",
    "image_url": "https://example.com/source.jpg",
    "duration": 6,
    "size": "720p"
  }'
```

### 4.2 使用 `image`

```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 landscape photo becomes a gentle animated scene, leaves moving in the wind, soft natural lighting, stable camera, no text.",
    "image": "https://example.com/landscape.png",
    "duration": 8,
    "size": "1080p"
  }'
```

### 4.3 480p 快速预览

```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 simple product shot, the object slowly rotates on a clean white background, smooth motion, no text.",
    "image_url": "https://example.com/product.jpg",
    "duration": 4,
    "size": "480p"
  }'
```

## 5. 创建响应示例

创建成功后会返回任务对象。此时视频通常还在队列或生成中。

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

请保存 `id` 或 `task_id`，后续用于查询任务。

## 6. 查询任务

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

处理中响应示例：

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "grok-video-1.5",
  "status": "in_progress",
  "progress": 35,
  "created_at": 1782400000
}
```

完成响应示例：

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "grok-video-1.5",
  "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"
    ]
  }
}
```

## 7. 下载视频

方式一：直接使用查询响应里的 `video_url`。

方式二：通过任务内容接口获取文件流。

```bash
curl -L "{BASE_URL}/v1/videos/task_xxxxxxxxxxxxx/content" \
  -H "Authorization: Bearer sk-***" \
  -o grok-video-1.5-output.mp4
```

## 8. 状态说明

| 状态 | 说明 |
| --- | --- |
| `queued` | 任务已创建，等待处理 |
| `in_progress` | 任务处理中 |
| `completed` | 任务完成，可以读取视频 URL |
| `failed` | 任务失败，查看响应中的 `error.message` |

客户端建议每隔 3 到 10 秒轮询一次，直到任务进入 `completed` 或 `failed`。

## 9. 常见错误

### 把模型发到图片接口

`grok-video-1.5` 是视频模型，应调用 `/v1/videos`，不要发到 `/v1/images/generations`。

### 没有传输入图片

该模型必须传 `image` 或 `image_url`。只传 `prompt` 会被拒绝。

### 传了多张图片

该模型只支持一张输入图片。不要传 `images`、`image_urls` 或 `reference_image_urls`。

### 传了视频输入

该模型不支持视频输入。不要传 `video`、`video_url`、`videos` 或 `video_urls`。

### 清晰度格式错误

`size` 或 `resolution` 只能传：

- `480p`
- `720p`
- `1080p`

不要传 `1920x1080`、`1280x720`、`4k` 或其他像素尺寸字符串。

### 想用 `aspect_ratio` 控制横竖屏

该模型当前不支持 `aspect_ratio`。请在提交前把输入图片裁剪为目标画面方向，例如横屏使用横向图片，竖屏使用竖向图片。

### 请求编辑或续写能力

`grok-video-1.5` 不支持编辑和续写。不要传：

```json
{
  "extra_body": {
    "operation": "edit_video"
  }
}
```

或：

```json
{
  "extra_body": {
    "operation": "video_extend"
  }
}
```

## 10. 提示词建议

提示词建议包含：

- 主体：画面中要动起来的对象。
- 动作：主体如何运动。
- 镜头：推进、拉远、平移、固定机位等。
- 风格：真实摄影、电影感、产品广告、自然光等。
- 限制：不要文字、不要 logo、不要人物等。

示例：

```markdown
A cinematic product video of the object slowly rotating on a clean studio background, soft natural light, smooth camera push-in, realistic texture, no text, no logo.
```

## 11. 最小可用请求

```json
{
  "model": "grok-video-1.5",
  "prompt": "A calm product video, slow camera movement, soft light, no text.",
  "image_url": "https://example.com/source.jpg",
  "duration": 6,
  "size": "720p"
}
```

---

# 创建视频生成任务（老）

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/grok/legacy-create-video
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/grok/legacy-create-video.md
Description: Grok 旧版创建视频生成任务接口。

## 说明

### `grok-imagine`

适用场景：

- 文生视频
- 单图生视频

选择规则：

- 只有 `prompt` -> 文生视频
- `prompt + image` -> 图生视频

## 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 | 图生视频 |
| `duration` | string | Yes | 输出时长，单位秒 | 允许值：`6`、`10` |
| `size` | string | Yes | 输出分辨率 | 允许值：`480p`、`720p` |
| `aspect_ratio` | string | Yes | 输出比例 | 允许值：`16:9`、`1:1`、`9:16` |

## 请求示例

### 文生视频

```json
{
  "model": "grok-imagine",
  "prompt": "电影感手持镜头，一名记者站在暴雪中的时代广场，路人撑伞快速走过，雪花不断打在镜头前，皮肤纹理真实，整体色调克制。",
  "size": "720p",
  "aspect_ratio": "16:9",
  "duration": 6
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine",
    "prompt": "电影感手持镜头，一名记者站在暴雪中的时代广场，路人撑伞快速走过，雪花不断打在镜头前，皮肤纹理真实，整体色调克制。",
    "size": "720p",
    "aspect_ratio": "16:9",
    "duration": 6
}'
```
### 单图生视频

```json
{
  "model": "grok-imagine",
  "prompt": "人物缓慢转头看向镜头，头发随风轻微摆动，电影级布光，镜头有细微推进。",
  "image": "https://example.com/portrait.png",
  "size": "480p",
  "aspect_ratio": "9:16",
  "duration": 10
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine",
    "prompt": "人物缓慢转头看向镜头，头发随风轻微摆动，电影级布光，镜头有细微推进。",
    "image": "https://example.com/portrait.png",
    "size": "480p",
    "aspect_ratio": "9:16",
    "duration": 10
}'
```
## 响应字段

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


## 响应示例

### 示例 1

```json
{}
```

---

# 查询视频任务

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/grok/legacy-query-video
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/grok/legacy-query-video.md
Description: Grok 旧版查询视频任务接口。

## Endpoint


```http
GET /v1/videos/{task_id}
```
## Header 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No |  | Bearer &#123;your_token&#125; |
## Path 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `task_id` | string | Yes |  |  |
## 响应字段

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


## 响应示例

### 示例 1

```json
{
  "id": "task_xxxxxxxxxx",
  "model": "grok-imagine",
  "object": "video",
  "status": "completed",
  "seconds": "8",
  "task_id": "5c9e83c9-1044-46cd-8cff-b2c4cb90efba",
  "progress": 100,
  "video_url": "https://xxxxxx/r/xxxxxx.mp4",
  "created_at": 1774102861000
}
```

---

# 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 视频 API 调用 Happy-Horse 模型生成视频。

Happy-Horse 支持文生视频、图生视频、多参考图生视频和视频编辑。通过统一视频生成接口提交任务，再轮询任务 ID，直到返回结果视频 URL。

## 支持模型

| 模型 | 用途 |
| --- | --- |
| `happy-horse-720p` | 720p 文生视频、图生视频和多参考图生成。 |
| `happy-horse-1080p` | 1080p 文生视频、图生视频和多参考图生成。 |
| `happy-horse-edit-720p` | 720p 视频编辑。 |
| `happy-horse-edit-1080p` | 1080p 视频编辑。 |

## Endpoint

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

## Authentication

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

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | Happy-Horse 公共模型 ID。 |
| `prompt` | string | 是 | 提示词。来源限制最多 `2500` 字符。 |
| `aspect_ratio` | string | 否 | `16:9`、`9:16`、`1:1`、`4:3` 或 `3:4`。 |
| `duration` | integer | 条件必填 | 输出秒数，来源范围为 `3` 到 `15`。 |
| `seed` | integer | 否 | 随机种子，范围 `0` 到 `2147483647`。 |
| `image` | string | 条件必填 | 单张公开可访问的源图片 URL。 |
| `images` | string[] | 条件必填 | `1` 到 `9` 张公开可访问的参考图 URL。 |
| `video` | string | 条件必填 | 编辑模型使用的源视频 URL。 |
| `reference_image_urls` | string[] | 否 | 视频编辑参考图。 |
| `audio_setting` | string | 否 | `auto` 或 `origin`；默认跟随上游配置。 |

## 文生视频示例

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse-720p",
    "prompt": "A cinematic wide shot of a white horse running across a misty grassland at sunrise, realistic motion, soft rim light.",
    "duration": 4,
    "aspect_ratio": "16:9",
    "size": "720p",
    "seed": 12345
  }'
```

## 图生视频示例

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse-1080p",
    "prompt": "Animate the subject naturally, with subtle camera push-in and realistic cloth movement.",
    "image": "https://example.com/source-frame.png",
    "duration": 6,
    "size": "1080p",
    "seed": 67890
  }'
```

## 多参考图示例

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse-1080p",
    "prompt": "character1 rides character2 through a futuristic city street, keep both identities consistent.",
    "images": [
      "https://example.com/character1.png",
      "https://example.com/character2.png"
    ],
    "duration": 8,
    "aspect_ratio": "9:16",
    "seed": 24680
  }'
```

## 视频编辑示例

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse-edit-720p",
    "prompt": "Change the actor jacket into a red leather jacket while preserving motion, face identity, camera movement, and background.",
    "video": "https://example.com/source-video.mp4",
    "reference_image_urls": [
      "https://example.com/jacket-reference.png"
    ],
    "duration": 4,
    "size": "720p"
  }'
```

## 查询任务状态

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

```json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video.generation.job",
  "model": "happy-horse-720p",
  "status": "completed",
  "progress": 100,
  "video_url": "https://example.com/output.mp4"
}
```

建议每 2 到 5 秒轮询一次。`status` 为 `completed` 或 `failed` 时停止。

## 计费说明

Happy-Horse 计费与模型档位、输出分辨率、输出秒数和操作类型有关。视频编辑可能涉及源视频处理。最终价格以当前产品价格页和任务结算记录为准。

## 常见错误

- 编辑模型没有传 `video`。
- `duration` 不在 `3` 到 `15` 范围内。
- 媒体 URL 私有、过期或上游不可访问。
- 参考图超过 `9` 张。
- 使用 720p 模型却请求 1080p `size`。

## 相关页面

- [视频生成概览](/zh-CN/models/video/overview)
- [Seedance 2.0 视频生成](/zh-CN/models/video/seedance-2-0)
- [Veo 3.1 视频生成](/zh-CN/models/video/veo-3-1)

---

# 创建视频生成任务

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 创建视频生成任务接口。

本文档说明 Happy Horse 视频模型调用方式。

## 公共模型

| 公共模型 | 能力 | 分辨率档位 |
|---|---|---:|
| `happy-horse-720p` | 文生视频、图生视频、参考图生视频 | 720p |
| `happy-horse-1080p` | 文生视频、图生视频、参考图生视频 | 1080p |
| `happy-horse-edit-720p` | 视频编辑 | 720p |
| `happy-horse-edit-1080p` | 视频编辑 | 1080p |


说明：

- `duration` 对所有 Happy Horse 公共模型都是必传参数，允许 `3` 到 `15` 秒。
- 对视频编辑模型，`duration` 只用于计费和任务记录，编辑输出实际时长由输入视频决定，最多处理前 `15` 秒。
- 生成模型的 `aspect_ratio` 只对文生视频和参考图生视频有效；图生视频由输入图片决定构图。
- 视频编辑模型不支持 `aspect_ratio`。

## 接口

提交任务：

```http
POST /v1/videos/generations
Authorization: Bearer <api-key>
Content-Type: application/json
```

查询任务：

```http
GET /v1/videos/generations/{task_id}
Authorization: Bearer <api-key>
```

## 参数说明

| 参数 | 类型 | 必填 | 适用模型 | 说明 |
|---|---|---:|---|---|
| `model` | string | 是 | 全部 | 公共模型名 |
| `prompt` | string | 是 | 全部 | 提示词，最多 `2500` 字符 |
| `duration` | integer | 是 | 全部 | 允许 `3` 到 `15` 秒；编辑模型仅用于外围计费 |
| `size` | string | 否 | 全部 | 可选传同档位值：720p 模型传 `720p`，1080p 模型传 `1080p` |
| `seed` | integer | 否 | 全部 | 随机种子，范围按 `0` 到 `2147483647` |
| `aspect_ratio` | string | 否 | 文生视频、参考图生视频 | 可选 `16:9`、`9:16`、`1:1`、`4:3`、`3:4` |
| `image` | string | 图生视频必填 | 图生视频 | 单张源图片 URL |
| `images` | string[] | 参考图生视频必填 | 参考图生视频 | 1 到 9 张参考图片 URL |
| `reference_image_urls` | string[] | 参考图生视频可用 | 参考图生视频 | `images` 的等价别名 |

图片约束：

- 图生视频 `image` 支持 `jpeg`、`jpg`、`png`、`bmp`、`webp`，图片尺寸至少 `300px`，比例在 `1:2.5` 到 `2.5:1`，最大 `10MB`。
- 参考图生视频 `images` 支持 `jpeg`、`jpg`、`png`、`webp`，1 到 9 张，最短边至少 `400px`，建议 720p 以上，单张最大 `10MB`。
- 参考图生视频提示词中应使用 `character1` 到 `character9` 指代图片角色。

### 视频编辑参数

| 参数 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `video` | string | 是 | 输入视频 URL |
| `reference_image_urls` | string[] | 否 | 参考图片 URL，最多 5 张 |
| `audio_setting` | string | 否 | 可选 `auto` 或 `origin`，默认使用上游默认 `auto` |

输入视频约束：

- 支持 `mp4`、`mov`，推荐 H.264。
- 输入视频时长 `3` 到 `60` 秒。
- 长边不超过 `2160px`，短边不小于 `320px`。
- 画面比例在 `1:2.5` 到 `2.5:1`。
- 帧率大于 `8fps`，文件最大 `100MB`。

参考图片约束：

- 最多 5 张。
- 支持 `jpeg`、`jpg`、`png`、`webp`。
- 尺寸至少 `300px`，比例在 `1:2.5` 到 `2.5:1`。
- 单张最大 `10MB`。

## 接口参数与示例

### 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 | 模型名称 | 公共模型名 |
| `prompt` | string | Yes | 提示词 | 提示词，最多 `2500` 字符 |
| `image` | string | Yes | 参考图URL | 单张源图片 URL，必须是公开可访问的URL图片链接 |
| `images` | string | Yes | 参考图生视频 | 1 到 9 张参考图片 URL |
| `aspect_ratio` | string | No | 画幅比例 | 可选 `16:9`、`9:16`、`1:1`、`4:3`、`3:4` |
| `duration` | string | No | 输出描述 | 允许 `3` 到 `15` 秒；编辑模型仅用于外围计费 |
| `seed` | string | Yes | 随机种子 | 随机种子，范围按 `0` 到 `2147483647` |
| `video` | string | Yes | 输入视频URL | 必须是公开可访问的URL媒体链接 |
| `audio_setting` | string | Yes |  | 可选 `auto` 或 `origin`，默认使用上游默认 `auto` |
| `size` | string | No | Example field | Appears in a request example; no separate field description is provided. |
| `reference_image_urls` | array | No | Example field | Appears in a request example; no separate field description is provided. |

### 请求示例

#### 文生视频

```json
{
  "model": "happy-horse-720p",
  "prompt": "A cinematic wide shot of a white horse running across a misty grassland at sunrise, realistic motion, soft rim light.",
  "duration": 4,
  "aspect_ratio": "16:9",
  "size": "720p",
  "seed": 12345
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse-720p",
    "prompt": "A cinematic wide shot of a white horse running across a misty grassland at sunrise, realistic motion, soft rim light.",
    "duration": 4,
    "aspect_ratio": "16:9",
    "size": "720p",
    "seed": 12345
}'
```
#### 图生视频

```json
{
  "model": "happy-horse-1080p",
  "prompt": "Animate the subject naturally, with subtle camera push-in and realistic cloth movement.",
  "image": "https://example.com/source-frame.png",
  "duration": 6,
  "size": "1080p",
  "seed": 67890
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse-1080p",
    "prompt": "Animate the subject naturally, with subtle camera push-in and realistic cloth movement.",
    "image": "https://example.com/source-frame.png",
    "duration": 6,
    "size": "1080p",
    "seed": 67890
}'
```
#### 参考图生视频

```json
{
  "model": "happy-horse-1080p",
  "prompt": "character1 rides character2 through a futuristic city street, keep both identities consistent.",
  "images": [
    "https://example.com/character1.png",
    "https://example.com/character2.png"
  ],
  "duration": 8,
  "aspect_ratio": "9:16",
  "seed": 24680
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse-1080p",
    "prompt": "character1 rides character2 through a futuristic city street, keep both identities consistent.",
    "images": [
        "https://example.com/character1.png",
        "https://example.com/character2.png"
    ],
    "duration": 8,
    "aspect_ratio": "9:16",
    "seed": 24680
}'
```
#### 视频编辑

```json
{
  "model": "happy-horse-edit-720p",
  "prompt": "Change the actor jacket into a red leather jacket while preserving motion, face identity, camera movement, and background.",
  "video": "https://example.com/source-video.mp4",
  "reference_image_urls": [
    "https://example.com/jacket-reference.png"
  ],
  "duration": 4,
  "size": "720p",
  "audio_setting": "origin",
  "seed": 13579
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse-edit-720p",
    "prompt": "Change the actor jacket into a red leather jacket while preserving motion, face identity, camera movement, and background.",
    "video": "https://example.com/source-video.mp4",
    "reference_image_urls": [
        "https://example.com/jacket-reference.png"
    ],
    "duration": 4,
    "size": "720p",
    "audio_setting": "origin",
    "seed": 13579
}'
```
### 响应字段

| 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 | 秒数 |  |

### 响应示例

#### 成功

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "happy-horse-edit-720p",
  "status": "queued",
  "progress": 0,
  "created_at": 1777355454
}
```

---

# 查询视频生成任务

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/happy-horse/query-task
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/happy-horse/query-task.md
Description: Happy-Horse 查询视频生成任务接口。

## Endpoint


```http
GET /v1/videos/{task_id}
```
## Header 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No |  | Bearer &#123;your_token&#125; |
## Path 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `task_id` | string | Yes |  |  |
## 响应字段

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `id` | string | Yes | 任务ID |  |
| `model` | string | Yes | 模型名称 |  |
| `object` | string | Yes | 任务类型 |  |
| `prompt` | string | Yes | 提示词 |  |
| `status` | string | Yes | 状态 | queued: 排队中, in_progress: 生成中, completed: 已完成, failed: 失败 |
| `duration` | string | Yes | 任务耗时 |  |
| `metadata` | string | Yes | // |  |
| `progress` | string | Yes | 进度 |  |
| `video_url` | string | Yes | 视频URL |  |
| `created_at` | string | Yes | 创建时间 |  |
| `thumbnail_url` | string | Yes | 缩略图 |  |

## 响应示例

### 示例 1

```json
{
  "id": "task_xxxxxxxxxxxxxxx",
  "error": null,
  "model": "happy-horse-edit-720p",
  "object": "video.generation.job",
  "result": {
    "outputs": [
      "https://xxxxxxxxxxx.cn/xxxxxxxx.mp4"
    ],
    "video_url": "https://xxxxxxxxxxx.cn/xxxxxxxx.mp4"
  },
  "status": "completed",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxx",
  "progress": 100,
  "video_url": "https://xxxxxxxxxxx.cn/xxxxxxxx.mp4",
  "created_at": 1777355454,
  "raw_status": "COMPLETED"
}
```

---

# 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 视频 API 调用 Kling v3 模型生成视频。

Kling 支持文生视频、图生视频、首尾帧和高级提示词控制。通过公共模型 ID 选择标准或 Pro 档，以及静音或带音频输出。

## 支持模型

| 模型 | 档位 | 音频 |
| --- | --- | --- |
| `kling-v3-std-silent` | 标准 | 静音输出。 |
| `kling-v3-std-audio` | 标准 | 带音频输出。 |
| `kling-v3-pro-silent` | Pro | 静音输出。 |
| `kling-v3-pro-audio` | Pro | 带音频输出。 |

## Endpoint

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

## Authentication

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

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | Kling v3 模型 ID。 |
| `prompt` | string | 是 | 主提示词。图生模式下不要与 `extra_body.multi_prompt` 同时传。 |
| `image` | string | 条件必填 | 参考图 URL；如果存在 `last_image`，该字段表示首帧。 |
| `last_image` | string | 条件必填 | 结束帧图 URL。 |
| `aspect_ratio` | string | 否 | `16:9`、`9:16` 或 `1:1`；图生模式不保证一定生效。 |
| `duration` | integer | 否 | 来源范围为 `3` 到 `15` 秒。 |
| `extra_body.negative_prompt` | string | 否 | 不希望出现的内容。 |
| `extra_body.cfg_scale` | number | 否 | 提示词贴合强度，通常越高越贴近提示词。 |
| `extra_body.multi_prompt` | array | 否 | 高级图生模式的多镜头提示词列表。 |
| `extra_body.element_list` | array | 否 | 元素参考列表。 |
| `extra_body.shot_type` | string | 否 | `customize` 或 `intelligent`。 |

## 文生视频示例

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-std-silent",
    "prompt": "A wide cinematic shot of a traveler walking through dusty desert ruins, cloak moving in the wind, slow pullback, natural motion.",
    "aspect_ratio": "16:9",
    "duration": 5,
    "extra_body": {
      "cfg_scale": 0.5,
      "shot_type": "customize",
      "negative_prompt": "blur, low detail"
    }
  }'
```

## 图生视频示例

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-pro-audio",
    "prompt": "The person writes naturally in a notebook, subtle hand detail, small thoughtful pauses, soft classroom depth of field.",
    "image": "https://example.com/start-frame.png",
    "aspect_ratio": "16:9",
    "duration": 6,
    "extra_body": {
      "cfg_scale": 0.6,
      "shot_type": "intelligent",
      "negative_prompt": "artifacts, distortion"
    }
  }'
```

## 首尾帧示例

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-pro-silent",
    "prompt": "The portrait subject slowly turns toward the camera while keeping identity stable and motion natural.",
    "image": "https://example.com/first-frame.png",
    "last_image": "https://example.com/last-frame.png",
    "duration": 8
  }'
```

## 查询任务状态

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

```json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video.generation.job",
  "model": "kling-v3-pro-audio",
  "status": "completed",
  "progress": 100,
  "video_url": "https://example.com/output.mp4"
}
```

## 计费说明

Kling 计费与模型档位、音频模式、输出秒数和生成模式有关。任务结算记录和当前产品价格是最终计费来源。

## 常见错误

- 图生模式下同时传 `prompt` 和 `extra_body.multi_prompt`。
- 请求 `3` 到 `15` 以外的时长。
- 认为图生模式一定遵循 `aspect_ratio`。
- 需要静音输出却使用带音频模型。
- 传入私有媒体 URL。

## 相关页面

- [视频生成概览](/zh-CN/models/video/overview)
- [Veo 3.1 视频生成](/zh-CN/models/video/veo-3-1)
- [数字人口播](/zh-CN/models/avatar/digital-human)

---

# 创建视频任务

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/kling/create-task
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/kling/create-task.md
Description: Kling 创建视频任务接口。

## 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 | 模型名称 | kling-v3-std-silent, kling-v3-std-audio, kling-v3-pro-silent, kling-v3-pro-audio |
| `prompt` | string | Yes | 主提示词 | 图生模式下不能与 `extra_body.multi_prompt` 同时传 |
| `image` | string | Yes | 参考图URL | 传/图生视频, 不传/文生视频（注：若有last_image，则是首帧图） |
| `last_image` | string | Yes | 结束帧图 URL |  |
| `aspect_ratio` | string | Yes | 输出画幅比例 | 允许值：`16:9`、`9:16`、`1:1`，（注：图生视频模式下不保证有效，以输出视频为准） |
| `duration` | string | Yes | 视频时长（秒） | 允许值：`3` 到 `15` |
| `extra_body` | object | Yes |  |  |

## 请求示例

### 文生视频

```json
{
  "model": "kling-v3-std-silent",
  "prompt": "广角电影感镜头，一个旅行者独自穿过满是尘土的沙漠废墟，披风被风吹动，镜头缓慢拉远，动作真实自然，氛围感强。",
  "aspect_ratio": "16:9",
  "duration": 5,
  "extra_body": {
    "cfg_scale": 0.5,
    "shot_type": "customize",
    "negative_prompt": "模糊, 低细节"
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-std-silent",
    "prompt": "广角电影感镜头，一个旅行者独自穿过满是尘土的沙漠废墟，披风被风吹动，镜头缓慢拉远，动作真实自然，氛围感强。",
    "aspect_ratio": "16:9",
    "duration": 5,
    "extra_body": {
        "cfg_scale": 0.5,
        "shot_type": "customize",
        "negative_prompt": "模糊, 低细节"
    }
}'
```
### 图生视频

```json
{
  "model": "kling-v3-pro-audio",
  "prompt": "人物自然地在笔记本上书写，手部动作细腻，头部有轻微思考停顿，景深柔和，课堂环境真实。",
  "image": "https://example.com/start-frame.png",
  "aspect_ratio": "16:9",
  "duration": 6,
  "extra_body": {
    "cfg_scale": 0.6,
    "shot_type": "intelligent",
    "negative_prompt": "伪影, 畸变"
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-pro-audio",
    "prompt": "人物自然地在笔记本上书写，手部动作细腻，头部有轻微思考停顿，景深柔和，课堂环境真实。",
    "image": "https://example.com/start-frame.png",
    "aspect_ratio": "16:9",
    "duration": 6,
    "extra_body": {
        "cfg_scale": 0.6,
        "shot_type": "intelligent",
        "negative_prompt": "伪影, 畸变"
    }
}'
```
### 首尾帧图生视频

```json
{
  "model": "kling-v3-pro-silent",
  "prompt": "肖像人物逐渐转向镜头，身份保持稳定，动作自然。",
  "image": "https://example.com/first-frame.png",
  "last_image": "https://example.com/last-frame.png",
  "duration": 8,
  "extra_body": {
    "cfg_scale": 0.5,
    "shot_type": "customize"
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-pro-silent",
    "prompt": "肖像人物逐渐转向镜头，身份保持稳定，动作自然。",
    "image": "https://example.com/first-frame.png",
    "last_image": "https://example.com/last-frame.png",
    "duration": 8,
    "extra_body": {
        "cfg_scale": 0.5,
        "shot_type": "customize"
    }
}'
```
### 使用multi_prompt的图生视频

```json
{
  "model": "kling-v3-std-audio",
  "image": "https://example.com/source-image.png",
  "duration": 10,
  "extra_body": {
    "multi_prompt": [
      {
        "prompt": "镜头先以中近景开始，人物低头。"
      },
      {
        "prompt": "人物抬头并看向镜头。"
      }
    ],
    "shot_type": "customize"
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-std-audio",
    "image": "https://example.com/source-image.png",
    "duration": 10,
    "extra_body": {
        "multi_prompt": [
            {
                "prompt": "镜头先以中近景开始，人物低头。"
            },
            {
                "prompt": "人物抬头并看向镜头。"
            }
        ],
        "shot_type": "customize"
    }
}'
```
## 响应字段

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


## 响应示例

### 示例 1

```json
{}
```

---

# 查询视频任务

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/kling/query-task
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/kling/query-task.md
Description: Kling 查询视频任务接口。

## Endpoint


```http
GET /v1/videos/{task_id}
```
## Header 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No |  | Bearer &#123;your_token&#125; |
## Path 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `task_id` | string | Yes |  |  |
## 响应字段

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


## 响应示例

### 示例 1

```json
{
  "id": "task_xxxxxxxxxx",
  "model": "kling-v3-std-silent",
  "object": "video",
  "status": "completed",
  "seconds": "8",
  "task_id": "5c9e83c9-1044-46cd-8cff-b2c4cb90efba",
  "progress": 100,
  "video_url": "https://xxxxxx/r/xxxxxx.mp4",
  "created_at": 1774102861000
}
```

---

# 视频生成概览

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 视频生成 API 分类入口。

视频生成文档只覆盖来源菜单中选定的视频页面。

## 包含页面

- [Happy-Horse 视频生成](/zh-CN/models/video/happy-horse)
- [Seedance 2.0 视频生成](/zh-CN/models/video/seedance-2-0)
- [Grok Imagine 视频生成](/zh-CN/models/video/grok-imagine)
- [Veo 3.1 视频生成](/zh-CN/models/video/veo-3-1)
- [Vidu 视频生成](/zh-CN/models/video/vidu)
- [Kling 视频生成](/zh-CN/models/video/kling)
- [Wan 2.6 视频生成](/zh-CN/models/video/wan-2-6)
- [Sora 2 视频生成](/zh-CN/models/video/sora-2)

## 接入建议

视频 API 通常是异步任务。客户端应先提交任务，再轮询状态，任务完成后读取结果 URL 或下载结果内容。

---

# 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 支持文生视频、图生视频、首尾帧、多参考图，以及兼容层的视频编辑或续写模式。新接入应使用新创建任务接口，不再使用来源中的旧版废弃接口。

## 支持模型

| 模型 | 说明 |
| --- | --- |
| `seedance2.0-480p` | 标准档。 |
| `seedance2.0-720p` | 标准档。 |
| `seedance2.0-1080p` | 标准档。 |
| `seedance2.0-4k` | 账号启用时可用的 4K 档。 |
| `seedance2.0-fast-480p` | 快速档。 |
| `seedance2.0-fast-720p` | 快速档。 |
| `seedance2.0-mini-480p` | Mini 档。 |
| `seedance2.0-mini-720p` | Mini 档。 |

## Endpoint

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

部分兼容客户端可能看到 `/v1/videos/generations`，但选定来源页面的创建任务接口为 `/v1/video/generations`。

## Authentication

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

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | Seedance 2.0 模型 ID。 |
| `prompt` | string | 是 | 提示词。只有 `prompt` 时为文生视频。 |
| `duration` | integer/string | 条件必填 | 来源范围为 `5` 到 `15` 中的任意值。 |
| `aspect_ratio` | string | 否 | `9:16`、`1:1` 或 `16:9`。 |
| `image` | string | 条件必填 | 图生视频的单张源图。 |
| `last_image` | string | 条件必填 | 尾帧图，与 `image` 配合使用。 |
| `images` | string[] | 条件必填 | 全能参考模式的参考图 URL，最多 `9` 张。 |
| `videos` | string[] | 条件必填 | 参考视频 URL，最多 `3` 个；每个 `2` 到 `15` 秒，总时长不超过 `15` 秒。 |
| `audios` | string[] | 否 | 参考音频 URL。 |
| `extra_body.generate_audio` | boolean | 否 | 是否生成带音频的视频。 |
| `extra_body.seed` | integer | 否 | 随机种子。 |
| `extra_body.watermark` | boolean/string | 否 | 是否加水印。 |
| `extra_body.camera_fixed` | boolean/string | 否 | 是否固定镜头。 |
| `extra_body.return_last_frame` | boolean/string | 否 | 是否返回最后一帧。 |
| `extra_body.operation` | string | 仅兼容层 | `reference_to_video`、`edit_video`、`extend_video` 或 `first_last_frame`；content-array 风格下会被忽略。 |

## 请求示例

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0-720p",
    "prompt": "A clean commercial product video with slow camera movement, soft reflections, and realistic lighting.",
    "duration": 8,
    "aspect_ratio": "16:9",
    "extra_body": {
      "generate_audio": false,
      "seed": 42,
      "watermark": false
    }
  }'
```

## 多参考图示例

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0-fast-720p",
    "prompt": "Create a fast fashion lookbook clip while preserving the product identity.",
    "images": [
      "https://example.com/model.png",
      "https://example.com/outfit.png"
    ],
    "duration": 6,
    "aspect_ratio": "9:16",
    "extra_body": {
      "generate_audio": true,
      "camera_fixed": false
    }
  }'
```

## 查询任务状态

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

```json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video.generation.job",
  "model": "seedance2.0-720p",
  "status": "completed",
  "progress": 100,
  "video_url": "https://example.com/output.mp4"
}
```

## 计费说明

Seedance 计费与模型档位、输出分辨率、时长、是否使用参考媒体和是否生成音频有关。最终费用以平台结算记录为准。

## 常见错误

- 新接入仍使用旧版废弃创建任务接口。
- 参考图超过 `9` 张。
- 参考视频超过 `3` 个，或总时长超过 `15` 秒。
- `duration` 不在 `5` 到 `15` 范围内。
- 新输入格式和兼容层 `operation` 混用导致路由不明确。

## 相关页面

- [视频生成概览](/zh-CN/models/video/overview)
- [Happy-Horse 视频生成](/zh-CN/models/video/happy-horse)
- [Grok Imagine 视频生成](/zh-CN/models/video/grok-imagine)

---

# 创建视频任务（新）

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/seedance-2-0/create-task
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/seedance-2-0/create-task.md
Description: Seedance 2.0 创建视频任务接口。

## 1. 公共模型

- `seedance2.0-480p`
- `seedance2.0-720p`
- `seedance2.0-1080p`
- `seedance2.0-4k`
- `seedance2.0-fast-480p`
- `seedance2.0-fast-720p`
- `seedance2.0-mini-480p`
- `seedance2.0-mini-720p`

当前对外统一接口：

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

## 2. 设计原则

### 2.1 主推火山原生风格

如果你已经使用火山原生风格的 `content[]`，平台会优先按 `content[]` 处理。

这意味着：

- `content[]` 是主协议
- `type` / `role` 是主语义
- **如果传了 `content[]`，平台会忽略自封装 `extra_body.operation`**

### 2.2 旧字段只做兼容

以下旧字段继续兼容：

- `prompt`
- `image`
- `images`
- `video`
- `videos`
- `audios`
- `last_image`

但这些旧字段只是兼容层，不再是主推方案。

### 2.3 `extra_body.operation` 只保留给兼容层

只有在你**没有传 `content[]`**、而是走旧字段兼容写法时，才建议或要求使用：

- `reference_to_video`
- `edit_video`
- `extend_video`
- `first_last_frame`

如果你已经传了 `content[]`：

- 即使你再传 `extra_body.operation`
- 平台也会忽略它

## 3. 模型与允许值

| 模型 | 类型 | 固定分辨率 | 允许 `duration` | 允许 `aspect_ratio` |
|---|---|---|---|---|
| `seedance2.0-480p` | 标准版 | `480p` | `4` 到 `15` 的整数 | `auto` / `21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16`|
| `seedance2.0-720p` | 标准版 | `720p` | `4` 到 `15` 的整数 | `auto` / `21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16`|
| `seedance2.0-1080p` | 标准版 | `1080p` | `4` 到 `15` 的整数 | `auto` / `21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16`|
| `seedance2.0-fast-480p` | Fast 版 | `480p` | `4` 到 `15` 的整数 | `auto` / `21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16`|
| `seedance2.0-fast-720p` | Fast 版 | `720p` | `4` 到 `15` 的整数 | `auto` / `21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16`|

补充说明：

- 分辨率由模型锁定。
- 不允许通过 `size` 把 `480p` 模型改成 `720p`。
- 如果你要传 `size`：
  - `seedance2.0-480p` / `seedance2.0-fast-480p` 只能传 `480p`
  - `seedance2.0-720p` / `seedance2.0-fast-720p` 只能传 `720p`
  - `seedance2.0-1080p` / 只能传 `1080p`
## 4. 顶层参数说明

### 4.1 必填参数

| 参数 | 类型 | 是否必填 | 允许值 | 说明 |
|---|---|---|---|---|
| `model` | string | 是 | 4 个公共模型之一 | 公共模型名 |
| `duration` | integer | 是 | `4` 到 `15` 的整数 | 视频秒数 |

### 4.2 主推参数

| 参数 | 类型 | 是否必填 | 允许值 | 说明 |
|---|---|---|---|---|
| `content` | array | 推荐必填 | 见下文 | 火山原生风格输入 |
| `aspect_ratio` | string | 否 | `auto` / `21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16` | 宽高比 |
| `prompt` | string | 否 | 任意非空字符串 | 如果你通过 `new-api` 网关，建议同时传 |

### 4.3 兼容参数

| 参数 | 类型 | 是否必填 | 允许值 | 说明 |
|---|---|---|---|---|
| `image` | string / object | 否 | 单张图片 URL | 旧字段兼容 |
| `images` | array | 否 | `1` 到 `9` 张图片 URL | 旧字段兼容 |
| `video` | string | 否 | 单条视频 URL | 旧字段兼容 |
| `videos` | array | 否 | `1` 到 `3` 条视频 URL | 旧字段兼容 |
| `audios` | array | 否 | `1` 到 `3` 条音频 URL | 旧字段兼容 |
| `last_image` | string / object | 否 | 单张图片 URL | 旧字段兼容 |

### 4.4 `extra_body` 参数

| 参数 | 类型 | 是否必填 | 允许值 | 说明 |
|---|---|---|---|---|
| `extra_body.generate_audio` | boolean | 否 | `true` / `false` | 是否生成音频 |
| `extra_body.seed` | integer | 否 | 任意整数 | 随机种子 |
| `extra_body.watermark` | boolean | 否 | `true` / `false` | 是否加水印 |
| `extra_body.camera_fixed` | boolean | 否 | `true` / `false` | 是否固定镜头 |
| `extra_body.service_tier` | string | 否 | 当前平台不枚举固定值 | 透传给上游 |
| `extra_body.execution_expires_after` | integer | 否 | 正整数 | 透传给上游 |
| `extra_body.draft` | boolean | 否 | `true` / `false` | 草稿模式 |
| `extra_body.return_last_frame` | boolean | 否 | `true` / `false` | 是否返回最后一帧 |
| `extra_body.frames` | integer | 否 | 正整数 | 帧数 |
| `extra_body.operation` | string | 仅兼容层使用 | `reference_to_video` / `edit_video` / `extend_video` / `first_last_frame` | **只有旧字段模式才使用；`content[]` 模式下会被忽略** |

## 5. `content[]` 结构

### 5.1 文本项

```json
{
  "type": "text",
  "text": "未来城市，交通发达"
}
```

规则：

- `type` 必须是 `text`
- `text` 必须是非空字符串
- 整个请求至少要有 1 条文本项

### 5.2 图片项

```json
{
  "type": "image_url",
  "url": "https://example.com/ref.png",
  "role": "reference_image"
}
```

图片 `role` 允许值：

- `image`
- `reference_image`
- `first_frame`
- `last_frame`

### 5.3 视频项

```json
{
  "type": "video_url",
  "url": "https://example.com/ref.mp4",
  "role": "reference_video"
}
```

视频 `role` 允许值：

- `reference_video`
- `source_video`

### 5.4 音频项

```json
{
  "type": "audio_url",
  "url": "https://example.com/ref.mp3",
  "role": "reference_audio"
}
```

音频 `role` 允许值：

- `reference_audio`

## 6. `content[]` 模式下各种能力怎么表达

这一节是重点：

- 用户传了 `content[]`
- 平台就按 `content[]` 的 `type + role` 理解能力
- **不要求再额外传 `extra_body.operation`**
- 即使传了，也会被忽略

### 6.1 文生视频

```json
{
  "model": "seedance2.0-720p",
  "content": [
    {
      "type": "text",
      "text": "夜晚的未来城市高架桥，车流穿梭，镜头缓慢推进"
    }
  ],
  "duration": 5,
  "aspect_ratio": "16:9"
}
```

### 6.2 单图生视频

```json
{
  "model": "seedance2.0-fast-720p",
  "content": [
    {
      "type": "text",
      "text": "让产品缓慢旋转，镜头轻推，保持白底电商风格"
    },
    {
      "type": "image_url",
      "url": "https://example.com/product.png",
      "role": "image"
    }
  ],
  "duration": 5,
  "aspect_ratio": "16:9",
  "extra_body": {
    "generate_audio": false,
    "watermark": false
  }
}
```

### 6.3 首尾帧

```json
{
  "model": "seedance2.0-720p",
  "content": [
    {
      "type": "text",
      "text": "从起始图平滑过渡到结束图，保持主体一致"
    },
    {
      "type": "image_url",
      "url": "https://example.com/start.png",
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "url": "https://example.com/end.png",
      "role": "last_frame"
    }
  ],
  "duration": 6,
  "aspect_ratio": "16:9"
}
```

### 6.4 图片参考模式

```json
{
  "model": "seedance2.0-720p",
  "content": [
    {
      "type": "text",
      "text": "保持人物外观一致，生成一段站在白色背景前的展示视频"
    },
    {
      "type": "image_url",
      "url": "https://example.com/ref-1.png",
      "role": "reference_image"
    },
    {
      "type": "image_url",
      "url": "https://example.com/ref-2.png",
      "role": "reference_image"
    }
  ],
  "duration": 8,
  "aspect_ratio": "9:16"
}
```

### 6.5 全能参考模式

```json
{
  "model": "seedance2.0-720p",
  "content": [
    {
      "type": "text",
      "text": "保持产品外观一致，参考动作和音频节奏，生成一段电商演示视频"
    },
    {
      "type": "image_url",
      "url": "https://example.com/product.png",
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "url": "https://example.com/motion-guide.mp4",
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "url": "https://example.com/music-guide.mp3",
      "role": "reference_audio"
    }
  ],
  "duration": 10,
  "aspect_ratio": "16:9",
  "extra_body": {
    "generate_audio": true,
    "seed": 88,
    "watermark": false
  }
}
```

### 6.6 视频编辑

```json
{
  "model": "seedance2.0-720p",
  "content": [
    {
      "type": "text",
      "text": "把这段视频改成简洁明亮的电商展示风格"
    },
    {
      "type": "video_url",
      "url": "https://example.com/source.mp4",
      "role": "source_video"
    }
  ],
  "duration": 5,
  "aspect_ratio": "16:9",
  "extra_body": {
    "watermark": false
  }
}
```

### 6.7 视频延长

```json
{
  "model": "seedance2.0-720p",
  "content": [
    {
      "type": "text",
      "text": "延续当前镜头运动和场景风格，保持主体一致"
    },
    {
      "type": "video_url",
      "url": "https://example.com/source.mp4",
      "role": "source_video"
    }
  ],
  "duration": 5,
  "aspect_ratio": "16:9",
  "extra_body": {
    "watermark": false
  }
}
```

## 7. 旧字段兼容写法

这部分只给旧客户端或旧网关兼容使用。

### 7.1 单图兼容写法

```json
{
  "model": "seedance2.0-fast-480p",
  "prompt": "让产品轻微旋转",
  "image": "https://example.com/product.png",
  "duration": 5,
  "aspect_ratio": "16:9"
}
```

### 7.2 首尾帧兼容写法

```json
{
  "model": "seedance2.0-720p",
  "prompt": "从起始图平滑过渡到结束图",
  "image": "https://example.com/start.png",
  "last_image": "https://example.com/end.png",
  "duration": 6,
  "aspect_ratio": "16:9",
  "extra_body": {
    "operation": "first_last_frame"
  }
}
```

### 7.3 多模态参考兼容写法

```json
{
  "model": "seedance2.0-720p",
  "prompt": "生成一段带参考动作和音频节奏的视频",
  "images": [
    "https://example.com/ref-1.png"
  ],
  "videos": [
    "https://example.com/ref.mp4"
  ],
  "audios": [
    "https://example.com/ref.mp3"
  ],
  "duration": 8,
  "aspect_ratio": "16:9",
  "extra_body": {
    "operation": "reference_to_video"
  }
}
```

### 7.4 旧字段视频编辑 / 延长兼容写法

```json
{
  "model": "seedance2.0-720p",
  "prompt": "把这段视频改成简洁明亮的电商展示风格",
  "video": "https://example.com/source.mp4",
  "duration": 5,
  "aspect_ratio": "16:9",
  "extra_body": {
    "operation": "edit_video"
  }
}
```

## 8. 本站通过new-api调用时

强烈建议同时传顶层 `prompt` 和 `content[0].text`。

原因：

- 因采用openai风格，所以 `prompt` 字段必传，否则请求不能到达火山引擎服务

推荐兼容写法：

```json
{
  "model": "seedance2.0-fast-480p",
  "prompt": "未来城市，交通发达",
  "content": [
    {
      "type": "text",
      "text": "未来城市，交通发达"
    }
  ],
  "duration": 5,
  "aspect_ratio": "16:9",
  "extra_body": {
    "generate_audio": false,
    "watermark": false
  }
}
```

## 9. 常见错误

### 错误 1：通过 `new-api` 只传 `content[]`，不传顶层 `prompt`

现象：

- 前置层直接报 `prompt is required`


解决：

- 顶层 `prompt` 和 `content[0].text` 同时传

### 错误 2：`content[]` 里 `role` 不合法

图片 `role` 只允许：

- `image`
- `reference_image`
- `first_frame`
- `last_frame`

视频 `role` 只允许：

- `reference_video`
- `source_video`

音频 `role` 只允许：

- `reference_audio`

### 错误 3：旧字段兼容模式没传 `operation`

说明：

- 旧字段本身表达力不足
- 平台需要你显式补语义

例如：

- `video` 兼容模式下要配 `edit_video` 或 `extend_video`
- `videos / audios` 兼容模式下要配 `reference_to_video`

### 错误 4：尝试覆盖分辨率

说明：

- 模型分辨率由公共模型名锁定

例如：

- `seedance2.0-fast-480p` 不能改成 `720p`
- `seedance2.0-720p` 不能改成 `480p`

## 10. 响应说明

提交后会返回统一异步任务对象，例如：

```json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video.generation.job",
  "model": "seedance2.0-720p",
  "status": "queued",
  "raw_status": "PENDING",
  "progress": 0,
  "created_at": 1773980459,
  "video_url": null
}
```

之后轮询：

- `GET /v1/videos/generations/{task_id}`

直到状态变成：

- `completed`
- 或 `failed`

## 11. 最终建议

一句话总结：

- **如果你会写 `content[]`，就按火山原生风格写，不用再传 `extra_body.operation`**
- **如果你还在用旧字段兼容写法，再传 `extra_body.operation`**
- **如果通过 `new-api`，建议同时传顶层 `prompt` 和 `content[0].text`**

## 接口参数与示例

### 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 | 模型名称 |  |
| `prompt` | string | Yes | 提示词 | 只有 `prompt` -&gt; 文生视频 |
| `image` | string | Yes | 单张源图 | 图生视频 |
| `last_image` | string | Yes | 尾帧图 | 首尾帧和image配合使用 |
| `images` | string | Yes | 参考图 URL 数组 | 多图参考输入, '全能参考模式', 图片最多9张 |
| `audios` | string | Yes | 参考音频 URL 数组 | 用于全能参考模式, 最多 3 个，每个 2~15s，总时长 &lt;= 15s |
| `videos` | string | Yes | 参考视频 URL 数组 | 用于全能参考模式, 最多 3 个，每个 2~15s，总时长 &lt;= 15s |
| `duration` | string | Yes | 秒数 | 5到15中的任意值 |
| `aspect_ratio` | string | Yes | 比例 | `9:16`、`1:1`、`16:9` |
| `extra_body` | object | No | 扩展 |  |

### 请求示例

#### 示例

```json
{
  "model": "string",
  "prompt": "string",
  "image": "string",
  "last_image": "string",
  "images": "string",
  "audios": "string",
  "videos": "string",
  "duration": "string",
  "aspect_ratio": "string",
  "extra_body": {
    "generate_audio": true,
    "seed": "string",
    "watermark": "string",
    "camera_fixed": "string",
    "service_tier": "string",
    "execution_expires_after": "string",
    "draft": "string",
    "return_last_frame": "string",
    "frames": "string",
    "operation": "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",
    "last_image": "string",
    "images": "string",
    "audios": "string",
    "videos": "string",
    "duration": "string",
    "aspect_ratio": "string",
    "extra_body": {
        "generate_audio": true,
        "seed": "string",
        "watermark": "string",
        "camera_fixed": "string",
        "service_tier": "string",
        "execution_expires_after": "string",
        "draft": "string",
        "return_last_frame": "string",
        "frames": "string",
        "operation": "string"
    }
}'
```
### 响应字段

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


### 响应示例

#### 示例 1

```json
{
  "id": "task_xxx",
  "error": null,
  "model": "seedance2.0-720p",
  "object": "video.generation.job",
  "result": {
    "outputs": [
      "https://xxx.aijisu.cn/video/xxxx.mp4"
    ],
    "video_url": "https://xxx.aijisu.cn/video/xxx.mp4"
  },
  "status": "completed",
  "task_id": "task_xxxxx",
  "progress": 100,
  "video_url": "https://xxx.aijisu.cn/video/xxx.mp4",
  "created_at": 1774405050,
  "raw_status": "COMPLETED"
}
```

---

# 创建视频任务（老-已废弃）

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/seedance-2-0/legacy-create-task
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/seedance-2-0/legacy-create-task.md
Description: Seedance 2.0 旧版创建视频任务接口。

## 说明

| 输入形态 | 实际能力 |
|---|---|
| 只有 `prompt` | `文生视频` |
| 只传 `image` | `图生视频` |
| 同时传 `image` 和 `last_image` | `首尾帧` |
| 传 `images` / `videos` / `audios` 任意一个或组合 | `全能参考模式` |

## 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 | 模型名称 | jisudance2.0-480p, jisudance2.0-720p, jisudance2.0-fast-480p, jisudance2.0-fast-720p |
| `prompt` | string | Yes | 提示词 | 只有 `prompt` -&gt; 文生视频 |
| `image` | string | Yes | 单张源图 | 图生视频 |
| `last_image` | string | Yes | 尾帧图 | 首尾帧和image配合使用 |
| `images` | string | Yes | 参考图 URL 数组 | 多图参考输入, '全能参考模式', 图片最多9张 |
| `audios` | string | Yes | 参考音频 URL 数组 | 用于全能参考模式, 最多 3 个，每个 2~15s，总时长 &lt;= 15s |
| `videos` | string | Yes | 参考视频 URL 数组 | 用于全能参考模式, 最多 3 个，每个 2~15s，总时长 &lt;= 15s |
| `duration` | string | Yes | 秒数 | 5到15中的任意值 |
| `aspect_ratio` | string | Yes | 比例 | `9:16`、`1:1`、`16:9` |
| `extra_body` | object | No | 扩展 |  |

## 请求示例

### test

```json
{
  "model": "jisudance2.0-480p",
  "prompt": "自然过渡",
  "duration": 5,
  "aspect_ratio": "9:16"
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jisudance2.0-480p",
    "prompt": "自然过渡",
    "duration": 5,
    "aspect_ratio": "9:16"
}'
```
## 响应字段

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


## 响应示例

### 示例 1

```json
{
  "id": "task_xxx",
  "error": null,
  "model": "jisudance2.0-720p",
  "object": "video.generation.job",
  "result": {
    "outputs": [
      "https://xxx.aijisu.cn/video/xxxx.mp4"
    ],
    "video_url": "https://xxx.aijisu.cn/video/xxx.mp4"
  },
  "status": "completed",
  "task_id": "task_xxxxx",
  "progress": 100,
  "video_url": "https://xxx.aijisu.cn/video/xxx.mp4",
  "created_at": 1774405050,
  "raw_status": "COMPLETED"
}
```

---

# 查询视频任务

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/seedance-2-0/query-task
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/seedance-2-0/query-task.md
Description: Seedance 2.0 查询视频任务接口。

## Endpoint


```http
GET /v1/videos/{task_id}
```
## Header 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No |  | Bearer &#123;your_token&#125; |
## Path 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `task_id` | string | Yes |  |  |
## 响应字段

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


## 响应示例

### 示例 1

```json
{
  "id": "task_xxxxxxxxxx",
  "model": "jisudance-2.0-720p",
  "object": "video",
  "status": "completed",
  "seconds": "8",
  "task_id": "5c9e83c9-1044-46cd-8cff-b2c4cb90efba",
  "progress": 100,
  "video_url": "https://xxxxxx/r/xxxxxx.mp4",
  "created_at": 1774102861000
}
```

---

# 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 模型生成视频。

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

## 查询任务状态

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

```json
{
  "id": "gen_xxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "sora2-portrait-12s",
  "status": "completed",
  "progress": 100,
  "video_url": "https://example.com/output.mp4",
  "seconds": "12"
}
```

## 计费说明

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 创建视频生成任务接口。

## 说明

新增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"
}
```

---

# 原生 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 格式接口。

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

---

# 查询视频生成任务

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/sora-2/query-task
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/sora-2/query-task.md
Description: Sora 2 查询视频生成任务接口。

## Endpoint


```http
GET /v1/videos/{task_id}
```
## Header 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No |  | Bearer &#123;your_token&#125; |
## Path 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `task_id` | string | Yes |  |  |
## 响应字段

| Field | Type | Required | Title | Description |
| --- | --- | --- | --- | --- |
| `id` | string | Yes | 任务ID |  |
| `model` | string | Yes | 模型名称 |  |
| `object` | string | Yes | 任务类型 |  |
| `prompt` | string | Yes | 提示词 |  |
| `status` | string | Yes | 状态 | queued: 排队中, in_progress: 生成中, completed: 已完成, failed: 失败 |
| `duration` | string | Yes | 任务耗时 |  |
| `metadata` | string | Yes | // |  |
| `progress` | string | Yes | 进度 |  |
| `video_url` | string | Yes | 视频URL |  |
| `created_at` | string | Yes | 创建时间 |  |
| `thumbnail_url` | string | Yes | 缩略图 |  |

## 响应示例

### 示例 1

```json
{
  "id": "gen_xxxxxxx",
  "model": "sora2",
  "object": "video.generation.job",
  "prompt": "xxxxxxxxxxxxxx",
  "status": "completed",
  "duration": 89,
  "metadata": {
    "total_time": 89.550817778,
    "predict_time": 89.537048777
  },
  "progress": 100,
  "video_url": "https://xx.xxxxxx.cn/xxxx/xxxxxxxxxxxxxxxxxxxxxxxx.mp4",
  "created_at": 1770405484,
  "thumbnail_url": 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 模型生成视频。

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

## 查询任务状态

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

```json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video.generation.job",
  "model": "veo3.1-video-1080p",
  "status": "completed",
  "progress": 100,
  "video_url": "https://example.com/output.mp4"
}
```

## 计费说明

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 创建视频生成任务接口。

## 说明

| 公共模型名 | 当前支持的视频生成能力 |
|---|---|
| `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
{}
```

---

# 查询视频任务

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/veo-3-1/query-task
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/veo-3-1/query-task.md
Description: Veo 3.1 查询视频任务接口。

## Endpoint


```http
GET /v1/videos/{task_id}
```
## Header 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No |  | Bearer &#123;your_token&#125; |
## Path 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `task_id` | string | Yes |  |  |
## 响应字段

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


## 响应示例

### 示例 1

```json
{
  "id": "task_xxxxxxxxxx",
  "model": "viduq3p-1080p",
  "object": "video",
  "status": "completed",
  "seconds": "8",
  "task_id": "5c9e83c9-1044-46cd-8cff-b2c4cb90efba",
  "progress": 100,
  "video_url": "https://xxxxxx/r/xxxxxx.mp4",
  "created_at": 1774102861000
}
```

---

# Vidu 视频生成

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: Vidu 来源文档。

视频生成用户调用文档

更新时间：2026-06-03

本文按当前线上口径整理，适用于本站 Vidu Q3 Pro / Q3 Turbo 视频模型调用。用户只需要使用本站展示的稳定模型名和视频任务接口，不要直接依赖上游或内部路由字段。

## 1. 可用模型

| 模型 | 系列 | 文生视频 | 单图生视频 | 首尾帧 | 多参考图 |
| --- | --- | --- | --- | --- | --- |
| `viduq3p-540p` | Q3 Pro | 支持 | 支持 | 支持，使用 `image` + `last_image` | 支持，使用 `reference_image_urls`，最多 4 张 |
| `viduq3p-720p` | Q3 Pro | 支持 | 支持 | 支持，使用 `image` + `last_image` | 支持，使用 `reference_image_urls`，最多 4 张 |
| `viduq3p-1080p` | Q3 Pro | 支持 | 支持 | 支持，使用 `image` + `last_image` | 支持，使用 `reference_image_urls`，最多 4 张 |
| `viduq3t-540p` | Q3 Turbo | 支持 | 支持 | 支持，使用 `image` + `last_image` | 支持，使用 `reference_image_urls`，最多 4 张 |
| `viduq3t-720p` | Q3 Turbo | 支持 | 支持 | 支持，使用 `image` + `last_image` | 支持，使用 `reference_image_urls`，最多 4 张 |
| `viduq3t-1080p` | Q3 Turbo | 支持 | 支持 | 支持，使用 `image` + `last_image` | 支持，使用 `reference_image_urls`，最多 4 张 |

说明：

- 当前线上模型列表只包含上表 6 个模型。
- 创建任务时只使用上表展示的模型名。
- Q3 Turbo 当前只按文生或单图生使用；多参考图请使用 Q3 Pro。

## 2. 接口

### 2.1 创建视频任务

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

请求头：

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

### 2.2 查询视频任务

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

兼容查询接口：

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

## 3. 参数说明

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 使用上表 6 个模型之一 |
| `prompt` | string | 是 | 视频生成提示词 |
| `duration` | integer/string | 是 | 输出视频秒数，当前建议传 `1-16` 的整数 |
| `aspect_ratio` | string | 文生建议传 | 输出画幅比例，常用 `16:9`、`9:16`、`1:1` |
| `image` | string | 单图/首尾帧必填 | 公开可访问的图片 URL；单图生视频时只传这一张图 |
| `last_image` | string | 首尾帧必填 | 尾帧图片 URL；和 `image` 配合使用，保持旧版文档字段不变 |
| `reference_image_urls` | string[] | 多参考图必填 | Q3 Pro 多参考图字段，最多 4 张公开可访问图片 URL |
| `extra_body.audio` | boolean | 否 | 是否生成声音；不需要声音时传 `false` |
| `extra_body.seed` | integer | 否 | 随机种子 |
| `extra_body.bgm` | boolean | 否 | 是否开启背景音乐；不需要时传 `false` |

字段使用约束：

- 文生视频：只传 `prompt`、`model`、`duration`，可选 `aspect_ratio`。
- 单图生视频：传 `image`，不要同时传多图数组。
- 首尾帧：传 `image` + `last_image`，不要把首尾帧塞进 `images` 数组。
- 多参考图：传 `reference_image_urls`，不要同时传 `images`、`image_urls` 或重复传同一批图片。
- `reference_image_urls` 只推荐用于 `viduq3p-*`，不要用于 `viduq3t-*`。

## 4. 请求示例

以下示例中的 `{BASE_URL}` 可替换为 `https://api.aijisu.cn`。

### 4.1 文生视频

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3p-720p",
    "prompt": "电影感航拍镜头，日出时分掠过未来海滨城市，光线柔和，镜头缓慢推进。",
    "aspect_ratio": "16:9",
    "duration": 5,
    "extra_body": {
      "audio": false,
      "seed": 42,
      "bgm": false
    }
  }'
```

### 4.2 单图生视频

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3t-540p",
    "prompt": "人物缓慢抬头并看向镜头，动作自然，镜头轻微前推。",
    "image": "https://example.com/source.png",
    "duration": 5,
    "extra_body": {
      "seed": 42
    }
  }'
```

### 4.3 首尾帧生视频

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3p-720p",
    "prompt": "人物从正面自然转向侧面，身份保持稳定，动作连贯。",
    "image": "https://example.com/head.png",
    "last_image": "https://example.com/tail.png",
    "duration": 6,
    "extra_body": {
      "seed": 42
    }
  }'
```

### 4.4 多参考图生视频

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3p-720p",
    "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"
    ],
    "aspect_ratio": "16:9",
    "duration": 5,
    "extra_body": {
      "audio": false,
      "seed": 42,
      "bgm": false
    }
  }'
```

## 5. 响应示例

创建任务成功时：

```json
{
  "id": "task_xxxxx",
  "task_id": "task_xxxxx",
  "object": "video.generation.job",
  "model": "viduq3p-720p",
  "status": "queued",
  "progress": 0,
  "created_at": 1774507626
}
```

查询任务完成时：

```json
{
  "id": "task_xxxxx",
  "task_id": "task_xxxxx",
  "object": "video.generation.job",
  "model": "viduq3p-720p",
  "status": "completed",
  "progress": 100,
  "video_url": "https://example.com/output.mp4",
  "created_at": 1774507626
}
```

常见状态：

| 状态 | 含义 |
| --- | --- |
| `queued` | 排队中 |
| `in_progress` | 生成中 |
| `completed` | 已完成 |
| `failed` | 失败 |

## 6. 常见错误

### 6.1 把多张图放进 `images`

不要这样传：

```json
{
  "model": "viduq3p-720p",
  "prompt": "首尾帧变化",
  "images": [
    "https://example.com/head.png",
    "https://example.com/tail.png"
  ],
  "duration": 6
}
```

当前线上口径下，多图 `images` 可能被路由为不匹配的 reference 分支。首尾帧请使用 `image` + `last_image`；多参考图请使用 `reference_image_urls`。

### 6.2 Q3 Turbo 使用多参考图

不要对 `viduq3t-*` 传 `reference_image_urls`。Q3 Turbo 当前只按文生或单图生使用。

### 6.3 使用未展示的模型名

创建任务时只使用本文模型表中的 6 个模型名。未在模型表中展示的模型名不要作为 `model` 参数传入。

## 7. 与旧版文档的主要区别

| 项目 | 旧版文档口径 | 当前口径 |
| --- | --- | --- |
| 文生视频说明 | `prompt` 字段描述为“只传 prompt 视为图生视频” | 只传 `prompt` 应为文生视频 |
| 必填字段 | OpenAPI schema 把 `image`、`last_image`、`reference_image_urls`、`aspect_ratio`、`extra_body` 等都列为必填 | 只有 `model`、`prompt`、`duration` 基础必填；图片字段按场景条件必填 |
| 首尾帧字段 | 使用 `image` + `last_image` | 保持 `image` + `last_image`，旧用户不需要改字段名 |
| 首尾帧传图方式 | 未说明不要传 `images` | 明确不要把首尾帧放进 `images` 数组；`images` 多图不是首尾帧写法 |
| 多参考图模型 | 旧版示例包含未在当前模型表展示的模型名 | 当前使用 `viduq3p-*` + `reference_image_urls` |
| 多参考图数量 | 未说明上限 | 当前建议最多 4 张 |
| Q3 Turbo 多参考图 | 未限制 | 当前 `viduq3t-*` 不用于多参考图 |
| 示例模型 | 旧版示例包含未在当前模型表展示的模型名 | 当前用户文档只保留 6 个线上可用模型 |
| `duration` 类型 | schema 写 string，示例传 number | 当前建议传整数；兼容数字字符串 |
| `extra_body.bgm` 类型 | schema 写 string | 当前按 boolean 使用 |
| 查询任务 | 旧文档只展示创建接口 | 当前补充 `GET /v1/video/generations/{task_id}` 和兼容 `GET /v1/videos/{task_id}` |

---

# 创建视频任务（旧）

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/vidu/create-task-old
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/vidu/create-task-old.md
Description: Vidu 旧版创建视频任务接口。

## 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 | 模型名称 | viduq3p-540p, viduq3p-720p, viduq3p-1080p, viduq3t-540p, viduq3t-720p, viduq3t-1080p |
| `prompt` | string | Yes | 提示词 | 只传prompt视为图生视频 |
| `image` | string | Yes | 参考图/首帧参考图 | 只传image, 不传last_image, 视为图生视频 |
| `reference_image_urls` | array | Yes | mix模式参考图 | 只有 mix模式生效，字符串数组：示例：[, "https://example.com/ref-1.png",  "https://example.com/ref-2.png", ] |
| `last_image` | string | Yes | 尾帧参考图 | 同时传入image和last_image视为首尾帧生视频，不支持只传入last_image |
| `aspect_ratio` | string | Yes | 输出画幅比例 | 文生视频有效；图生视频也可传入，但不保证影响结果 |
| `duration` | string | Yes | 视频时长（秒） | 允许值：`1` 到 `16` |
| `extra_body` | object | Yes | 扩展参数 |  |

## 请求示例

### 文生视频

```json
{
  "model": "viduq3p-720p",
  "prompt": "电影感航拍镜头，日出时分掠过未来海滨城市，光线柔和，镜头缓慢推进。",
  "aspect_ratio": "16:9",
  "duration": 5,
  "extra_body": {
    "audio": false,
    "seed": 42,
    "bgm": false
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3p-720p",
    "prompt": "电影感航拍镜头，日出时分掠过未来海滨城市，光线柔和，镜头缓慢推进。",
    "aspect_ratio": "16:9",
    "duration": 5,
    "extra_body": {
        "audio": false,
        "seed": 42,
        "bgm": false
    }
}'
```
### 单图生视频

```json
{
  "model": "viduq3t-540p",
  "prompt": "人物缓慢抬头并看向镜头，动作自然，镜头轻微前推。",
  "image": "https://example.com/source.png",
  "duration": 5,
  "extra_body": {
    "seed": 42
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3t-540p",
    "prompt": "人物缓慢抬头并看向镜头，动作自然，镜头轻微前推。",
    "image": "https://example.com/source.png",
    "duration": 5,
    "extra_body": {
        "seed": 42
    }
}'
```
### 首尾帧生视频

```json
{
  "model": "viduq3p-1080p-offpeak",
  "prompt": "人物从正面自然转向侧面，身份保持稳定，动作连贯。",
  "image": "https://example.com/head.png",
  "last_image": "https://example.com/tail.png",
  "duration": 6
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3p-1080p-offpeak",
    "prompt": "人物从正面自然转向侧面，身份保持稳定，动作连贯。",
    "image": "https://example.com/head.png",
    "last_image": "https://example.com/tail.png",
    "duration": 6
}'
```
### 参考图生视频

```json
{
  "model": "viduq3p-mix-720p",
  "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"
  ],
  "aspect_ratio": "16:9",
  "duration": 5,
  "extra_body": {
    "audio": false,
    "seed": 42
  }
}
```

```bash
curl -X POST "{BASE_URL}/v1/video/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "viduq3p-mix-720p",
  "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"
  ],
  "aspect_ratio": "16:9",
  "duration": 5,
  "extra_body": {
    "audio": false,
    "seed": 42
  }
}'
```
## 响应字段

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


## 响应示例

### 成功

```json
{
  "id": "task_xxxxx",
  "task_id": "task_xxxxx",
  "object": "video.generation.job",
  "model": "viduq3p-540p",
  "status": "queued",
  "progress": 0,
  "created_at": 1774507626
}
```

---

# 查询视频任务

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/vidu/query-task
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/vidu/query-task.md
Description: Vidu 查询视频任务接口。

## Endpoint


```http
GET /v1/videos/{task_id}
```
## Header 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No |  | Bearer &#123;your_token&#125; |
## Path 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `task_id` | string | Yes |  |  |
## 响应字段

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


## 响应示例

### 示例 1

```json
{
  "id": "task_xxxxxxxxxx",
  "model": "viduq3p-1080p",
  "object": "video",
  "status": "completed",
  "seconds": "8",
  "task_id": "5c9e83c9-1044-46cd-8cff-b2c4cb90efba",
  "progress": 100,
  "video_url": "https://xxxxxx/r/xxxxxx.mp4",
  "created_at": 1774102861000
}
```

---

# 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 模型生成视频。

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

## 查询任务状态

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

```json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video.generation.job",
  "model": "wan2.6-video-1080p",
  "status": "completed",
  "progress": 100,
  "video_url": "https://example.com/output.mp4"
}
```

## 计费说明

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 创建视频生成任务接口。

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

---

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

---

# 查询视频任务

Locale: zh-CN
URL: https://docs.uniall.ai/zh-CN/models/video/wan-2-6/query-task
Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/wan-2-6/query-task.md
Description: Wan 2.6 查询视频任务接口。

## Endpoint


```http
GET /v1/videos/{task_id}
```
## Header 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `Authorization` | string | No |  | Bearer &#123;your_token&#125; |
## Path 参数

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `task_id` | string | Yes |  |  |
## 响应字段

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


## 响应示例

### 示例 1

```json
{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxx",
  "error": null,
  "model": "wan2.6-video-1080p",
  "object": "video.generation.job",
  "result": {
    "outputs": [
      "https://xxxxxxx.cn/predictions/xxxxx/1.mp4"
    ],
    "video_url": "https://xxxxxxx.cn/predictions/xxxxx/1.mp4"
  },
  "status": "completed",
  "task_id": "xxxxxxxxxxxxxxxxxxxxxxx",
  "progress": 100,
  "video_url": "https://xxxxxxx.cn/predictions/xxxxx/1.mp4",
  "created_at": 1773984104,
  "raw_status": "COMPLETED"
}
```

---

# 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 创建视频任务接口。

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

---

# 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 视频编辑接口。

## 说明

它支持两种工作模式：

- `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
{}
```