# UniAll Docs Full Markdown Generated from the UniAll documentation source for AI and LLM consumption. Website: https://docs.uniall.ai/ Index: https://docs.uniall.ai/llms.txt --- # Documentation Overview Locale: en URL: https://docs.uniall.ai/ Source: site-docs/overview.md Description: UniAll developer documentation scope, API style, and selected model documentation structure. UniAll Docs is the developer reference for the selected API and model pages migrated from the current Apifox documentation scope. The source menu is used as an inventory only. The new site normalizes naming, routes, examples, and page structure so the docs read as one UniAll product surface. The current public documentation is intentionally narrow. It includes the selected balance, model listing, image, video, audio, and digital-human pages from the approved scope. Standalone quick start, authentication, billing policy, error-code catalog, changelog, and generated API reference pages are not part of this phase. ## Included Documentation | Area | Current pages | Main purpose | | --- | --- | --- | | Account | [Query Balance](/balance) | Confirm account and API key quota before submitting tasks. | | Model index | [Models](/models) | List model documentation by capability and describe the model-list endpoint. | | Image generation | [Async Image Generation](/models/image/async-image-generation), Seedream, GPT-Image-2, Nano Series | Use async tasks or synchronous image endpoints depending on the model page. | | Video generation | Happy-Horse, Seedance 2.0, [Grok Imagine](/models/video/grok-imagine), Veo 3.1, Vidu, Kling, Wan 2.6, Sora 2 | Submit video tasks, poll status, and retrieve completed videos. | | Audio and music | Music Generation, Speech Synthesis | Generate music or speech with model-specific request fields. | | Digital humans | Digital Human Video | Generate narrated digital-human videos. | ## API Style Most model pages use a task-based flow: 1. Submit a task with `Authorization: Bearer sk-***`. 2. Store the returned task ID. 3. Poll the task endpoint every 2 to 5 seconds. 4. Stop polling when the task reaches a terminal status such as `succeeded`, `completed`, or `failed`. 5. Use the returned result URL or content endpoint to download the final asset. Balance and model listing pages are synchronous API concept pages. They return immediately and do not require polling. ## Common Conventions | Convention | Rule | | --- | --- | | Base URL | `https://api.uniall.ai`; `{BASE_URL}` in examples means this value. | | Authentication | Use `Authorization: Bearer sk-***` unless a page documents a compatibility-specific header. | | Request examples | `curl` is the primary example format. | | Model IDs | Use exact model IDs in JSON, such as `grok-imagine` and `gpt-image-2`. | | Result URLs | Treat returned URLs as generated assets; do not assume they are permanent unless the product contract says so. | | Billing | Page-level billing notes explain what affects cost, but exact prices should come from the current product pricing surface. | ## Language And AI-Readable Docs English is the default locale at `/`. Chinese is available under `/zh-CN/`. Code examples, JSON keys, endpoint paths, and model IDs stay identical across languages. The site also publishes AI-readable indexes: - [`/llms.txt`](/llms.txt) - [`/llms-full.txt`](/llms-full.txt) Use these files when an agent or external AI tool needs a compact view of the current documentation surface. ## Related Pages - [Query Balance](/balance) - [Models](/models) - [Async Image Generation](/models/image/async-image-generation) - [Grok Imagine Video Generation](/models/video/grok-imagine) --- # Query Balance Locale: en URL: https://docs.uniall.ai/balance Source: site-docs/balance.md Description: Query account balance and credit usage. ## 1. Endpoint Description Endpoint standard API key query: - API Key user ID - user account balance - display balance converted by site configuration - quota information for the current API key Endpointuse `sk-...` API Key call, requires usingr. --- ## 2. Details | | | | --- | --- | | Method | `GET` | | Path | `/api/usage/balance` | | Authentication | `Authorization: Bearer sk-xxx` | | Content-Type |, pass | --- ## 3. Request Examples ```bash curl -X GET "https://api.aijisu.cn/api/usage/balance" \ -H "Authorization: Bearer sk-your-api-key" ``` --- ## 4. SuccessResponse Examples ```json { "success": true, "message": "", "data": { "object": "api_key_balance", "user_id": 1, "balance": { "quota": 1000000, "amount": 14.6, "display_amount": "¥14.60", "quota_per_unit": 500000, "quota_display_type": "CNY", "currency_symbol": "¥", "exchange_rate": 7.3 }, "token": { "id": 12, "name": "my-key", "remain_quota": 100000, "used_quota": 5000, "total_quota": 105000, "unlimited_quota": false, "expired_time": -1, "status": 1, "model_limits_enabled": false, "model_limits": {} } } } ``` --- ## 5. responsesParameter Reference ### 5.1 Parameters | Parameters | Type | Note | | --- | --- | --- | | `success` | boolean | WhetherSuccess | | `message` | string | responses, Success string | | `data` | object | responses | ### 5.2 `data` Parameters | Parameters | Type | Note | | --- | --- | --- | | `data.object`| string | object type,`api_key_balance` | | `data.user_id` | number | API Key user ID | | `data.balance` | object | user account balance | | `data.token` | object | API Key quota | ### 5.3 `data.balance` Parameters | Parameters | Type | Note | | --- | --- | --- | | `data.balance.quota` | number | useraccount quota, quota | | `data.balance.amount` | number | balance | | `data.balance.display_amount` | string | format, | | `data.balance.quota_per_unit`| number | quota,`500000` `500000 quota = 1 USD` | | `data.balance.quota_display_type`| string | balance Type, value:`USD`, `CNY`, `CUSTOM`, `TOKENS` | | `data.balance.currency_symbol`| string |,`$`, `¥`; Type `TOKENS` string | | `data.balance.exchange_rate`| number | use;`USD` `1`, `CNY`, `CUSTOM` | ### 5.4 `data.token` Parameters | Parameters | Type | Note | | --- | --- | --- | | `data.token.id` | number | API Key ID | | `data.token.name` | string | API Key name | | `data.token.remain_quota` | number | API Key balance | | `data.token.used_quota` | number | API Key usequota | | `data.token.total_quota`| number | API Key quota,`remain_quota + used_quota` | | `data.token.unlimited_quota` | boolean | API Key Whether quota | | `data.token.expired_time`| number | API Key;`-1` | | `data.token.status`| number | API Key Status;`1` | | `data.token.model_limits_enabled` | boolean | API Key Whether Modelconstraints | | `data.token.model_limits`| object | API Key Modelconstraints; constraints object `{}` | --- --- ## 6. Errorresponses ### 6.1 pass API Key HTTP Status code: `401` ```json { "success": false, "message": "Token not provided" } ``` ### 6.2 API Key or HTTP Status code: `401` ```json { "success": false, "message": "Invalid token" } ``` ### 6.3 API Key HTTP Status code: `403` ```json { "success": false, "message": "Token invalid" } ``` --- ## 7. callNote - use `Authorization: Bearer sk-xxx` pass in API Key. - return Yes API Key user accountbalance, Yesupstream balance. - Endpoint return API Key string. - API Key querybalance. - API Key orquota, querybalance, Key user. - `amount` and `display_amount` balance. --- # Models Locale: en URL: https://docs.uniall.ai/models Source: site-docs/models/index.md Description: Supported UniAll model documentation grouped by capability, with the model-list endpoint. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. The Models page is the normalized entry point for the selected UniAll model documentation. It groups pages by capability instead of preserving the original Apifox menu order. Use the model-list endpoint when you need to discover the models available to the current API key at runtime. ## Capability Categories | Category | Pages | Typical endpoint | | --- | --- | --- | | Image Generation | Async Image Generation, Seedream, Seedream 5.0 Pro, GPT-Image-2, GPT-Image-2.5, GPT-Image-2.6, Qwen Image, Nano Series (including Nano Banana 2.1), Kling | `POST /v1/images/tasks`, `POST /v1/images/generations`, or `POST /v1/images/edits` | | Video Generation | Happy Horse, Seedance 2.0, Seedance 2.5, Grok Imagine, Veo 3.1, Gemini Omni Flash Preview, Vidu Q3, Hailuo, MiniMax H3 / H3 Max, Kling, Wan 2.6, Sora 2 | `POST /v1/video/generations`, `POST /v1/videos`, `POST /v1beta/interactions`, or `POST /v2/video_generation` | | Audio and Music | Music Generation, Speech Synthesis | Model-specific audio endpoints | | Digital Humans | Digital Human Video | Model-specific avatar video endpoint | ## Model List Endpoint ```http GET /v1/models ``` The endpoint returns the current model list. UniAll can return compatibility-specific formats based on request headers: | Request style | Detection rule | Response style | | --- | --- | --- | | OpenAI compatible | Default request style | OpenAI model list | | Anthropic compatible | Includes both `x-api-key` and `anthropic-version` | Anthropic-style model list | | Gemini compatible | Includes `x-goog-api-key` header or `key` query parameter | Gemini-style model list | For this documentation scope, the normalized pages focus on the selected image, video, audio, and digital-human capabilities. ## Required Headers ```http Authorization: Bearer sk-*** ``` Compatibility-specific clients may use their native authentication headers when documented by the client format. ## Request Example ```bash curl "{BASE_URL}/v1/models" \ -H "Authorization: Bearer sk-***" ``` ## Response Example ```json { "object": "list", "data": [ { "id": "grok-imagine", "object": "model", "created": 0, "owned_by": "uniall" }, { "id": "gpt-image-2.5-flare", "object": "model", "created": 0, "owned_by": "uniall" }, { "id": "gpt-image-2.6-flare", "object": "model", "created": 0, "owned_by": "uniall" }, { "id": "gpt-image-2.6-sunburst", "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 - For Nano Banana 2.1, use `nano-banana-2.1` with the [OpenAI Images guide](/models/image/nano-series/nano-banana-2-1/openai-format), or the official ID `gemini-nano-banana-2.1` with the [Gemini generateContent guide](/models/image/nano-series/nano-banana-2-1/gemini-format). Both formats return results synchronously. - Use [Async Image Generation](/models/image/async-image-generation) when the task is image generation or image editing through a polling flow. - Use [Qwen Image](/models/image/qwen-image) for synchronous generation and editing with the six 3.0, 2.1 and 2.0 models through OpenAI Images or the Bailian native API. - Use [GPT-Image-2.5](/models/image/gpt-image-2-5) for synchronous GPT Image 2.5 generation and editing. - Use [GPT-Image-2.6](/models/image/gpt-image-2-6) for synchronous generation, editing and GIF generation with `gpt-image-2.6-flare` and `gpt-image-2.6-sunburst`. - Use [Seedream 5.0 Pro Image Generation](/models/image/seedream-5-0-pro) when the model ID is `seedream-5.0-pro`. - Use [Seedance 2.5](/models/video/seedance-2-5) for `seedance2.5`, including ordinary 1080p output and the [480p Draft to 1080p final-video workflow](/models/video/seedance-2-5#draft-to-final). - Use the [MiniMax H3 native API](/models/video/minimax-h3) for `MiniMax-H3` and `MiniMax-H3-Max` video calls. - Use [Grok Imagine Video Generation](/models/video/grok-imagine) when the model ID is `grok-imagine`. - Use [Gemini Omni Flash Preview Video Generation](/models/video/gemini-omni-flash-preview) when the model ID is `gemini-omni-flash-preview`. - Use [Hailuo Video Generation](/models/video/hailuo) when the model ID is `hailuo-02`, `hailuo-2.3`, or `hailuo-2.3-fast`. - Use [Kling Image](/models/image/kling) for `kling-v3`, `kling-v3-omni`, or `kling-image-o1` image tasks. - Use [Kling Video](/models/video/kling) for version-level Kling video models, and [Digital Human Video](/models/avatar/digital-human) for `operation: avatar`. - Use the capability-specific page for model-specific fields 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) - [GPT-Image-2.6](/models/image/gpt-image-2-6) - [Qwen Image](/models/image/qwen-image) - [Seedream 5.0 Pro Image Generation](/models/image/seedream-5-0-pro) - [Seedance 2.5](/models/video/seedance-2-5) - [Grok Imagine Video Generation](/models/video/grok-imagine) - [Gemini Omni Flash Preview Video Generation](/models/video/gemini-omni-flash-preview) - [Hailuo Video Generation](/models/video/hailuo) - [Kling Image](/models/image/kling) - [Kling Video](/models/video/kling) - [Digital Human Video](/models/avatar/digital-human) --- # Music Generation Locale: en URL: https://docs.uniall.ai/models/audio/music-generation Source: site-docs/models/audio/music-generation.md Description: MiniMax Music generation source documentation. This document explains how to use MiniMax Music 2.6 async music generation endpoint. Supported models: | Model name | Type | Suitable scenarios | Billing mode | |---|---|---|---| | `minimax-music-2.6` | music generation | ad music, short-video background music, podcast intro, product promo track, instrumental ambience bed | billed by output audio item count | Endpoint async task mode: | Operation | Method | Path | |---|---|---| | submit musictask | `POST`|`/v1/audio/tasks` | | query musictask | `GET`|`/v1/audio/tasks/{task_id}` | --- ## 1. Authentication Endpoint requires request headers API Key: ```http Authorization: Bearer sk-xxxxxxxxxxxxxxxx Content-Type: application/json ``` Example: ```uri https://api.xxx.xx ``` --- ## 2. Model overview `minimax-music-2.6` music description and generate music audio. generation video, pass, music, BGM. Modelsupports: - pass `prompt`+`lyrics` - music: pass `prompt`+`is_instrumental: true` --- ## 3. submit musictask ```http POST https://api.xxx.xx/v1/audio/tasks ``` ### 3.1 Request Parameters | Parameters | Type | Required | Note | |---|---|---|---| | `model`| string | Yes |`minimax-music-2.6` | | `prompt` | string | Yes | music description, recommended style, Purpose, | | `lyrics` | string | No |. music recommendedprovides | | `lyrics_optimizer` | boolean | No | Whether | | `is_instrumental` | boolean | No | Whether to generate music | | `audio_setting` | object | No | audio object, the platformavailableCapabilitypass through | ### 3.2 submitResponse Examples ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "audio.generation.job", "status": "queued" } ``` Field Reference: | Field | Note | |---|---| | `id`/`task_id` | async task ID, query result | | `status`| task status, value `queued`, `processing`, `completed`, `failed` | --- ## 4. query musictask ```http GET https://api.xxx.xx/v1/audio/tasks/{task_id} ``` queryExample: ```bash curl -X GET "https://api.xxx.xx/v1/audio/tasks/task_xxxxxxxxxxxxx" \ -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" ``` Completed Response Example: ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "audio.generation.job", "status": "completed", "audio_url": "https://api.xxx.xx/media/xxxxx.mp3", "result": { "outputs": [ "https://api.xxx.xx/media/xxxxx.mp3" ], "audios": [ { "url": "https://api.xxx.xx/media/xxxxx.mp3" } ] } } ``` --- ## 5. Request Examples ### 5.1 generation ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-music-2.6", "prompt": "A bright synth pop song for a product launch, upbeat, modern commercial style, clean vocal, energetic chorus", "lyrics": "Hello future, we are ready now\nLight the skyline, make it loud\nEvery step is shining brighter\nWe are here and moving proud", "lyrics_optimizer": true, "is_instrumental": false}' ``` ### 5.2 generationshort-video background music ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-music-2.6", "prompt": "A catchy 30-second lifestyle vlog background track, light guitar, soft beat, sunny mood, no vocal", "is_instrumental": true}' ``` ### 5.3 generation music ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-music-2.6", "prompt": "A warm podcast intro jingle, 8 to 12 seconds feeling, soft piano, subtle electronic pulse, professional and friendly", "is_instrumental": true}' ``` ### 5.4 generationChinese ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-music-2.6", "prompt": "Chinese mandopop brand song, warm female vocal, inspiring chorus, clean arrangement, suitable for a technology brand", "lyrics": " \nnew \n \n to change ", "lyrics_optimizer": true, "is_instrumental": false}' ``` ### 5.5 generation music ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-music-2.6", "prompt": "Educational course intro music, calm but motivating, soft marimba, piano, gentle percussion, suitable for online learning", "is_instrumental": true}' ``` --- ## 6. Common Errors ### 6.1 prompt Error: ```json { "model": "minimax-music-2.6", "lyrics": "Hello world" } ``` `prompt`. ### 6.2 music If: ```json { "is_instrumental": false } ``` recommended to pass both `lyrics`. --- ## 7. recommended 1. scenario music style, Purpose. 2. If required, provides. 3. submit `/v1/audio/tasks`. 4. poll `/v1/audio/tasks/{task_id}`. 5. task completed read `audio_url`. --- ## 8. Minimum Valid Request ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-music-2.6", "prompt": "A bright short commercial pop song, modern and uplifting", "is_instrumental": true}' ``` --- # Audio and Music Overview Locale: en URL: https://docs.uniall.ai/models/audio/overview Source: site-docs/models/audio/overview.md Description: UniAll speech synthesis and music generation docs entry point. This category organizes speech synthesis and music generation from the source menu. ## Included Pages - [Music Generation](/models/audio/music-generation) - [Speech Synthesis](/models/audio/speech-synthesis) ## Integration Guidance Use [Music Generation](/models/audio/music-generation) for `minimax-music-2.6` music tasks. Use [Speech Synthesis](/models/audio/speech-synthesis) for MiniMax Speech HD text-to-speech and voice management. Both capabilities use asynchronous task flows for generated audio. Submit a task, poll by `task_id`, then read the returned audio URL after success. --- # Speech Synthesis Locale: en URL: https://docs.uniall.ai/models/audio/speech-synthesis Source: site-docs/models/audio/speech-synthesis.md Description: Generate speech and manage MiniMax voices through UniAll async audio APIs. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. Use MiniMax Speech HD models to generate speech from text. Voice management APIs can list system voices and create reusable private `voice_id` values through voice cloning or voice design. ## When To Use It - Generate voiceover for short videos, ads, courses, narration, or digital humans. - Use a public voice from the voice list. - Clone or design a private voice, then pass its `voice_id` into a speech task. ## Supported Models | Model | Type | Recommended use | | --- | --- | --- | | `minimax-speech-2.8-hd` | Text to speech | Natural short-form speech, emotional narration, ads, digital-human voiceover. | | `minimax-speech-02-hd` | Text to speech | Audiobooks, course narration, customer-service voice, news reading, long-form narration. | ## Endpoint ```http POST /v1/audio/tasks GET /v1/audio/tasks/{task_id} GET /v1/audio/voices POST /v1/audio/voices/clone POST /v1/audio/voices/design ``` ## Authentication ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## Speech Request Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | `minimax-speech-2.8-hd` or `minimax-speech-02-hd`. | | `text` | string | Yes | Text to synthesize. | | `voice_id` | string | Yes | Public or private voice ID. | | `speed` | number | No | Speaking speed when supported by the model. | | `volume` | number | No | Output volume when supported. | | `pitch` | number | No | Pitch adjustment when supported. | | `format` | string | No | Output format, such as `mp3` or `wav`, when supported. | | `language` | string | No | Language hint for multilingual text. | | `audio_setting` | object | No | Advanced audio settings passed through to the provider when supported. | ## Speech Request Example ```bash curl -X POST "{BASE_URL}/v1/audio/tasks" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-2.8-hd", "text": "Welcome back. Today we will introduce a faster way to build AI applications.", "voice_id": "voice_xxx", "format": "mp3", "speed": 1 }' ``` ## Submit Response ```json { "task_id": "task_xxx", "status": "queued", "model": "minimax-speech-2.8-hd", "created_at": 1773980459 } ``` ## Query Task Status ```bash curl "{BASE_URL}/v1/audio/tasks/task_xxx" \ -H "Authorization: Bearer sk-***" ``` ```json { "task_id": "task_xxx", "status": "succeeded", "progress": "100%", "output": { "audio_url": "https://example.com/speech.mp3" }, "error": null } ``` ## Voice Management List available voices: ```bash curl "{BASE_URL}/v1/audio/voices" \ -H "Authorization: Bearer sk-***" ``` Clone a voice from reference audio: ```bash curl -X POST "{BASE_URL}/v1/audio/voices/clone" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "name": "brand-narrator", "audio_url": "https://example.com/reference.wav" }' ``` Design a voice from text: ```bash curl -X POST "{BASE_URL}/v1/audio/voices/design" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "name": "warm-host", "description": "Warm, clear, young adult narrator for product explainers" }' ``` Use the returned `voice_id` in later speech tasks. ## Billing Notes Speech generation is billed by generated audio usage. Voice cloning and voice design may be billed separately because they create reusable private voices. Exact prices should come from the current product pricing surface. ## Common Errors - Missing `text` or `voice_id`. - Passing a private `voice_id` that is not visible to the current account. - Submitting very long text without splitting it into smaller tasks. - Using an unsupported output format. - Insufficient balance or disabled API key. ## Related Pages - [Audio and Music Overview](/models/audio/overview) - [Music Generation](/models/audio/music-generation) - [Digital Human Video](/models/avatar/digital-human) --- # MiniMax Speech HD Locale: en URL: https://docs.uniall.ai/models/audio/speech/minimax-speech-hd Source: site-docs/models/audio/speech/minimax-speech-hd.md Description: MiniMax Speech HD generation source documentation. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. This document explains how to use MiniMax Speech HD async speech generation model. Supported models: | Model name | Type | Recommended scenarios | |---|---|---| | `minimax-speech-2.8-hd` | text-to-speech | short-video narration, ad voiceover, digital-human voice, emotional narration, natural spoken voice | | `minimax-speech-02-hd` | text-to-speech | audiobook, course explanation, customer-service broadcast, news broadcast, long-form narration, multilingual speech | Endpoint async task mode: | Operation | Method | Path | |---|---|---| | submit speech task | `POST`|`/v1/audio/tasks` | | query speech task | `GET`|`/v1/audio/tasks/{task_id}` | URL example: ```uri https://api.xxx.xx ``` ## 1. Model overview ### 1.1 minimax-speech-2.8-hd `minimax-speech-2.8-hd` Yes new speech generation model, requires, and speech. Suitable scenarios: - short-video narration - ad voiceover - digital human - podcast intro Recommended text example: ```markdown <#0.5#>. (laughs) ``` ### 1.2 minimax-speech-02-hd `minimax-speech-02-hd` Yes stable speech generation model, stable, text speech task. Suitable scenarios: - audiobook - course explanation - news broadcast - speech - long-form narration - multilingual speech generation Recommended text example: ## 2. Authentication requires API Key. request headers: ```http Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` ## 3. submit speech generationtask URL: ```http POST https://api.xxx.xx/v1/audio/tasks ``` ### 3.1 Request Parameters | Parameters | Type | Required | Note | |---|---|---|---| | `model`| string | Yes | Model name, supports `minimax-speech-2.8-hd`, `minimax-speech-02-hd` | | `text` | string | Yes | generationspeech text | | `input`| string | No |`text`, OpenAI style | | `voice_id` | string | No | voice ID, the platformprovides voiceor voice ID | | `voice` | string | No | voice name, compatibility field | | `speed`| number | No |, range `0.5` `2.0` | | `emotion`| string | No |,`happy`, `sad`, `angry`, `fearful`, `disgusted`, `surprised`, `neutral` | | `language`| string | No | language,`Chinese`, `English`, `Japanese`, `auto` | | `output_format`| string | No | format, recommended to use `url` | | `response_format`| string | No | responsesformat, recommended to use `url` | | `sample_rate`| number | No |,`32000`, `44100` | | `pronunciation_dict` | object | No | | | `timber_weights` | array | No | voice, | | `subtitle_enable` | boolean | No | Whether generation | | `metadata` | object | No | | | `extra_body` | object | No | Parameters | Note: - `text` and `input` one of two required. - recommendedprefer using `text`. - If you pass both `text` and `input`. - Endpoint async taskEndpoint, submit task requires `task_id` query result. - billing detail, Chinese, English, punctuation, spaces, line breaks, emoji. - Example `voice_id`, voice ID. ### 3.2 Request Examples ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-speech-2.8-hd", "text": ", use aijisu speech generationservice. "}' ``` ### 3.3 submitSuccessResponse Example ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "audio.generation.job", "status": "queued", "raw_status": "SUBMITTED", "progress": "0%", "audio_url": null, "result": null, "error": null } ``` ## 4. Query Taskresult URL: ```http GET https://api.xxx.xx/v1/audio/tasks/{task_id} ``` Request Examples: ```bash curl -X GET "https://api.xxx.xx/v1/audio/tasks/task_xxxxxxxxxxxxx" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### 4.1 generation Response Example ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "audio.generation.job", "status": "in_progress", "raw_status": "IN_PROGRESS", "progress": "45%", "audio_url": null, "result": null, "error": null } ``` ### 4.2 generation completedResponse Example ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "audio.generation.job", "status": "completed", "raw_status": "SUCCESS", "progress": "100%", "audio_url": "https://example.com/audio.mp3", "result": { "audio_url": "https://example.com/audio.mp3", "outputs": [ "https://example.com/audio.mp3" ], "audios": [ { "url": "https://example.com/audio.mp3" } ] }, "error": null } ``` ### 4.3 generationFailedResponse Example ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "audio.generation.job", "status": "failed", "raw_status": "FAILURE", "progress": "100%", "audio_url": null, "result": null, "error": { "message": "audio task failed" } } ``` ## 5. task status Values | status | Note | |---|---| | `queued` | submit, processing | | `in_progress` | generation | | `processing` | In progress | | `completed` | generation completed | | `failed` | generationFailed | recommended 2 5 query task status, recommended poll. ## 6. and `minimax-speech-2.8-hd` use and. | | Note | |---|---| | `<#0.5#>` | 0.5 | | `<#1.0#>` | 1 | | `(laughs)` | | | `(sighs)` | | | `(coughs)` | | | `(clears throat)` | | | `(gasps)` | | | `(sniffs)` | | | `(groans)` | | | `(yawns)` | | Example: ```markdown <#0.8#>. (sighs) ``` ## 7. Use Case Examples ### 7.1 Chinese short-video narration ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-speech-2.8-hd", "text": ". <#0.4#>. ", "voice_id": "Wise_Woman", "speed": 1.05, "emotion": "happy", "output_format": "url"}' ``` ### 7.2 course explanation ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-speech-02-hd", "text": ". to change. ", "voice_id": "Wise_Woman", "speed": 0.95, "emotion": "neutral", "output_format": "url"}' ``` ### 7.3 ad voiceover ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-speech-2.8-hd", "text": " new. <#0.3#>,! ", "voice_id": "Wise_Woman", "speed": 1.12, "emotion": "happy", "output_format": "url"}' ``` ### 7.4 audiobook ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-speech-02-hd", "text": ".. ", "voice_id": "Wise_Woman", "speed": 0.88, "emotion": "neutral", "output_format": "url"}' ``` ### 7.5 Details ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-speech-2.8-hd", "text": ". <#0.6#>. (sighs)", "voice_id": "Wise_Woman", "speed": 0.92, "emotion": "sad", "output_format": "url"}' ``` ### 7.6 Englishpodcast intro ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-speech-2.8-hd", "text": "Hey, welcome back to the show. <#0.4#> Today we are talking about how AI is changing creative work. (laughs)", "voice_id": "Wise_Woman", "speed": 1.0, "emotion": "happy", "language": "English", "output_format": "url"}' ``` ### 7.7 language ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-speech-02-hd", "text": ", service. Please hold on for a moment. service. ", "voice_id": "Wise_Woman", "speed": 1.0, "language": "auto", "emotion": "neutral", "output_format": "url"}' ``` ### 7.8 news broadcast ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-speech-02-hd", "text": " new:, new. ", "voice_id": "Wise_Woman", "speed": 1.0, "emotion": "neutral", "output_format": "url"}' ``` ### 7.9 digital human ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-speech-2.8-hd", "text": ", Yes AI. <#0.4#>. ", "voice_id": "Wise_Woman", "speed": 1.03, "emotion": "happy", "output_format": "url"}' ``` ### 7.10 Details ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-speech-2.8-hd", "text": "., Yes. ", "voice_id": "Wise_Woman", "speed": 0.9, "emotion": "happy", "output_format": "url"}' ``` ### 7.11 speech ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-speech-02-hd", "text": ". Operation. ", "voice_id": "Wise_Woman", "speed": 0.96, "emotion": "neutral", "output_format": "url"}' ``` ### 7.12 Details ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-speech-2.8-hd", "text": ". <#1.0#>. <#1.0#>. ", "voice_id": "Wise_Woman", "speed": 0.82, "emotion": "neutral", "output_format": "url"}' ``` ### 7.13 use input Fieldsubmit ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-speech-02-hd", "input": " Yes use input Fieldsubmit speech generationtask. ", "voice_id": "Wise_Woman", "output_format": "url"}' ``` ### 7.14 Details ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-speech-2.8-hd", "text": " use AI, new the platform. ", "voice_id": "Wise_Woman", "output_format": "url", "pronunciation_dict": {"tone_list": ["AI /(A)(I)(ji2)(su4)"]}}' ``` ### 7.15 audio ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-speech-2.8-hd", "text": " Yesa video quality. ", "voice_id": "Wise_Woman", "sample_rate": 44100, "output_format": "url"}' ``` ### 7.16 IVR ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-speech-02-hd", "text": "., query, service. ", "voice_id": "Wise_Woman", "speed": 0.98, "emotion": "neutral", "output_format": "url"}' ``` ### 7.17 video ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-speech-2.8-hd", "text": " Yes. <#0.4#> completed, and generation. ", "voice_id": "Wise_Woman", "speed": 1.02, "emotion": "happy", "output_format": "url"}' ``` ### 7.18 Details ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-speech-02-hd", "text": ", and. ", "voice_id": "Wise_Woman", "speed": 0.9, "emotion": "neutral", "output_format": "url"}' ``` ## 8. JavaScript callExample ```javascript const API_KEY = "YOUR_API_KEY"; const BASE_URL = "https://api.xxx.xx"; async function createAudioTask() {const response = await fetch(`${BASE_URL}/v1/audio/tasks`, {method: "POST", headers: {"Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json"}, body: JSON.stringify({model: "minimax-speech-2.8-hd", text: ", Yesa aijisu generation speech. ", voice_id: "Wise_Woman", speed: 1, emotion: "neutral", output_format: "url"})}); if (!response.ok) {throw new Error(await response.text());} return await response.json();} async function getAudioTask(taskId) {const response = await fetch(`${BASE_URL}/v1/audio/tasks/${taskId}`, {method: "GET", headers: {"Authorization": `Bearer ${API_KEY}`}}); if (!response.ok) {throw new Error(await response.text());} return await response.json();} async function main() {const task = await createAudioTask(); console.log("task_id:", task.task_id); while (true) {const result = await getAudioTask(task.task_id); console.log(result.status, result.progress); if (result.status === "completed") {console.log("audio_url:", result.audio_url); break;} if (result.status === "failed") {console.error("failed:", result.error); break;} await new Promise(resolve => setTimeout(resolve, 3000));}} main().catch(console.error); ``` ## 9. Python callExample ```python import time import requests API_KEY = "YOUR_API_KEY" BASE_URL = "https://api.xxx.xx" headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"} payload = {"model": "minimax-speech-02-hd", "text": ", Yesa Python submit speech generationtask. ", "voice_id": "Wise_Woman", "speed": 1, "emotion": "neutral", "output_format": "url"} create_resp = requests.post(f"{BASE_URL}/v1/audio/tasks", headers=headers, json=payload) create_resp.raise_for_status() task = create_resp.json() task_id = task["task_id"] while True: query_resp = requests.get(f"{BASE_URL}/v1/audio/tasks/{task_id}", headers={"Authorization": f"Bearer {API_KEY}"}) query_resp.raise_for_status() result = query_resp.json() print(result["status"], result.get("progress")) if result["status"] == "completed": print("audio_url:", result.get("audio_url")) break if result["status"] == "failed": print("failed:", result.get("error")) break time.sleep(3) ``` ## 10. Billing Notes speech generation billing detail.: - Chinese - English - punctuation - spaces - line breaks - emoji Example: 6 characters. billing model pricing, rules and account balance rules. ## 11. Model recommended ### 11.1 prefer using minimax-speech-2.8-hd: - requires - requires, - short-video narration - ad voiceover - digital human - speech ### 11.2 prefer using minimax-speech-02-hd: - long-form narration - audiobook - course explanation - customer-service broadcast - news broadcast - language - stable scenario ## 12. recommended ### 12.1 short-video narration ```json { "model": "minimax-speech-2.8-hd", "text": ". <#0.4#>. ", "voice_id": "Wise_Woman", "speed": 1.05, "emotion": "happy", "output_format": "url" } ``` ### 12.2 audiobook ```json { "model": "minimax-speech-02-hd", "text": ". ", "voice_id": "Wise_Woman", "speed": 0.88, "emotion": "neutral", "output_format": "url" } ``` ### 12.3 customer-service broadcast ```json { "model": "minimax-speech-02-hd", "text": ", service., service. ", "voice_id": "Wise_Woman", "speed": 1, "emotion": "neutral", "output_format": "url" } ``` ### 12.4 Details ```json { "model": "minimax-speech-2.8-hd", "text": "? <#0.8#>. (sighs)", "voice_id": "Wise_Woman", "speed": 0.92, "emotion": "sad", "output_format": "url" } ``` ### 12.5 English ```json { "model": "minimax-speech-2.8-hd", "text": "Welcome back. <#0.4#> Today we are going to talk about how creators can use AI to work faster.", "voice_id": "Wise_Woman", "speed": 1, "emotion": "happy", "language": "English", "output_format": "url" } ``` ## 13. Details ### 13.1 submit returnaudio? speech generationYesasync task. submit endpoint returntask ID, requires queryEndpoint audio URL. ### 13.2 `text` and `input`? `input` Yes `text`. recommendedprefer using `text`. ### 13.3 generation audio? recommended generation audio. If required audio, recommended task submit. ### 13.4 text processing? recommended task. controlFailed, and. ### 13.5 speech? recommended: - reservedpunctuation - do not use - scenario `speed` -, digital humanprefer using `minimax-speech-2.8-hd` ### 13.6 audio URL? task completed return `audio_url`, download or processing. ### 13.7 Failed?: - API Key or - `model` - `text` or `input` - pass both `text` and `input`, - voice ID unavailable - Parametersformat - accountbalance or use Model ## 14. Example ###: submit task ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-speech-2.8-hd", "text": ", Yes speech. ", "voice_id": "Wise_Woman", "speed": 1, "emotion": "neutral", "output_format": "url"}' ``` return: ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "audio.generation.job", "status": "queued", "raw_status": "SUBMITTED", "progress": "0%", "audio_url": null, "result": null, "error": null } ``` ###: Query Task ```bash curl -X GET "https://api.xxx.xx/v1/audio/tasks/task_xxxxxxxxxxxxx" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ###: audio URL `status` `completed`, read: ```json { "audio_url": "https://example.com/audio.mp3" } ``` ordownloadgeneration audio. --- # MiniMax Speech Voice Management Locale: en URL: https://docs.uniall.ai/models/audio/speech/voice-management Source: site-docs/models/audio/speech/voice-management.md Description: MiniMax Speech voice management source documentation. This document explains how to use MiniMax voiceCapability, voice list, Voice CloningandVoice Design. If you only need to generate speech from text, usespeech generation endpoint: - `POST /v1/audio/tasks` - `GET /v1/audio/tasks/{task_id}` If you want to create your own `voice_id`, then use that `voice_id` in speech generation, use this page voice endpoints. ## 1. supportsCapability | Capability | Endpoint | Whether | Note | |---|---|---:|---| | List Voices | `GET /v1/audio/voices` | No | return voiceand privatevoice | | Voice Cloning | `POST /v1/audio/voices/clone`| Yes | reference audiogenerate a `voice_id` | | Voice Design | `POST /v1/audio/voices/design`| Yes | description `voice_id` | | usevoicegenerationspeech | `POST /v1/audio/tasks`| Yes |`voice_id` pass TTS Modelgenerate audio | recommended TTS Modeluse: | Model name | Note | |---|---| | `minimax-speech-2.8-hd` | new speech generation model, video, digital human, ad voiceover | | `minimax-speech-02-hd` | stable speech generation model, audiobook, text | Voice CloningandVoice Designcreate `voice_id` TTS Modeluse. ## 2. EndpointURL Example use: ```uri https://api.xxx.xx ``` call aijisu API. | Operation | Method | Path | |---|---|---| | List Voices | `GET`|`/v1/audio/voices` | | Voice Cloning | `POST`|`/v1/audio/voices/clone` | | Voice Design | `POST`|`/v1/audio/voices/design` | | submit speech generationtask | `POST`|`/v1/audio/tasks` | | query speech generationtask | `GET`|`/v1/audio/tasks/{task_id}` | ## 3. Authentication Endpoint use Bearer Token: ```http Authorization: Bearer YOUR_API_KEY ``` Example: ```bash curl https://api.xxx.xx/v1/audio/voices \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## 4. voice ID Note `voice_id` Yescall TTS use voice. voice: | | Note | |---|---| | system voices | the platform voice, user queryanduse | | privatevoice | Voice CloningorVoice Designcreate voice, and | Voice CloningandVoice DesignSuccess, Endpoint return `voice_id`. to change, `/v1/audio/tasks` pass in `voice_id` generationspeech. ## 5. List Voices ### 5.1 Details ```http GET /v1/audio/voices ``` Optional valuesqueryParameters: | Parameters | Type | Required | Note | |---|---|---:|---| | `model`| string | No | compatibilityModel voice, Optional values `minimax-speech-2.8-hd` or `minimax-speech-02-hd` | ### 5.2 queryall voice ```bash curl "https://api.xxx.xx/v1/audio/voices" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### 5.3 query Speech 2.8 HD voice ```bash curl "https://api.xxx.xx/v1/audio/voices?model=minimax-speech-2.8-hd" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### 5.4 query Speech 02 HD voice ```bash curl "https://api.xxx.xx/v1/audio/voices?model=minimax-speech-02-hd" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### 5.5 Response Examples ```json { "object": "audio.voice.list", "model": "minimax-speech-2.8-hd", "data": [ { "voice_id": "Chinese (Mandarin)_Kind-hearted_Elder", "display_name": "Kind-hearted Elder", "language": "Chinese (Mandarin)", "description": "MiniMax system voice", "source_type": "system", "visibility": "public", "status": "active", "compatible_models": [ "minimax-speech-2.8-hd", "minimax-speech-02-hd" ], "preview_audio_url": null, "created_at": "2026-06-23T18:05:59Z" }, { "voice_id": "ttv-voice-2026062416421526-E4jmMP8B", "display_name": "local-design-taskid-smoke", "language": "Chinese (Mandarin)", "description": "Local smoke test for task id in sync response.", "source_type": "voice_design", "visibility": "private", "status": "active", "compatible_models": [ "minimax-speech-2.8-hd", "minimax-speech-02-hd" ], "preview_audio_url": "https://api.xxx.xx/media/preview.mp3", "created_at": "2026-06-24T08:42:23Z" } ] } ``` ### 5.6 Response Fields | Field | Note | |---|---| | `object`|`audio.voice.list` | | `model` | Model | | `data` | voicearray | | `data[].voice_id` | voice ID, TTS callpass value | | `data[].display_name` | voice name | | `data[].language` | voice language | | `data[].description` | voice description | | `data[].source_type`| voice, Yes `system`, `voice_clone`, `voice_design` | | `data[].visibility`|, Yes `public` or `private` | | `data[].status`| Status,`active` | | `data[].compatible_models` | use voice TTS Model | | `data[].preview_audio_url` | audio URL, | | `data[].created_at` | Created time | ## 6. Voice Cloning Voice Cloning areference audio, create newprivate `voice_id`. Suitable scenarios: - digital humangeneration voice -, audiobook, video - to change call TTS voice ### 6.1 Details ```http POST /v1/audio/voices/clone ``` JSON. | Parameters | Type | Required | Note | |---|---|---:|---| | `audio_url` | string | Yes | reference audio URL, requiresEndpointservice | | `text` | string | recommended | reference audio textor text, qualityandgeneration | | `preview_text`| string | No |`text` compatibility field. pass both, recommendedand `text` | | `display_name` | string | No | voice name, list | | `name`| string | No |`display_name` compatibility field | | `language`| string | No | voice language,`Chinese (Mandarin)`, `English` | | `description` | string | No | voice description | | `noise_reduction` | boolean | No | Whether | | `need_volume_normalization` | boolean | No | Whether | | `accuracy` | number/string | No | Parameters, the platform supportspass through | ### 6.2 reference audiorecommended | | recommended | |---|---| | audio |, | | audio | recommended 10, | | quality |, music, | | | stable, do not or | | text | If audio, recommendedto change `text` | | | use | ### 6.3 Request Examples ```bash curl -X POST "https://api.xxx.xx/v1/audio/voices/clone" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"audio_url": "https://example.com/audio/reference-speaker.mp3", "text": ". Method. ", "display_name": "course-teacher-voice", "language": "Chinese (Mandarin)"}' ``` ### 6.4 and ```bash curl -X POST "https://api.xxx.xx/v1/audio/voices/clone" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"audio_url": "https://example.com/audio/noisy-reference.wav", "text": " Yes Voice Cloning reference audio, voice stable. ", "display_name": "cleaned-brand-speaker", "language": "Chinese (Mandarin)", "description": " voice", "noise_reduction": true, "need_volume_normalization": true}' ``` ### 6.5 English Voice Cloning ```bash curl -X POST "https://api.xxx.xx/v1/audio/voices/clone" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"audio_url": "https://example.com/audio/english-host.mp3", "text": "Welcome back to the show. Today we are going to explore a simple but powerful idea.", "display_name": "english-podcast-host", "language": "English", "description": "Warm English podcast host voice"}' ``` ### 6.6 Response Examples ```json { "object": "audio.voice", "model": "minimax-voice-clone", "task_id": "task_abc123", "voice_id": "VoiceClone123456", "preview_audio_url": "https://api.xxx.xx/media/voice-clone-preview.mp3", "voice": { "voice_id": "VoiceClone123456", "display_name": "course-teacher-voice", "language": "Chinese (Mandarin)", "description": " voice", "source_type": "voice_clone", "visibility": "private", "status": "active", "compatible_models": [ "minimax-speech-2.8-hd", "minimax-speech-02-hd" ], "preview_audio_url": "https://api.xxx.xx/media/voice-clone-preview.mp3", "created_at": "2026-06-24T08:42:23Z" }, "billing_contract": { "billing_version": "media-v1", "public_model": "minimax-voice-clone", "operation": "audio.voice_clone", "settlement_policy": "fixed_at_estimate", "billing_stage": "final", "facts": { "voice_clones": 1, "preview_characters": 36 } }, "outputs": [ { "url": "https://api.xxx.xx/media/voice-clone-preview.mp3", "type": "audio" } ] } ``` ## 7. Voice Design Voice Design descriptiongenerate anewprivate `voice_id`, requires passreference audio. Suitable scenarios: - video voice - digital human - fast generation, voice - reference audio, description scenario ### 7.1 Details ```http POST /v1/audio/voices/design ``` JSON. | Parameters | Type | Required | Note | |---|---|---:|---| | `prompt` | string | Yes | Voice design description, voice description, language, scenario | | `preview_text` | string | Yes | generation audio text | | `text`| string | No |`preview_text` compatibility field | | `display_name` | string | No | voice name, list | | `name`| string | No |`display_name` compatibility field | | `language`| string | No | voice language,`Chinese (Mandarin)`, `English` | | `description` | string | No | voice description | ### 7.2 Prompt recommended recommended `prompt` description: | | Example | |---|---| | language | Chinese Mandarin, English, Cantonese | | | male, female | | | young adult, middle-aged, elder | | | warm, clear, soft, energetic, calm | | scenario | product demo, customer service, audiobook, game character | | | friendly, confident, gentle, dramatic | | | slow, medium pace, lively | ### 7.3 Chinese ```bash curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "A warm, calm Chinese Mandarin female narrator voice for short product demos, clear diction, gentle confidence, studio quality.", "preview_text": ", YesaVoice Design. newspeechCapability. ", "display_name": "warm-product-narrator", "language": "Chinese (Mandarin)", "description": " andshort-video narration "}' ``` ### 7.4 digital human voice ```bash curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "A confident Chinese Mandarin female digital human presenter voice, natural conversational tone, bright but not exaggerated, suitable for business explanation videos.", "preview_text": ", Yes.. ", "display_name": "digital-human-presenter", "language": "Chinese (Mandarin)", "description": "digital human voice"}' ``` ### 7.5 customer-service broadcastvoice ```bash curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "A polite Chinese Mandarin customer service voice, patient, clear, stable, friendly, suitable for service notifications and call center messages.", "preview_text": ", processingcompleted.. ", "display_name": "customer-service-clear", "language": "Chinese (Mandarin)", "description": " and voice"}' ``` ### 7.6 voice ```bash curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "A young Chinese Mandarin fantasy game character voice, playful, lively, slightly mysterious, expressive but clear.", "preview_text": ".. ", "display_name": "fantasy-guide-character", "language": "Chinese (Mandarin)", "description": " voice"}' ``` ### 7.7 English voice ```bash curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "A modern English commercial voice, energetic, premium, confident, suitable for product launch ads and social media videos.", "preview_text": "Meet the new way to create, edit, and publish your ideas in minutes.", "display_name": "english-commercial-premium", "language": "English", "description": "English commercial voice for product ads"}' ``` ### 7.8 audiobook voice ```bash curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "A mature Chinese Mandarin audiobook narrator voice, calm, steady, immersive, with clear pronunciation and comfortable pacing.", "preview_text": ". ", "display_name": "audiobook-calm-narrator", "language": "Chinese (Mandarin)", "description": "audiobook voice"}' ``` ### 7.9 Response Examples ```json { "object": "audio.voice", "model": "minimax-voice-design", "task_id": "task_437fb17536aa4ff7830ffb7a39f43a99", "voice_id": "ttv-voice-2026062416421526-E4jmMP8B", "preview_audio_url": "https://api.xxx.xx/media/design-preview.mp3", "voice": { "voice_id": "ttv-voice-2026062416421526-E4jmMP8B", "display_name": "warm-product-narrator", "language": "Chinese (Mandarin)", "description": " andshort-video narration ", "source_type": "voice_design", "visibility": "private", "status": "active", "compatible_models": [ "minimax-speech-2.8-hd", "minimax-speech-02-hd" ], "preview_audio_url": "https://api.xxx.xx/media/design-preview.mp3", "created_at": "2026-06-24T08:42:23Z" }, "billing_contract": { "billing_version": "media-v1", "public_model": "minimax-voice-design", "operation": "audio.voice_design", "settlement_policy": "fixed_at_estimate", "billing_stage": "final", "facts": { "voice_designs": 1, "preview_characters": 12 } }, "outputs": [ { "url": "https://api.xxx.xx/media/design-preview.mp3", "type": "audio" } ] } ``` ## 8. voice_id speech generation Voice CloningorVoice DesignSuccess, to changereturn `voice_id` `/v1/audio/tasks` generationspeech. ### 8.1 useVoice DesignvoicegenerationChinese ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-speech-2.8-hd", "text": "., fast. ", "voice_id": "ttv-voice-2026062416421526-E4jmMP8B", "speed": 1.0, "response_format": "url"}' ``` ### 8.2 useVoice Cloningvoicegenerationcourse explanation ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "minimax-speech-02-hd", "text": ".. ", "voice_id": "VoiceClone123456", "speed": 0.95, "response_format": "url"}' ``` ### 8.3 query speech generationtask ```bash curl "https://api.xxx.xx/v1/audio/tasks/task_abc123" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### 8.4 speech generationtaskCompleted Response Example ```json { "object": "audio.generation.job", "task_id": "task_abc123", "model": "minimax-speech-2.8-hd", "status": "completed", "audio_url": "https://api.xxx.xx/media/output.mp3", "result": { "audio_url": "https://api.xxx.xx/media/output.mp3", "outputs": [ "https://api.xxx.xx/media/output.mp3" ], "audios": [ { "url": "https://api.xxx.xx/media/output.mp3" } ] } } ``` ## 9. Billing Notes billing aijisu control andaccount. Endpoint Billing basis. | Capability | billing detail | billing detail | |---|---|---| | List Voices | | billing | | Voice Cloning | + | `voice_clones * 1.5 + preview_characters * 0.0003` | | Voice Design | + | `voice_designs * 3 + preview_characters * 0.00003` | | speech generation | | TTS Model billing detail Rules | Note: - `preview_characters` Yes text Unicode. - Chinese, English, spaces, punctuation, line breaks, emoji. - Yes UTF-8, Yes token. - Voice CloningandVoice Design submit billing detail. - If Failed, the platformFailed Rulesprocessing. ## 10. Node.js Example ### 10.1 Voice Design ```javascript const response = await fetch("https://api.xxx.xx/v1/audio/voices/design", {method: "POST", headers: {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}, body: JSON.stringify({prompt: "A warm Chinese Mandarin female narrator voice, clear and calm.", preview_text: ", YesVoice Design. ", display_name: "node-design-voice", language: "Chinese (Mandarin)"})}); const data = await response.json(); console.log(data.voice_id); console.log(data.preview_audio_url); ``` ### 10.2 generation voice_id createspeech task ```javascript const voiceId = "ttv-voice-2026062416421526-E4jmMP8B"; const response = await fetch("https://api.xxx.xx/v1/audio/tasks", {method: "POST", headers: {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}, body: JSON.stringify({model: "minimax-speech-2.8-hd", text: " Yesause voicegeneration speech. ", voice_id: voiceId, response_format: "url"})}); const task = await response.json(); console.log(task.task_id); ``` ## 11. Python Example ### 11.1 Voice Cloning ```python import requests api_key = "YOUR_API_KEY" response = requests.post("https://api.xxx.xx/v1/audio/voices/clone", headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}, json={"audio_url": "https://example.com/audio/reference-speaker.mp3", "text": ". ", "display_name": "python-clone-voice", "language": "Chinese (Mandarin)", "noise_reduction": True, "need_volume_normalization": True}, timeout=180) data = response.json() print(data["voice_id"]) print(data.get("preview_audio_url")) ``` ### 11.2 List Voices ```python import requests api_key = "YOUR_API_KEY" response = requests.get("https://api.xxx.xx/v1/audio/voices", headers={"Authorization": f"Bearer {api_key}"}, params={"model": "minimax-speech-2.8-hd"}, timeout=30) voices = response.json()["data"] for voice in voices: print(voice["voice_id"], voice.get("display_name")) ``` ## 12. Common Errors ### 12.1 Authentication ```json { "error": { "message": "API key required.", "type": "invalid_request_error", "code": "api_key_required" } } ``` Fix: Request headersWhether `Authorization: Bearer YOUR_API_KEY`. ### 12.2 Voice Cloning audio_url ```json { "error": { "message": "`audio_url` is required.", "type": "invalid_request_error", "code": "invalid_request_parameter" } } ``` Fix: pass in reference audio URL. ### 12.3 Voice Design prompt ```json { "error": { "message": "`prompt` is required.", "type": "invalid_request_error", "code": "invalid_request_parameter" } } ``` Fix: description, language, scenario, and. ### 12.4 Voice Design preview_text ```json { "error": { "message": "`preview_text` is required.", "type": "invalid_request_error", "code": "invalid_request_parameter" } } ``` Fix: pass in generation audio text. ### 12.5 voice_id unavailable ```json { "error": { "message": "`voice_id` is not visible for the current client or is not compatible with this model", "type": "invalid_request_error", "code": "invalid_request_parameter" } } ``` - `voice_id` Error. - use privatevoice. - voice compatibility TTS Model. - voice orunavailable. Fix: 1. call `GET /v1/audio/voices?model=...` query voice. 2. returnresult `voice_id`. 3. `voice_id` `/v1/audio/tasks`. ## 13. Details ### 13.1 Voice Cloning reference audio, requires, useVoice Cloning. scenario: - audio. - audio. - TTS reference. ### 13.2 Voice Design reference audio, description, useVoice Design. scenario: - digital human. - video generation voice. - generation. - fast or voice. ### 13.3 voice recommended recommended `display_name` usestable, name. Example: ```markdown brand-female-presenter course-teacher-male customer-service-clear game-guide-young english-commercial-premium ``` ### 13.4 voice_id createSuccess, Save: - `voice_id` - `display_name` - `source_type` - `preview_audio_url` - `compatible_models` - `created_at` Yes `voice_id`. TTS call requirespass `voice_id`. ### 13.5 callrecommended - Voice CloningandVoice Design TTS, recommended. - do not API Key. - recommended service call aijisu API. - `voice_id`, create voice. - create audioand. --- # Digital Human Video Locale: en URL: https://docs.uniall.ai/models/avatar/digital-human Source: site-docs/models/avatar/digital-human.md Description: Create Kling V3 digital-human videos from an image and audio or a UniAll voice ID. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. ## Overview Kling digital-human video uses the stable `kling-v3` model with `operation: avatar`. Provide one public image and either an audio URL or a UniAll `voice_id`; do not use the historical Kling Avatar tier model IDs. UniAll does not currently expose Kling subject-library creation or query endpoints. Do not pass `subject_ids` as a regular public parameter. ## When To Use It - Use `audio_url` when narration audio already exists. - Use `voice_id` when the task should use a voice returned by the UniAll voice list or clone endpoint. - Use `resolution: std` for the standard quality tier or `resolution: pro` for the higher quality tier. ## Endpoint | Action | Method | Path | | --- | --- | --- | | Create a digital-human video task | `POST` | `/v1/videos` | | Query a video task | `GET` | `/v1/videos/{task_id}` | | Download a completed video | `GET` | `/v1/videos/{task_id}/content` | | List Kling voices | `GET` | `/v1/audio/voices?model=kling-v3` | | Clone a Kling voice | `POST` | `/v1/audio/voices/clone` | ## Authentication ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## Request Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | Use `kling-v3`. | | `operation` | string | Yes | Use `avatar`. | | `prompt` | string | Yes | Presentation, expression, and camera guidance required by the UniAll video interface. | | `image` | string | Yes | Public HTTP(S) image URL for the presenter. | | `audio_url` | string | Conditional | Public narration-audio URL. Use exactly one of `audio_url` or `voice_id`. | | `voice_id` | string | Conditional | UniAll voice ID. Use exactly one of `voice_id` or `audio_url`. | | `resolution` | string | No | `std` or `pro`; default `std`. | | `watermark` | boolean | No | Whether to add an AIGC watermark. | Do not pass a `sound` switch. `audio_url` and `voice_id` are lip-sync inputs, and the prompt describes the intended presentation style. Do not pass both voice inputs in one request. ## List Available Voices ```bash curl "{BASE_URL}/v1/audio/voices?model=kling-v3" \ -H "Authorization: Bearer sk-***" ``` Use the UniAll `voice_id` returned by the list response. Do not pass an upstream voice ID. ## Clone A Voice ```bash curl -X POST "{BASE_URL}/v1/audio/voices/clone" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3", "voice_name": "Product narrator", "audio_url": "https://example.com/voice-sample.mp3", "text": "This is the preview text for the cloned voice." }' ``` Save the UniAll `voice_id` returned by a successful clone request, then pass it to the avatar task. ## Request Examples ### Use An Audio URL ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3", "operation": "avatar", "prompt": "A friendly presenter explains the product naturally in a stable front-facing shot.", "image": "https://example.com/presenter.png", "audio_url": "https://example.com/speech.mp3", "resolution": "pro", "watermark": false }' ``` ### Use A UniAll Voice ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3", "operation": "avatar", "prompt": "A professional presenter delivers the narration with natural expression and a stable front-facing camera.", "image": "https://example.com/presenter.png", "voice_id": "voice_xxxxxxxxxxxxx", "resolution": "std" }' ``` ## Response Example ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "kling-v3", "status": "queued", "progress": 0 } ``` ## Task Status And Result Save `id` or `task_id`, then follow [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared 3-to-10-second polling interval, terminal statuses, result fields, error contract, and authenticated download flow. ## Billing Notes Digital-human video billing normally depends on `kling-v3`, `operation: avatar`, `resolution`, and the output duration. Voice cloning may be billed separately according to the current model catalog. Task submission may reserve balance; the final task settlement and consumption records are authoritative. ## Common Errors - Using a historical digital-human tier model ID instead of `kling-v3`. - Omitting `operation: avatar` or the required `prompt`. - Passing both `audio_url` and `voice_id`, or passing neither. - Passing an upstream voice ID instead of a UniAll `voice_id`. - Passing `subject_ids` even though the public subject-library API is not available. - Passing `sound`, `duration`, or media URLs that the service cannot access publicly. - Resubmitting a paid task after one polling request times out instead of continuing to query the original `task_id`. Public responses do not expose provider names, upstream task IDs, routes, credentials, or raw upstream requests. ## Related Pages - [Kling Video](/models/video/kling) - [Kling Image](/models/image/kling) - [Video Generation Overview](/models/video/overview) --- # Digital Humans Overview Locale: en URL: https://docs.uniall.ai/models/avatar/overview Source: site-docs/models/avatar/overview.md Description: UniAll digital human narration docs entry point. This category organizes the digital-human narration workflow from the source menu and the user-supplied Kling V3 contract. ## Included Pages - [Digital Human Video](/models/avatar/digital-human) ## Integration Guidance Digital-human narration uses `kling-v3` with `operation: avatar`. Submit one presenter image with either an audio URL or a UniAll `voice_id`, then poll the returned `task_id` until the output video is available. Use the Kling voice list or clone endpoint on the [Digital Human Video](/models/avatar/digital-human) page when the workflow requires a `voice_id`. --- # Async Image Generation Locale: en URL: https://docs.uniall.ai/models/image/async-image-generation Source: site-docs/models/image/async-image-generation.md Description: Async image generation source documentation. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. Updated: 2026-04-29 This document explains how to use the async image task endpoint to call NanoBanana model and `gpt-image-2`, including request flow, Parameters, responses, billing detail rules and differences between the two model families. ## 1. Endpoint Overview ### 1.1 Submit Async Image Task ```http POST /v1/images/tasks ``` supports: - `task_type = text2image` - `task_type = image2image` ### 1.2 Query Async Image Task ```http GET /v1/images/tasks/{task_id} ``` ### 1.3 Details ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## 2. Model ### 2.1 NanoBanana upstream Nano Model: | Model | Note | | --- | --- | | `NanoBanana` | NanoBanana Model | | `NanoBanana2-0.5K` | NanoBanana2, 0.5K | | `NanoBanana2-1K` | NanoBanana2, 1K | | `NanoBanana2-2K` | NanoBanana2, 2K | | `NanoBanana2-4K` | NanoBanana2, 4K | | `NanoBananaPro-1K` | NanoBanana Pro, 1K | | `NanoBananaPro-2K` | NanoBanana Pro, 2K | | `NanoBananaPro-4K` | NanoBanana Pro, 4K | | `NanoBananaPro-8K` | NanoBanana Pro, 8K | Note: Whether the user can call Model, the platform Whether and billing detail Model. ### 2.2 gpt-image-2 | Model | Note | | --- | --- | | `gpt-image-2`|Image generation and editing model | ## 3. Request Body Parameters These fields apply to NanoBanana and `gpt-image-2` unless a model is specified in the row. | 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) | | `background` | string | No | For `gpt-image-2` only; pending release. `auto` (model chooses from the prompt), `opaque` (opaque background), or `transparent` (transparent background). Omitted or `null`: `auto`. | ### 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 Use `size` for output dimensions, `quality` for image quality, `n` for the image count, and `output_format` for the image format. Background control is pending release. Pass `background` at the top level of the request body. - `auto`: the model chooses the background from the prompt. This is the default when omitted or set to `null`. - `opaque`: request an opaque background. - `transparent`: request a transparent background. Set `output_format` to `png` or `webp`; if omitted, it defaults to `png`. An invalid `background` value or a `transparent`/`jpeg` combination returns HTTP 400 during request validation, before generation starts. ### 5.1 JSON ```json { "model": "gpt-image-2", "task_type": "text2image", "prompt": "An orange cat sticker, full subject visible, transparent background", "size": "1024x768", "quality": "low", "background": "transparent", "output_format": "webp", "n": 1, "response_format": "url" } ``` ### 5.2 JSON ```json { "model": "gpt-image-2", "task_type": "image2image", "prompt": "Keep the product shape and remove the background to make it transparent", "image": "https://example.com/input.png", "size": "1024x1024", "quality": "medium", "background": "transparent", "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 product shape and remove the background to make it transparent" \ -F "size=1024x1024" \ -F "quality=medium" \ -F "background=transparent" \ -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; output dimensions. See [size guidance](#gpt-image-2-size-options). | | `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 Use `size` to specify output dimensions for `gpt-image-2`, such as `1024x1024`. Omit `aspect_ratio`; use `quality` for image quality and `n` for the image count. ## 6. Response Examples 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. Request Examples ### 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": "An orange cat sticker, full subject visible, transparent background", "size": "1024x768", "quality": "low", "background": "transparent", "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` | | Ratiocontrol | supports `aspect_ratio`, `1:1`,`2:3`,`3:2`,`3:4`,`4:3`,`4:5`,`5:4`,`9:16`,`16:9`,`21:9`| does not support `aspect_ratio`; use `size`, `1024x768`, `1024x1024` | | formatcontrol | `NanoBanana` supports `png`/`jpeg`/`webp`; `NanoBananaPro-*`, `NanoBanana2-*` supports `png`/`jpeg`| supports `png`/`jpeg`/`webp` | | `size`| controlParameters; model tierand `aspect_ratio`| Required, [gpt-image-2`size` options](#gpt-image-2-size-options) | | `quality`| the platform billing detail; model tier | Optional values, default `medium`, and billing detail | | `n`| Optional values, default `1`, value upstreamconstraints | Optional values, default `1`, range `1-8` | | `response_format`| recommended `url`| recommended `url` | | | use for single-image input `image`, use for multi-image input `images`, passreference /editingPath | use for single-image input `image`, use for multi-image input `images`, passreference /editingPath | ## 10. Details 1. use `POST /v1/images/tasks` submit task. 2. return `task_id`. 3. use `GET /v1/images/tasks/{task_id}` polltask. 4. `status = succeeded` read `result_url`. --- # GPT-Image-2 Locale: en URL: https://docs.uniall.ai/models/image/gpt-image-2 Source: site-docs/models/image/gpt-image-2.md Description: Generate or edit images with gpt-image-2 through UniAll image APIs. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. Use `gpt-image-2` for text-to-image and image editing through the OpenAI-compatible image endpoints. This model uses `size` to control both dimensions and aspect ratio. It does not support `aspect_ratio`. ## Endpoint ```http POST /v1/images/generations POST /v1/images/edits ``` Use `/v1/images/generations` for text-to-image. Use `/v1/images/edits` when a reference image is included. ## Authentication ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## Request Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | Use `gpt-image-2`. | | `prompt` | string | Yes | Image generation or editing prompt. | | `image` | string/object | Conditional | Reference image for editing. | | `images` | array | Conditional | Multiple reference images when supported. | | `size` | string | Yes | Output dimensions, such as `1024x1024`. | | `quality` | string | No | `low`, `medium`, or `high`. Default: `medium`. | | `output_format` | string | No | `png`, `jpeg`, or `webp`. | | `background` | string | No | `auto` (model chooses from the prompt), `opaque` (opaque background), or `transparent` (transparent background). Omitted or `null`: `auto`. | | `n` | integer | No | Output image count. Default: `1`; range: `1` to `8`. | | `response_format` | string | No | Prefer `url`. | ## Background Control Background control is pending release. Pass `background` at the top level of the request body. - `auto`: the model chooses the background from the prompt. This is the default when omitted or set to `null`. - `opaque`: request an opaque background. - `transparent`: request a transparent background. Set `output_format` to `png` or `webp`; if omitted, it defaults to `png`. An invalid `background` value or a `transparent`/`jpeg` combination returns HTTP 400 during request validation, before generation starts. Applies to both synchronous generation and editing endpoints on this page. Existing GPT Image 2 async image tasks and image-chat compatibility requests use the same top-level field. Image results remain URL-based. ## 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": "An orange cat sticker, full subject visible, transparent background", "size": "1024x768", "quality": "low", "background": "transparent", "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 and remove the background to make it transparent", "image": "https://example.com/input.png", "size": "1024x1024", "quality": "medium", "background": "transparent", "output_format": "png", "n": 1, "response_format": "url" }' ``` ## Response Example ```json { "created": 1778688000, "data": [ { "url": "https://example.com/generated.png" } ] } ``` ## Common Errors - Missing `size`. - Passing `aspect_ratio`; use `size` instead. - Passing `quality` outside `low`, `medium`, or `high`. - Requesting `n` outside `1` to `8`. - Using an unsupported size for the current account. ## Related Pages - [Image Generation Overview](/models/image/overview) - [Async Image Generation](/models/image/async-image-generation) - [Seedream Image Generation](/models/image/seedream) --- # GPT-Image-2.5 Locale: en URL: https://docs.uniall.ai/models/image/gpt-image-2-5 Source: site-docs/models/image/gpt-image-2-5.md Description: Generate or edit images with GPT Image 2.5 through UniAll synchronous image APIs. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. GPT Image 2.5 provides two public model IDs: - `gpt-image-2.5-flare` - `gpt-image-2.5-sunburst` Both IDs use the same OpenAI-compatible synchronous image contract. Use `/v1/images/generations` for text-to-image requests and `/v1/images/edits` whenever the request includes reference images. The models returned by `GET /v1/models` for your API key are the models currently available to your account. ## When To Use It Use GPT Image 2.5 when you need: - synchronous text-to-image generation; - image editing with one or more reference images; - explicit output size, quality, and format controls; - URL or Base64 image responses. ## Endpoint ```http GET /v1/models POST /v1/images/generations POST /v1/images/edits ``` The image endpoints wait for the provider result and return the generated image in the same response. They do not create a task that requires polling. ## Authentication ```http Authorization: Bearer sk-*** Content-Type: application/json ``` The compatibility header below can also be used for authenticated requests: ```http x-api-key: sk-*** ``` ## Model Availability ```bash curl "{BASE_URL}/v1/models" \ -H "Authorization: Bearer sk-***" ``` A successful response includes the model IDs visible to the current API key: ```json { "object": "list", "data": [ { "id": "gpt-image-2.5-flare", "object": "model", "created": 0, "owned_by": "uniall" }, { "id": "gpt-image-2.5-sunburst", "object": "model", "created": 0, "owned_by": "uniall" } ] } ``` ## Request Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | `gpt-image-2.5-flare` or `gpt-image-2.5-sunburst`. | | `prompt` | string | Yes | Generation or editing instruction. Maximum length: 32,000 characters. | | `size` | string | No | `auto` or `WIDTHxHEIGHT`. Default: `auto`. | | `quality` | string | No | `auto`, `low`, `medium`, `high`, `xhigh`, or `max`. Default: `auto`. | | `n` | integer | No | Number of output images. Default: `1`; range: `1` to `10`. | | `output_format` | string | No | `png`, `jpeg`, or `webp`. Default: `png`. | | `background` | string | No | `auto` (model chooses from the prompt), `opaque` (opaque background), or `transparent` (transparent background). Omitted or `null`: `auto`. | | `response_format` | string | No | `url` or `b64_json`. Default: `b64_json`. | | `images` | array | Conditional | JSON reference images for `/v1/images/edits`. Each item uses `{"image_url":"..."}`. | | `mask` | object | No | JSON mask for `/v1/images/edits`. Uses `{"image_url":"..."}` and applies to the first reference image. | ## Background Control Background control is pending release. Pass `background` at the top level of the request body. - `auto`: the model chooses the background from the prompt. This is the default when omitted or set to `null`. - `opaque`: request an opaque background. - `transparent`: request a transparent background. Set `output_format` to `png` or `webp`; if omitted, it defaults to `png`. An invalid `background` value or a `transparent`/`jpeg` combination returns HTTP 400 during request validation, before generation starts. Applies to both synchronous generation and editing endpoints on this page. Result format remains selected by `response_format`: `url` or `b64_json`, with `b64_json` as the default. ## Size Rules For an explicit `WIDTHxHEIGHT` value: - width and height must be positive multiples of `16`; - the longest edge must not exceed `3840` pixels; - the aspect ratio must not exceed `3:1`; - total pixels must be between `655,360` and `8,294,400`. Use `auto` when the output size should be selected from the request and reference-image context. ## Text-To-Image Example ```bash curl -X POST "{BASE_URL}/v1/images/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2.5-flare", "prompt": "An orange cat sticker, full subject visible, transparent background", "size": "1024x1024", "quality": "medium", "background": "transparent", "output_format": "png", "n": 1, "response_format": "url" }' ``` ## JSON Image Editing Example Use `/v1/images/edits` when the request includes one or more reference images. ```bash curl -X POST "{BASE_URL}/v1/images/edits" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2.5-sunburst", "prompt": "Keep the product shape and remove the background to make it transparent", "images": [ {"image_url": "https://example.com/product.png"} ], "size": "auto", "quality": "high", "background": "transparent", "output_format": "png", "response_format": "url" }' ``` Each JSON reference uses an HTTP(S) image URL or a PNG, JPEG, or WebP Base64 Data URL. A request can include up to 16 reference images. ## Base64 Image Editing Example For JSON editing requests, pass the reference image as a complete Base64 Data URL in `images[].image_url`. ```bash curl -X POST "{BASE_URL}/v1/images/edits" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2.5-sunburst", "prompt": "Keep the product shape and remove the background to make it transparent", "images": [ { "image_url": "data:image/png;base64,BASE64_IMAGE_DATA" } ], "size": "1024x1024", "quality": "high", "background": "transparent", "output_format": "png", "response_format": "url" }' ``` The Data URL must include its MIME prefix, such as `data:image/png;base64,...`, `data:image/jpeg;base64,...`, or `data:image/webp;base64,...`. ## Multipart Image Editing Use multipart when the source image is a local file. Repeat `image[]` for multiple references. ```bash curl -X POST "{BASE_URL}/v1/images/edits" \ -H "Authorization: Bearer sk-***" \ -F "model=gpt-image-2.5-sunburst" \ -F "prompt=Keep the product shape and remove the background to make it transparent" \ -F "background=transparent" \ -F "output_format=png" \ -F "image[]=@product.png" \ -F "response_format=url" ``` A multipart mask can be sent as `mask=@mask.png`. The mask must be a PNG with an alpha channel, smaller than 4 MB, and have the same dimensions as the first reference image. ## Response Example ```json { "created": 1789121337, "size": "1024x1024", "output_format": "png", "data": [ { "url": "https://api.uniall.ai/generated-media/example.png" } ], "usage": { "prompt_tokens": 23, "completion_tokens": 425, "total_tokens": 448, "prompt_tokens_details": { "cached_tokens": 0, "text_tokens": 23, "image_tokens": 0 }, "completion_tokens_details": { "text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 0 }, "usage_source": "upstream_response" } } ``` When `response_format` is `b64_json`, each `data` item contains `b64_json` instead of `url`. The value is raw Base64 data without a `data:image/...;base64,` prefix. ## Base64 Response Example Set `response_format` to `b64_json` when your application needs the image bytes in the JSON response. ```bash curl -X POST "{BASE_URL}/v1/images/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2.5-flare", "prompt": "An orange cat sticker, full subject visible, transparent background", "size": "1024x1024", "quality": "medium", "background": "transparent", "output_format": "png", "response_format": "b64_json" }' ``` The response contains raw Base64 data without a `data:image/...;base64,` prefix: ```json { "data": [ { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." } ] } ``` ## Related Pages - [Image Generation Overview](/models/image/overview) - [GPT-Image-2](/models/image/gpt-image-2) - [Models](/models) --- # GPT-Image-2.6 Locale: en URL: https://docs.uniall.ai/models/image/gpt-image-2-6 Source: site-docs/models/image/gpt-image-2-6.md Description: Call GPT Image 2.6 Flare and Sunburst with UniAI synchronous Images API generation, reference editing, masks and GIF output. Generate or edit images with either model. Results return in the same response; no task polling is required. | Model ID | Use case | | --- | --- | | `gpt-image-2.6-flare` | Interactive creation and iteration. | | `gpt-image-2.6-sunburst` | Detailed composition and reference-image editing. | ## Endpoints Use `https://api.uniall.ai` with `Authorization: Bearer $UNIAI_API_KEY`. Replace the key, reference URLs and local file paths with your own values. | Method | Path | Input | | --- | --- | --- | | POST | `/v1/images/generations` | JSON text-to-image request. | | POST | `/v1/images/edits` | JSON references or multipart image files. | ## Parameters Both models use the same fields, with JSON options at the top level. `complexity` controls planning effort independently of `quality` for generation and editing. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | One of the two exact IDs above. | | `prompt` | string | Yes | Generation or editing instruction, up to 32,000 characters. | | `images` | object array | Either for JSON editing | 1–16 ordered reference objects, with URLs in images[].image_url. | | `image_urls` | string array | Either for JSON editing | Compatible form: 1–16 ordered reference URLs. | | `mask` | object | No | Editing only: URL in mask.image_url. Applies to the first reference. | | `markup` | object | No | Editing overlay URL in markup.image_url. Multipart uses a separate markup file. | | `size` | string | No | auto or WIDTHxHEIGHT. Default: auto. Static-image and GIF limits below. | | `quality` | string | No | auto, low, medium, high, xhigh, max; omitted uses the default quality. | | `complexity` | string | No | low, medium, high. Independent planning effort. The console selects high by default; API requests may set it explicitly. | | `n` | integer | No | Requested count, 1–10; default 1. GIF is subject to its pixel budget; use 1. | | `output_format` | string | No | png (default), jpeg, webp, gif. Editing uses PNG/JPEG/WebP; GIF limits below. | | `background` | string | No | auto, opaque, transparent. Transparency requires PNG or WebP. | | `output_compression` | integer | No | 0–100, for JPEG/WebP only. Explicit zero is preserved; no default is applied when omitted. | | `frame_count` | integer | No | GIF only, 2–16; omitted uses 9 for the request pixel budget. | | `frame_duration_ms` | integer | No | GIF only, 20–2000 ms; default 200. Encoded timing rounds to 10 ms. | | `safety_identifier` | string | No | Hashed end-user identifier, up to 128 characters. | | `prompt_rewriter` | JSON | No | Compatibility JSON, preserving explicit 0/false. Shape and availability depend on account access; no public structure is specified. | | `response_format` | string | No | url or b64_json; set it explicitly to select result delivery. | | `moderation` | string | No | auto or low. | For JSON edits, choose the `images` object array or the `image_urls` string array. The `mask` and `markup` objects each contain an `image_url`, as shown below. For explicit static-image dimensions, both sides must be multiples of 16, the longest side must be at most 3,840 pixels, the aspect ratio must be between 1:3 and 3:1, and total pixels must be 655,360–8,294,400. For example: `1024x1024`, `1024x1536`, `1536x1024`, `1536x864` or `2048x1152`. References must be PNG, JPEG or WebP, up to 50 MiB each. URLs must remain reachable without login, cookies or custom headers. A reference may also be a complete image Data URL, such as `data:image/png;base64,...`. ## Generate an image ```bash curl "https://api.uniall.ai/v1/images/generations" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2.6-flare", "prompt": "A sculptural burgundy glass perfume bottle on ivory travertine, warm side lighting, no lettering", "size": "1536x864", "quality": "high", "complexity": "high", "n": 1, "output_format": "png", "response_format": "url" }' ``` For transparent output, set `background` to `transparent` and `output_format` to `png` or `webp`. ## Edit with references and a mask Use `image_urls` for JSON reference strings and `mask.image_url` for the mask: ```bash curl "https://api.uniall.ai/v1/images/edits" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2.6-sunburst", "prompt": "Replace only the masked background with a warm cream studio backdrop; keep the product unchanged", "image_urls": ["https://images.example.com/product.png"], "mask": { "image_url": "https://images.example.com/mask.png" }, "size": "1024x1024", "quality": "high", "complexity": "high", "n": 1, "output_format": "png", "response_format": "url" }' ``` The mask is one PNG with an alpha channel, smaller than 4 MiB and the same dimensions as the first reference. Transparent areas identify where to edit. Omit `mask` for an edit without a mask. ### Edit local files ```bash curl "https://api.uniall.ai/v1/images/edits" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -F "model=gpt-image-2.6-sunburst" \ -F "prompt=Replace only the masked background with a warm cream studio backdrop; keep the product unchanged" \ -F "image[]=@product.png" \ -F "mask=@mask.png" \ -F "size=1024x1024" \ -F "quality=high" \ -F "complexity=high" \ -F "n=1" \ -F "output_format=png" \ -F "response_format=url" ``` Repeat `image[]` for more references, up to 16. Let cURL set the multipart Content-Type. ### Markup editing Send an annotation overlay separately from the reference image: ```bash curl "https://api.uniall.ai/v1/images/edits" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2.6-sunburst", "prompt": "Change only the annotated bottle to blue and remove the annotation strokes", "images": [{"image_url": "https://images.example.com/product.png"}], "markup": {"image_url": "https://images.example.com/overlay.png"}, "complexity": "high", "quality": "high", "size": "1024x1024", "output_format": "png", "response_format": "url" }' ``` The overlay is a transparent PNG smaller than 50 MiB, matching the first reference after orientation. The first image and overlay must each be at most 16,777,216 pixels. Do not combine `markup` with `mask` or `prompt_rewriter`. For local files: ```bash curl "https://api.uniall.ai/v1/images/edits" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -F "model=gpt-image-2.6-sunburst" \ -F "prompt=Change only the annotated bottle to blue and remove the annotation strokes" \ -F "image[]=@product.png" \ -F "markup=@overlay.png" \ -F "complexity=high" \ -F "quality=high" \ -F "size=1024x1024" \ -F "output_format=png" \ -F "response_format=url" ``` ## Generate a GIF Use the generation endpoint with `output_format: "gif"`. Describe motion and looping in `prompt`, then set the frame count and duration: ```bash curl "https://api.uniall.ai/v1/images/generations" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2.6-flare", "prompt": "A silver tabby kitten dancing, alternating its front paws in a smooth seamless loop, fixed camera, cream background", "complexity": "medium", "quality": "high", "output_format": "gif", "size": "256x256", "n": 1, "frame_count": 12, "frame_duration_ms": 120, "response_format": "b64_json" }' ``` GIF dimensions must be multiples of 16, with each side at most 3,840 pixels and `width × height × frame_count × n ≤ 8,294,400`. The static-image minimum pixel count does not apply to GIF frames. GIF excludes masks, markup, compression and prompt rewriting. These are request controls; delivered frames, timing, dimensions and counts may still differ. The current service supports GIF generation only; GIF reference-image editing is unavailable. A response may also include a PNG sprite sheet; inspect every `data[]` item. ## Response With `response_format: "url"`, read the results from `data[].url`. Example: ```json { "data": [ { "url": "https://images.example.com/result.png" } ] } ``` With `response_format: "b64_json"`, decode each `data[].b64_json` value as file bytes. The value has no Data URL prefix. Example with shortened content: ```json { "data": [ { "b64_json": "R0lGODlh..." } ] } ``` The actual file format, dimensions, animation frames, timing and number of results may differ from the request. Optional `output_format` and `size` response fields describe the actual result when present. Inspect the delivered files rather than relying on the requested extension or count. Results retain original GIF bytes and their actual MIME type. Differences from the requested format, dimensions, frames or count do not trigger rejection, conversion or extra generation to reach `n`. If a request fails or times out, do not automatically submit it again. Keep the error and request ID for troubleshooting. Only synchronous Images API calls are supported. Responses sessions, a File ID service and streaming are unavailable; omit `partial_images` or set it to `0`. ## Related pages - [Image Generation Overview](/models/image/overview) - [GPT-Image-2.5](/models/image/gpt-image-2-5) - [Models](/models) --- # Edit Images Locale: en URL: https://docs.uniall.ai/models/image/gpt-image-2/openai-edit Source: site-docs/models/image/gpt-image-2/openai-edit.md Description: GPT-Image-2 edit images endpoint. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. Use `gpt-image-2` to edit reference images. The endpoint returns image URLs synchronously. ## API Parameters and Examples ### Endpoint ```http POST /v1/images/edits/ ``` ### Request Body Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | Use `gpt-image-2`. | | `prompt` | string | Yes | Image editing prompt. | | `image` | string | Yes | Reference image HTTP(S) URL. | | `size` | string | Yes | Output dimensions, such as `1024x1024`. | | `quality` | string | No | `low`, `medium`, or `high`. Default: `medium`. | | `output_format` | string | No | `png`, `jpeg`, or `webp`. | | `background` | string | No | For `gpt-image-2`. `auto` (model chooses from the prompt), `opaque` (opaque background), or `transparent` (transparent background). Omitted or `null`: `auto`. | | `n` | integer | No | Default: `1`; range: `1` to `8`. | | `response_format` | string | No | Use `url` for image URL results. | ### Background Control Background control is pending release. Pass `background` at the top level of the request body. - `auto`: the model chooses the background from the prompt. This is the default when omitted or set to `null`. - `opaque`: request an opaque background. - `transparent`: request a transparent background. Set `output_format` to `png` or `webp`; if omitted, it defaults to `png`. An invalid `background` value or a `transparent`/`jpeg` combination returns HTTP 400 during request validation, before generation starts. ### Request Examples #### Transparent Background The transparent-background request below uses `gpt-image-2` and returns an image URL. ```bash curl -X POST "{BASE_URL}/v1/images/edits" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "prompt": "Keep the product shape and remove the background to make it transparent", "image": "https://example.com/input.png", "size": "1024x1024", "quality": "medium", "background": "transparent", "output_format": "png", "n": 1, "response_format": "url" }' ``` ### Response Fields | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | ### Response Examples #### Example 1 ```json { "created": 1777107492, "data": [ { "url": "https://xxxxx.com/xxxx.png" } ] } ``` --- # Generate Images Locale: en URL: https://docs.uniall.ai/models/image/gpt-image-2/openai-generate Source: site-docs/models/image/gpt-image-2/openai-generate.md Description: GPT-Image-2 generate images endpoint. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. Use `gpt-image-2` to generate images. The endpoint returns image URLs synchronously. ## API Parameters and Examples ### Endpoint ```http POST /v1/images/generations/ ``` ### Request Body Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | Use `gpt-image-2`. | | `prompt` | string | Yes | Image generation prompt. | | `size` | string | No | Output dimensions, such as `1024x1024`, or `auto`. | | `quality` | string | No | `low`, `medium`, or `high`. | | `output_format` | string | No | `png`, `jpeg`, or `webp`. Default: `png`. | | `background` | string | No | For `gpt-image-2`. `auto` (model chooses from the prompt), `opaque` (opaque background), or `transparent` (transparent background). Omitted or `null`: `auto`. | | `n` | integer | No | Default: `1`; range: `1` to `8`. | | `response_format` | string | No | Use `url` for image URL results. | ### Background Control Background control is pending release. Pass `background` at the top level of the request body. - `auto`: the model chooses the background from the prompt. This is the default when omitted or set to `null`. - `opaque`: request an opaque background. - `transparent`: request a transparent background. Set `output_format` to `png` or `webp`; if omitted, it defaults to `png`. An invalid `background` value or a `transparent`/`jpeg` combination returns HTTP 400 during request validation, before generation starts. ### Request Examples #### Example ```json { "model": "gpt-image-2", "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", "prompt": "A cute baby sea otter", "size": "1024x1536", "quality": "medium", "output_format": "png"}' ``` #### Transparent Background The transparent-background request below uses `gpt-image-2` and returns an image URL. ```bash curl -X POST "{BASE_URL}/v1/images/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "prompt": "An orange cat sticker, full subject visible, transparent background", "size": "1024x1024", "quality": "medium", "background": "transparent", "output_format": "png", "n": 1, "response_format": "url" }' ``` ### Response Fields | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | | `created` | integer | Yes | | | | `data` | array | Yes | | | | `usage` | object | Yes | | | ### Response Examples #### Success Example ```json { "created": 1777105463, "data": [ { "url": "https://xxxxxx/xxx.jpg" } ] } ``` --- # Kling Locale: en URL: https://docs.uniall.ai/models/image/kling Source: site-docs/models/image/kling.md Description: Create and edit images with Kling V3, Omni, and Image O1 through UniAll asynchronous image tasks. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. ## Overview Kling image capabilities use `POST /v1/images/tasks`. Select the workflow with `operation`, quality with the top-level `resolution` field, and output count with `num_images`. | Model | Image capabilities | Resolution | | --- | --- | --- | | `kling-v3` | Text-to-image, single-image editing, outpainting, and subject completion | `1k`, `2k` | | `kling-v3-omni` | Text-to-image, single-image editing, multi-image reference, and image series | `1k`, `2k`, `4k` | | `kling-image-o1` | Text-to-image, single-image editing, multi-image reference, and image series | `1k`, `2k`, `4k` | Availability depends on the model catalog, the API key's model permissions, and currently enabled routes. ## When To Use It - Use `kling-v3` for text-to-image, single-image editing, outpainting, or completing a subject from one front-facing image. - Use `kling-v3-omni` for up to four reference images, `4k`, or a series result. - Use `kling-image-o1` for the same multi-image request structure in an image-only model. ## Endpoint | Action | Method | Path | | --- | --- | --- | | Create an asynchronous image task | `POST` | `/v1/images/tasks` | | Query an image task | `GET` | `/v1/images/tasks/{task_id}` | ## Authentication ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## Resolution And Ratios Pass `resolution` at the request body's top level. Do not use `size` in its place. The default is `1k`; omit `resolution` for `outpaint` and `complete_subject`. - V3 supports `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3`, and `21:9`. - Omni and Image O1 support the same ratios plus `auto`. ## Operations | `operation` | Supported models | Required input | | --- | --- | --- | | `text_to_image` | V3, Omni, Image O1 | No input image | | `image_edit` | V3, Omni, Image O1 | One `image` | | `reference_to_image` | Omni, Image O1 | `images` with two to four reference images | | `outpaint` | V3 | One `image` and `outpaint` | | `complete_subject` | V3 | One front-facing `image` | `kling-v3` does not accept two original images for `reference_to_image`. Use `kling-v3-omni` or `kling-image-o1` for multi-image reference. ## Request Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | `kling-v3`, `kling-v3-omni`, or `kling-image-o1`. | | `task_type` | string | Yes | `text2image` for text-to-image; `image2image` for other image operations. | | `operation` | string | Yes | Workflow from the operations table. | | `prompt` | string | Yes | Prompt required by the UniAll asynchronous image interface. | | `image` | string | Conditional | One public image URL for single-image operations. | | `images` | string[] | Conditional | Two to four public image URLs for multi-image reference. | | `resolution` | string | No | `1k`, `2k`, or supported `4k`; default `1k`. Omit for outpainting and subject completion. | | `aspect_ratio` | string | No | Output ratio; supported edit requests may use `auto`. | | `num_images` | integer | No | Number of outputs from `1` to `9`. | | `negative_prompt` | string | No | Negative prompt for V3 text-to-image. | | `result_type` | string | No | `single` or `series` for Omni and Image O1. | | `outpaint` | object | Conditional | Directional expansion ratios for `outpaint`. | | `watermark` | boolean | No | Whether to add an AIGC watermark. | ## Request Examples ### V3 Text-To-Image ```bash curl -X POST "{BASE_URL}/v1/images/tasks" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3", "task_type": "text2image", "operation": "text_to_image", "prompt": "Cinematic product photography of a silver watch on a black stone pedestal.", "negative_prompt": "blur, deformation, text, watermark", "resolution": "2k", "aspect_ratio": "16:9", "num_images": 1, "watermark": false }' ``` ### V3 Single-Image Editing ```bash curl -X POST "{BASE_URL}/v1/images/tasks" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3", "task_type": "image2image", "operation": "image_edit", "prompt": "Preserve the subject identity and replace the background with a clean photography studio.", "image": "https://example.com/person.png", "resolution": "2k", "aspect_ratio": "3:4", "num_images": 1 }' ``` ### Omni Multi-Image Reference In 4K ```bash curl -X POST "{BASE_URL}/v1/images/tasks" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3-omni", "task_type": "image2image", "operation": "reference_to_image", "prompt": "Use the first image as the subject and the second image for clothing and color, producing one cinematic portrait.", "images": [ "https://example.com/person.png", "https://example.com/style.png" ], "resolution": "4k", "aspect_ratio": "16:9", "num_images": 1, "result_type": "single" }' ``` Use the same multi-image structure with `kling-image-o1` by changing only `model`. ### V3 Outpainting ```bash curl -X POST "{BASE_URL}/v1/images/tasks" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3", "task_type": "image2image", "operation": "outpaint", "prompt": "Extend the beach and sky naturally while preserving the original lighting and perspective.", "image": "https://example.com/source.png", "outpaint": { "up_expansion_ratio": 0.2, "down_expansion_ratio": 0, "left_expansion_ratio": 0.1, "right_expansion_ratio": 0.1 }, "num_images": 1, "watermark": false }' ``` Each expansion ratio must be from `0` to `2`, at least one direction must be greater than `0`, and the expanded total area cannot exceed three times the original area. Do not pass `resolution` for outpainting. ### V3 Subject Completion ```bash curl -X POST "{BASE_URL}/v1/images/tasks" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3", "task_type": "image2image", "operation": "complete_subject", "prompt": "Complete the subject image.", "image": "https://example.com/front.png" }' ``` Subject completion accepts one front-facing image. Do not pass `resolution`, `aspect_ratio`, or `num_images`; `prompt` satisfies the common UniAll image-task requirement and does not replace the image input. ## Response Example ```json { "task_id": "task_xxxxxxxxxxxxx", "status": "queued", "progress": "0%", "result_url": "", "metadata": { "task_type": "image2image" }, "error": null } ``` ## Task Status And Result Poll `GET /v1/images/tasks/{task_id}` every 3 to 10 seconds until the task reaches `succeeded` or `failed`. The query response uses outer `code` and `data` fields. On success, read `data.result_url`; for multiple outputs, also read `data.metadata.result_urls`. Do not submit a duplicate paid task because one query request timed out. Continue querying the original `task_id`. See [Async Image Generation](/models/image/async-image-generation) for the common asynchronous image response flow. ## Billing Notes Image billing normally depends on the public model, `operation`, `resolution`, input image count, and output image count. Task submission may reserve balance; the task settlement record and current model catalog price are the final billing source. ## Common Errors - Passing `size` instead of `resolution`. - Requesting `4k` with `kling-v3`. - Passing two original images to `kling-v3` with `reference_to_image`. - Mixing `image`, `images`, and `reference_image_urls` and duplicating the same input. - Passing `resolution` to `outpaint` or `complete_subject`. - Passing media URLs that the service cannot access publicly. - Resubmitting after a query timeout instead of continuing to poll the original task. Public responses do not expose provider names, upstream task IDs, routes, credentials, or raw upstream requests. ## Related Pages - [Kling Video](/models/video/kling) - [Async Image Generation](/models/image/async-image-generation) - [Digital Human Video](/models/avatar/digital-human) --- # Nano Series Locale: en URL: https://docs.uniall.ai/models/image/nano-series Source: site-docs/models/image/nano-series.md Description: Choose a Nano Banana model and its OpenAI or Gemini image interface, including the separate Nano Banana 2.1 guides. Use Nano Series models to generate images from text or edit one or more reference images. UniAll exposes the same API key and model family through two request styles; choose one style for each integration. ## Choose An API Style | Use case | Recommended guide | Result format | | --- | --- | --- | | Nano Banana 2.1 with OpenAI Images fields and reference URLs | [Nano Banana 2.1 — OpenAI Images](./nano-series/nano-banana-2-1/openai-format) | URL in `data[].url` | | Nano Banana 2.1 with Gemini fields and Base64 references | [Nano Banana 2.1 — Gemini generateContent](./nano-series/nano-banana-2-1/gemini-format) | Base64 in `candidates[].content.parts[].inlineData.data` | | `nano-banana-2`, `nano-banana-pro`, or `nano-banana-2-lite` with OpenAI Images or asynchronous jobs | [OpenAI Images Format](./nano-series/openai-format) | URL in `data[].url` | | `nano-banana-2`, `nano-banana-pro`, or `nano-banana-2-lite` with Gemini | [Gemini generateContent Format](./nano-series/gemini-format) | Base64 in `candidates[].content.parts[].inlineData.data` | Both styles use `https://api.uniall.ai` and the same UniAll API key. Do not mix parameter names between the two formats. ## Recommended Models | Model | Resolutions | Default | Recommended use | | --- | --- | --- | --- | | `nano-banana-2.1` | `1k`, `2k`, `4k` | `1k` | Synchronous generation and editing, up to 14 reference images, and thinking control. | | `nano-banana-2` | `0.5k`, `1k`, `2k`, `4k` | `1k` | General generation, editing, and fast 0.5K previews. | | `nano-banana-pro` | `1k`, `2k`, `4k` | `1k` | Higher-detail generation and editing. | | `nano-banana-2-lite` | `1k` | `1k` | Lightweight 1K workloads. | Use these unified, lowercase model IDs for new integrations. Actual availability depends on the models enabled for your account. For Nano Banana 2.1, the Gemini URL uses the official ID `gemini-nano-banana-2.1`. The compatible Gemini URL using `nano-banana-2.1` remains available. OpenAI Images examples use `model: "nano-banana-2.1"`. ## Nano Banana 2.1 Integration The two 2.1 guides describe independent request formats: - OpenAI: `POST /v1/images/generations` for text to image; `POST /v1/images/edits` for editing. Use `Authorization: Bearer ` and top-level `resolution`, `aspect_ratio`, and `thinking_level`. - Gemini: `POST /v1beta/models/gemini-nano-banana-2.1:generateContent`. Use `x-goog-api-key: ` and `generationConfig.imageConfig` / `generationConfig.thinkingConfig`. Both return one image synchronously. 2.1 does not support `/v1/images/tasks` or `/v1/chat/completions`, 0.5K/512/8K, search, custom pixel sizes, masks, transparent backgrounds, or streaming. Omit search fields even when their value is `false`. 2.1 supports 14 aspect ratios: ```markdown 1:1 1:4 1:8 2:3 3:2 3:4 4:1 4:3 4:5 5:4 8:1 9:16 16:9 21:9 ``` Resolution is a tier rather than a fixed longest-edge pixel count; a non-square 1K image can be `1376 × 768`. PNG/JPEG/WebP references retain their order and duplicate entries; duplicates count toward the 14-image limit. Thinking control defaults to `medium` in OpenAI and `MEDIUM` in Gemini. It is available only for 2.1; do not add it to `nano-banana-2`, `nano-banana-pro`, or fixed-resolution compatibility models. ## Supported Aspect Ratios The other three models (`nano-banana-2`, `nano-banana-pro`, and `nano-banana-2-lite`) support: ```markdown 1:1 2:3 3:2 3:4 4:3 4:5 5:4 9:16 16:9 21:9 ``` The resolution field differs by API style: | Output | OpenAI Images | Gemini generateContent | | --- | --- | --- | | 0.5K | `resolution: "0.5k"` | `imageSize: "512"` | | 1K | `resolution: "1k"` | `imageSize: "1K"` | | 2K | `resolution: "2k"` | `imageSize: "2K"` | | 4K | `resolution: "4k"` | `imageSize: "4K"` | 0.5K is available only for `nano-banana-2`. Do not send `512K`, and do not use `0.5k` as a Gemini `imageSize`. ## Legacy Model IDs Earlier fixed-resolution IDs such as `NanoBanana2-1K` and `NanoBananaPro-2K` may remain accepted for compatibility. They are deprecated compatibility aliases and may be removed at any time. New integrations should use a unified model ID and select the resolution in the request. ## Integration Checklist - Keep `n` set to `1`; each request currently generates one image. - Use a server-accessible HTTP(S) URL or a complete Data URL for OpenAI-style reference images. - Use raw Base64 without a `data:image/...;base64,` prefix inside Gemini `inlineData.data`. - Set synchronous client timeouts up to 600 seconds when needed. - Do not retry immediately after a client timeout; the original generation may still complete. - Transfer temporary result URLs to your own storage if you need permanent retention. - Never log API keys or complete Base64 image payloads. ## Related Pages - [Nano Banana 2.1 — OpenAI Images](./nano-series/nano-banana-2-1/openai-format) - [Nano Banana 2.1 — Gemini generateContent](./nano-series/nano-banana-2-1/gemini-format) - [OpenAI Images Format](./nano-series/openai-format) - [Gemini generateContent Format](./nano-series/gemini-format) - [Async Image Generation](/models/image/async-image-generation) --- # Gemini generateContent Format Locale: en URL: https://docs.uniall.ai/models/image/nano-series/gemini-format Source: site-docs/models/image/nano-series/gemini-format.md Description: Generate and edit Nano Series images with the Gemini-compatible generateContent endpoint. This page covers `nano-banana-2`, `nano-banana-pro`, and `nano-banana-2-lite`. For Nano Banana 2.1, use the [dedicated Gemini generateContent guide](/models/image/nano-series/nano-banana-2-1/gemini-format). Thinking control is not enabled for these older models or their fixed-resolution compatibility names. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. Use this format with Gemini-style clients or when you need Base64 image input and output. The model is part of the URL, and image controls belong in `generationConfig.imageConfig`. ## Endpoint ```http POST /v1beta/models/{model}:generateContent ``` Replace `{model}` with `nano-banana-2`, `nano-banana-pro`, or `nano-banana-2-lite`. ## Authentication ```http x-api-key: sk-*** Content-Type: application/json ``` The same UniAll API key works for the OpenAI Images and Gemini formats. ## Request Body Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `contents` | array | Yes | Conversation content containing one user message. | | `contents[].role` | string | Yes | Use `user`. | | `contents[].parts[].text` | string | Yes | Generation or editing instruction. | | `contents[].parts[].inlineData` | object | Conditional | Reference image for editing. Repeat the part for multiple images. | | `inlineData.mimeType` | string | Conditional | Image media type, such as `image/png`. | | `inlineData.data` | string | Conditional | Raw Base64 data without a Data URL prefix. | | `generationConfig.responseModalities` | string[] | Yes | Use `["TEXT", "IMAGE"]` when text and image output are acceptable. | | `generationConfig.imageConfig.imageSize` | string | No | `512`, `1K`, `2K`, or `4K`; defaults to `1K`. Model limits apply. | | `generationConfig.imageConfig.aspectRatio` | string | No | Output ratio such as `1:1`, `3:4`, or `16:9`. | | Model | Supported `imageSize` values | | --- | --- | | `nano-banana-2` | `512`, `1K`, `2K`, `4K` | | `nano-banana-pro` | `1K`, `2K`, `4K` | | `nano-banana-2-lite` | `1K` | ## Request Examples ## Text-To-Image Example ```bash curl -X POST "{BASE_URL}/v1beta/models/nano-banana-2:generateContent" \ -H "x-api-key: sk-***" \ -H "Content-Type: application/json" \ -d '{ "contents": [ { "role": "user", "parts": [ { "text": "A cinematic product photo of a clear perfume bottle on black stone, blue mist, no text" } ] } ], "generationConfig": { "responseModalities": ["TEXT", "IMAGE"], "imageConfig": { "imageSize": "512", "aspectRatio": "1:1" } } }' ``` ## Image Editing Example Encode the image as raw Base64 before building the JSON request: ```bash IMAGE_BASE64="$(base64 < ./reference.png | tr -d '\n')" ``` ```json { "contents": [ { "role": "user", "parts": [ { "text": "Keep the subject and composition; replace the background with a rainy neon street" }, { "inlineData": { "mimeType": "image/png", "data": "BASE64_IMAGE_DATA" } } ] } ], "generationConfig": { "responseModalities": [ "TEXT", "IMAGE" ], "imageConfig": { "imageSize": "2K", "aspectRatio": "3:4" } } } ``` Add another `inlineData` part for each additional reference image. Keep the image order consistent with the prompt. ## Response Examples ```json { "candidates": [ { "content": { "role": "model", "parts": [ { "text": "Image generated." }, { "inlineData": { "mimeType": "image/png", "data": "iVBORw0KGgoAAAANSUhEUgAA..." } } ] }, "finishReason": "STOP" } ] } ``` Find the part containing `inlineData`, Base64-decode its `data`, and save it using the returned `mimeType`. Some clients may normalize the field names to `inline_data` and `mime_type`. ## Python Example ```python import base64 import requests response = requests.post( "https://api.uniall.ai/v1beta/models/nano-banana-2:generateContent", headers={"x-api-key": "sk-***", "Content-Type": "application/json"}, json={ "contents": [{ "role": "user", "parts": [{"text": "An orange cat wearing an astronaut helmet"}], }], "generationConfig": { "responseModalities": ["TEXT", "IMAGE"], "imageConfig": {"imageSize": "512", "aspectRatio": "1:1"}, }, }, timeout=600, ) response.raise_for_status() for candidate in response.json().get("candidates", []): for part in candidate.get("content", {}).get("parts", []): image = part.get("inlineData") or part.get("inline_data") if image and image.get("data"): with open("generated.png", "wb") as output: output.write(base64.b64decode(image["data"])) raise SystemExit(0) raise RuntimeError("response did not contain an image") ``` ## Legacy Model IDs Earlier Gemini preview IDs that encode a fixed resolution may remain accepted for compatibility. They are deprecated and may be removed at any time. New integrations should use a unified Nano model in the URL and select `imageSize` in the request. ## Billing Notes Billing depends on the model and `imageSize`. Check the current model price available to your account. The response may be large because it contains Base64 image data. ## Common Errors - Sending `imageSize: "0.5k"` or `"512K"`; use `"512"` for 0.5K. - Requesting `512` from `nano-banana-pro` or `nano-banana-2-lite`. - Including `data:image/png;base64,` in `inlineData.data`. - Looking only at the first response part instead of finding the part with `inlineData`. - Logging the full Base64 response or API key. ## Related Pages - [Nano Series](../nano-series) - [OpenAI Images Format](./openai-format) --- # Nano Banana 2.1 — Gemini generateContent Locale: en URL: https://docs.uniall.ai/models/image/nano-series/nano-banana-2-1/gemini-format Source: site-docs/models/image/nano-series/nano-banana-2-1/gemini-format.md Description: Generate and edit Nano Banana 2.1 images with the official Gemini model ID, inline Base64 references, and image response parts. ## Overview Use `gemini-nano-banana-2.1` to generate an image from text or edit up to 14 reference images with the Gemini request format. Each synchronous request returns one image as Base64 in an `inlineData` response part. ## Endpoint ```http POST /v1beta/models/gemini-nano-banana-2.1:generateContent ``` The base URL is `https://api.uniall.ai`. The main examples use Google's official model ID `gemini-nano-banana-2.1`. The compatible URL `/v1beta/models/nano-banana-2.1:generateContent` also remains available. ## Authentication Use your UniAI user API key: ```http x-goog-api-key: Content-Type: application/json ``` ## Request Parameters Send one `user` entry in `contents`. Use camelCase field names. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `contents` | array | Yes | Exactly one user-content entry. | | `contents[].role` | string | Yes | `user`. | | `contents[].parts[].text` | string | Yes | Non-empty generation or editing instruction. | | `contents[].parts[].inlineData` | object | Conditional | Reference image for editing; add a part for each image, up to 14. | | `contents[].parts[].inlineData.mimeType` | string | Conditional | `image/png`, `image/jpeg`, or `image/webp`. | | `contents[].parts[].inlineData.data` | string | Conditional | Raw Base64 image bytes without a Data URL prefix. | | `generationConfig.imageConfig.imageSize` | string | No | `1K`, `2K`, or `4K`; defaults to `1K`. | | `generationConfig.imageConfig.aspectRatio` | string | No | One of the 14 ratios below. If omitted, the ratio follows the reference image or generated content. | | `generationConfig.thinkingConfig.thinkingLevel` | string | No | `MINIMAL`, `MEDIUM`, or `HIGH`; defaults to `MEDIUM`. | | `generationConfig.responseModalities` | string[] | No | Defaults to `["IMAGE"]`; also accepts `["TEXT", "IMAGE"]`. Text appears only if final text is actually generated. `["TEXT"]` alone is unsupported. | | `generationConfig.candidateCount` | integer | No | Only `1` is accepted; each request returns one image. | ### Resolution And Reference Images Supported aspect ratios: ```markdown 1:1 1:4 1:8 2:3 3:2 3:4 4:1 4:3 4:5 5:4 8:1 9:16 16:9 21:9 ``` Resolution is a tier, not a fixed longest-edge pixel count. For example, a non-square `1K` result can be `1376 × 768`. `0.5K`, `512`, and `8K` are unsupported. Editing requires 1 to 14 PNG, JPEG, or WebP reference images. Keep them in `parts` in the order described by your prompt. Order and duplicate entries are preserved; duplicates count toward the limit. Set `mimeType` to the actual image type and put only raw Base64 in `data`. ## Request Examples ### Text To Image ```bash curl -X POST "https://api.uniall.ai/v1beta/models/gemini-nano-banana-2.1:generateContent" \ -H "x-goog-api-key: " \ -H "Content-Type: application/json" \ -d '{ "contents": [ { "role": "user", "parts": [ {"text": "Create a spring latte poster with a cream background and clear typography"} ] } ], "generationConfig": { "responseModalities": ["IMAGE"], "imageConfig": {"imageSize": "2K", "aspectRatio": "16:9"}, "thinkingConfig": {"thinkingLevel": "HIGH"}, "candidateCount": 1 } }' ``` ### Image Editing Replace `` with the reference image's raw Base64 bytes before sending this request. ```bash curl -X POST "https://api.uniall.ai/v1beta/models/gemini-nano-banana-2.1:generateContent" \ -H "x-goog-api-key: " \ -H "Content-Type: application/json" \ -d '{ "contents": [ { "role": "user", "parts": [ {"text": "Keep the cup shape and color; replace the background with a bright cafe"}, { "inlineData": { "mimeType": "image/png", "data": "" } } ] } ], "generationConfig": { "responseModalities": ["IMAGE"], "imageConfig": {"imageSize": "2K", "aspectRatio": "4:5"}, "thinkingConfig": {"thinkingLevel": "MEDIUM"}, "candidateCount": 1 } }' ``` Add another `inlineData` part for each additional reference image. To make a later edit, use the previous output image as a reference in a new independent request. ## Response Example ```json { "candidates": [ { "content": { "role": "model", "parts": [ { "inlineData": { "mimeType": "image/png", "data": "" } } ] }, "finishReason": "STOP" } ] } ``` | Response field | Description | | --- | --- | | `candidates[].content.parts[].inlineData` | Final image. Base64-decode `data` and save it according to the returned `mimeType`. | | `candidates[].content.parts[].text` | Optional final text when requesting `["TEXT", "IMAGE"]` and final text is actually generated. Text is not guaranteed. | | `usageMetadata` | May be present when actual usage metadata is available; do not require it to read the image. | Find the part containing `inlineData` rather than assuming the first part is an image. The response is synchronous and has no task ID or polling step. A client timeout does not confirm that generation stopped; avoid automatically submitting the request again. ## Capability Limits And Common Errors - Search is unavailable. Omit `tools`, `enable_web_search`, and `enable_image_search`; supplying them is rejected even when a search flag is `false`. - Only a single user-content entry with text and image references is supported. Multi-turn history, thinking signatures or summaries, video/PDF input, Files, Interactions, and Batch APIs are unavailable in this image integration. - `quality`, custom pixel `size` or `custom_size`, masks, transparent backgrounds, `seed`, and streaming output are unsupported. - Do not use `/v1/chat/completions` or `/v1/images/tasks` for Nano Banana 2.1. - An editing request without a reference image, more than 14 references, a Data URL prefix inside `inlineData.data`, an unsupported image size, text-only output, or a `candidateCount` other than `1` is invalid. - Thinking control is available only for the new 2.1 integration. It is not enabled for `nano-banana-2`, `nano-banana-pro`, or fixed-resolution compatibility models. ## Related Pages - [Nano Series](/models/image/nano-series) - [Nano Banana 2.1 — OpenAI Images](./openai-format) - [Gemini generateContent Format for other Nano models](/models/image/nano-series/gemini-format) --- # Nano Banana 2.1 — OpenAI Images Locale: en URL: https://docs.uniall.ai/models/image/nano-series/nano-banana-2-1/openai-format Source: site-docs/models/image/nano-series/nano-banana-2-1/openai-format.md Description: Generate and edit Nano Banana 2.1 images with OpenAI-style JSON requests, resolution and thinking controls, and URL results. ## Overview Use `nano-banana-2.1` to generate an image from text or edit up to 14 reference images. Each synchronous request returns one image URL. This format suits OpenAI Images clients and integrations that supply reference images as URLs. ## Endpoints | Workflow | Method and path | Input | | --- | --- | --- | | Text to image | `POST /v1/images/generations` | A non-empty `prompt`. | | Image editing | `POST /v1/images/edits` | A non-empty `prompt` and at least one reference image. | The base URL is `https://api.uniall.ai`. Nano Banana 2.1 does not support `/v1/chat/completions` or `/v1/images/tasks`. ## Authentication Use your UniAI user API key: ```http Authorization: Bearer Content-Type: application/json ``` ## Request Parameters Place the main parameters at the top level of the JSON body. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | `nano-banana-2.1`. | | `prompt` | string | Yes | Non-empty generation or editing instruction. | | `resolution` | string | No | `1k`, `2k`, or `4k`; defaults to `1k`. Uppercase values are also accepted. | | `aspect_ratio` | string | No | One of the 14 ratios below. If omitted, the ratio follows the reference image or generated content. | | `thinking_level` | string | No | `minimal`, `medium`, or `high`; defaults to `medium`. | | `images` | string[] | Conditional | Preferred reference-image field for editing. HTTP(S) URLs or complete image Data URLs. | | `image` / `image_url` | string | Conditional | Alternative reference-image fields. HTTP(S) URL or complete image Data URL. | | `image_urls` | string[] | Conditional | Alternative array of reference-image URLs or complete image Data URLs. | | `n` | integer | No | Only `1` is accepted; each request returns one image. | | `num_images` | integer | No | Compatible image-count field; only `1` is accepted. | | `response_format` | string | No | Accepts `url` or `b64_json` for compatibility. This endpoint always returns a URL. | | `output_format` | string | No | Accepts `png` or `jpeg` for compatibility. The actual format follows the result; conversion is not guaranteed. | ### Resolution And Aspect Ratio Supported aspect ratios: ```markdown 1:1 1:4 1:8 2:3 3:2 3:4 4:1 4:3 4:5 5:4 8:1 9:16 16:9 21:9 ``` Resolution is a tier, not a fixed longest-edge pixel count. For example, a non-square `1k` result can be `1376 × 768`. `0.5K`, `512`, and `8K` are unsupported. ### Reference Images And Compatibility Fields Editing requires 1 to 14 reference images across all reference fields combined. PNG, JPEG, and WebP are supported. Input order and duplicate entries are preserved; duplicates count toward the 14-image limit. Reference URLs must be directly accessible to the service. A Data URL must include the image MIME type and Base64 prefix, such as `data:image/png;base64,...`. Use JSON references for editing. Multipart file uploads are unsupported. `resolution`, `thinking_level`, `num_images`, `output_format`, and `response_format` may also be placed in `extra_body` for compatibility. If a field appears both at the top level and in `extra_body`, its values must match. The examples use top-level parameters. ## Request Examples ### Text To Image ```bash curl -X POST "https://api.uniall.ai/v1/images/generations" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-2.1", "prompt": "Create a spring latte poster with a cream background and clear typography", "resolution": "2k", "aspect_ratio": "16:9", "thinking_level": "high", "n": 1 }' ``` ### Image Editing ```bash curl -X POST "https://api.uniall.ai/v1/images/edits" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-2.1", "prompt": "Keep the cup shape and color; replace the background with a bright cafe", "images": ["https://example.com/reference.png"], "resolution": "2k", "aspect_ratio": "4:5", "thinking_level": "medium", "n": 1 }' ``` Replace the example URL with your reference image. Add references to `images` in the order described by your prompt. ## Response Example ```json { "created": 1791676800, "data": [ { "url": "https://example.com/generated.png" } ] } ``` Read `data[0].url` from the completed response. Even if you send `response_format: "b64_json"`, this entry point returns a URL. Inspect the downloaded file to determine its actual image format. The response is synchronous and has no task ID or polling step. A client timeout does not confirm that generation stopped; avoid automatically submitting the request again. ## Capability Limits And Common Errors - Search is unavailable. Omit `tools`, `enable_web_search`, and `enable_image_search`; supplying them is rejected even when a search flag is `false`. - `quality`, custom pixel dimensions through `size` or `custom_size`, masks, transparent backgrounds, `seed`, and streaming output are unsupported. - An editing request without a reference image, more than 14 references, an unsupported resolution or aspect ratio, or a count other than `1` is invalid. - Keep OpenAI field names in this request. Gemini `contents` and `generationConfig` belong to the [Gemini page](./gemini-format). - `thinking_level` is available only for the new 2.1 integration. It is not enabled for `nano-banana-2`, `nano-banana-pro`, or fixed-resolution compatibility models. ## Related Pages - [Nano Series](/models/image/nano-series) - [Nano Banana 2.1 — Gemini generateContent](./gemini-format) - [OpenAI Images Format for other Nano models](/models/image/nano-series/openai-format) --- # OpenAI Images Format Locale: en URL: https://docs.uniall.ai/models/image/nano-series/openai-format Source: site-docs/models/image/nano-series/openai-format.md Description: Generate and edit Nano Series images with synchronous OpenAI Images endpoints or asynchronous UniAll tasks. This page covers `nano-banana-2`, `nano-banana-pro`, and `nano-banana-2-lite`. For Nano Banana 2.1, use the [dedicated OpenAI Images guide](/models/image/nano-series/nano-banana-2-1/openai-format). Thinking control is not enabled for these older models or their fixed-resolution compatibility names. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. Use this format when your integration expects OpenAI-style JSON fields and image URLs. Text-to-image and image editing have synchronous endpoints; UniAll also provides an asynchronous task flow for clients that should not keep a long connection open. ## Endpoints | Workflow | Method and path | Behavior | | --- | --- | --- | | Text to image | `POST /v1/images/generations` | Waits and returns the image URL. | | Image editing | `POST /v1/images/edits` | Waits and returns the image URL. | | Asynchronous generation or editing | `POST /v1/images/tasks` | Returns a task ID immediately. | | Query asynchronous task | `GET /v1/images/tasks/{task_id}` | Returns status and results. | ## Authentication ```http Authorization: Bearer sk-*** Content-Type: application/json ``` `x-api-key: sk-***` is also accepted, but Bearer authentication is recommended for OpenAI-style clients. ## Request Body Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | `nano-banana-2`, `nano-banana-pro`, or `nano-banana-2-lite`. | | `prompt` | string | Yes | Generation or editing instruction. | | `resolution` | string | No | `0.5k`, `1k`, `2k`, or `4k`; defaults to `1k`. Model limits apply. | | `aspect_ratio` | string | No | Output ratio such as `1:1`, `3:4`, or `16:9`. | | `images` | string[] | Conditional | Reference image URLs or complete Data URLs for editing. | | `n` | integer | No | Keep at `1`; each request currently generates one image. | | `output_format` | string | No | Output format such as `png`. | | `request_id` | string | No | Your non-sensitive correlation ID for asynchronous tasks. | 0.5K is available only for `nano-banana-2` and must be written as `resolution: "0.5k"`. ## Request Examples ## Synchronous Text-To-Image ```bash curl -X POST "{BASE_URL}/v1/images/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-2", "prompt": "A cinematic product photo of a clear perfume bottle on black stone, blue mist, no text", "resolution": "0.5k", "aspect_ratio": "1:1", "n": 1, "output_format": "png" }' ``` ## Synchronous Image Editing ```bash curl -X POST "{BASE_URL}/v1/images/edits" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-2", "prompt": "Keep the subject and composition; replace the background with a rainy neon street", "images": ["https://example.com/reference/person.png"], "resolution": "2k", "aspect_ratio": "3:4", "n": 1, "output_format": "png" }' ``` Reference URLs must be directly accessible to the service. Put multiple references in `images` in the order the prompt describes them. ## Response Examples ```json { "created": 1787366400, "data": [ { "url": "https://media.example.com/generated/image.png", "width": 512, "height": 512 } ] } ``` Read `data[0].url` and transfer the asset if you need permanent retention. ## Asynchronous Task Generation and editing share `POST /v1/images/tasks`. Including `images` makes the request an editing task. ```bash curl -X POST "{BASE_URL}/v1/images/tasks" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-2", "prompt": "A cinematic product photo of a clear perfume bottle on black stone", "resolution": "0.5k", "aspect_ratio": "1:1", "n": 1, "output_format": "png", "request_id": "image-20260822-0001" }' ``` ```json { "id": "task_xxx", "task_id": "task_xxx", "object": "image.generation.job", "model": "nano-banana-2", "status": "PENDING", "progress": 0, "image_url": null } ``` Save `task_id`; do not create a replacement merely because the task is still pending. ## Task Status And Result ```bash curl "{BASE_URL}/v1/images/tasks/task_xxx" \ -H "Authorization: Bearer sk-***" ``` Poll every 2 to 3 seconds initially, then back off to every 5 to 10 seconds. Use `?refresh=true` only when you need an immediate upstream refresh, not on every poll. | Status | Meaning | Action | | --- | --- | --- | | `PENDING` | Waiting for processing | Continue polling. | | `IN_PROGRESS` | Generating | Continue polling. | | `COMPLETED` | Finished | Read `data[0].url`; fall back to `image_url`. | | `FAILED` | Failed | Read the public error and stop. | | `CANCELLED` | Cancelled | Stop polling. | ```json { "id": "task_xxx", "task_id": "task_xxx", "model": "nano-banana-2", "status": "COMPLETED", "progress": 100, "image_url": "https://media.example.com/generated/image.png", "data": [ { "url": "https://media.example.com/generated/image.png", "width": 512, "height": 512 } ], "error": null } ``` ## Legacy Model IDs Fixed-resolution aliases such as `NanoBanana2-0.5K` and `NanoBananaPro-4K` may still work for compatibility. They are deprecated and may be removed at any time. Use a unified model ID plus `resolution` for new code. ## Billing Notes Billing depends on the selected model and resolution. Check the current price available to your account. A disconnected synchronous request or client timeout does not guarantee that generation stopped. ## Common Errors - Sending `resolution: "512"` or `"512K"` instead of `"0.5k"`. - Requesting 0.5K from `nano-banana-pro` or `nano-banana-2-lite`. - Supplying a reference URL that requires a login or temporary cookie. - Retrying a timed-out request immediately and creating duplicate generations. - Branching on error-message text instead of HTTP status and structured error fields. ## Related Pages - [Nano Series](../nano-series) - [Gemini generateContent Format](./gemini-format) - [Async Image Generation](/models/image/async-image-generation) --- # Image Generation Overview Locale: en URL: https://docs.uniall.ai/models/image/overview Source: site-docs/models/image/overview.md Description: UniAll image generation API category entry point. Choose a model guide for generation and image editing. ## Included Pages - [Async Image Generation](/models/image/async-image-generation) - [Seedream Image Generation](/models/image/seedream) - [Seedream 5.0 Pro Image Generation](/models/image/seedream-5-0-pro) - [GPT-Image-2 Image Generation](/models/image/gpt-image-2) - [GPT-Image-2.5](/models/image/gpt-image-2-5) - [GPT-Image-2.6](/models/image/gpt-image-2-6) - [Qwen Image](/models/image/qwen-image) - [Nano Series Image Generation](/models/image/nano-series) - [Nano Banana 2.1 — OpenAI Images](/models/image/nano-series/nano-banana-2-1/openai-format) - [Nano Banana 2.1 — Gemini generateContent](/models/image/nano-series/nano-banana-2-1/gemini-format) - [Kling](/models/image/kling) ## Integration Guidance Start with the async image generation page when the selected model uses a polling flow. Kling uses `/v1/images/tasks` with `operation` for text generation, editing, multi-image reference, outpainting, and subject completion. For `seedream-5.0-pro`, use `/v1/images/generations` for text-to-image requests and `/v1/images/edits` for reference-image requests. Nano Banana 2.1 uses synchronous endpoints rather than asynchronous tasks: use the generation/edit endpoints for OpenAI style or `/v1beta/models/gemini-nano-banana-2.1:generateContent` for Gemini style. Choose one request format from the dedicated pages above. GPT Image 2.6 uses the synchronous Images API: `/v1/images/generations` for text-to-image and GIF, and `/v1/images/edits` for reference editing. Flare and Sunburst use their exact model IDs and share the same parameters. --- # Qwen Image Locale: en URL: https://docs.uniall.ai/models/image/qwen-image Source: site-docs/models/image/qwen-image.md Description: Qwen Image 3.0, 2.1 and 2.0 generation and editing with OpenAI Images and the Bailian native synchronous API. Generate or edit images with OpenAI Images or the Bailian native API. Both return image URLs synchronously; no task polling is required. ## Models | Model ID | Maximum reference images | | --- | --- | | `qwen-image-3.0-pro` | 3 | | `qwen-image-3.0` | 3 | | `qwen-image-2.1-pro` | 10 | | `qwen-image-2.1-turbo` | 10 | | `qwen-image-2.0-pro` | 3 | | `qwen-image-2.0` | 3 | ## Endpoints Use `https://api.uniall.ai` with `Authorization: Bearer $UNIAI_API_KEY`. Replace the key and reference URLs in the examples with your own values. | Format | Method | Path | | --- | --- | --- | | OpenAI generation | POST | `/v1/images/generations` | | OpenAI editing (JSON or multipart) | POST | `/v1/images/edits` | | Bailian native generation and editing | POST | `/api/v1/services/aigc/multimodal-generation/generation` | ## Parameters For OpenAI JSON, put these fields at the top level. For the native API, keep `model` at the top level, put the prompt and images in `input.messages`, and generation options in `parameters`. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | One of the six IDs above. | | `prompt` | string | Yes | Generation or editing instruction. Native: one `text` item in `input.messages[0].content`. | | `image` | string or array | Conditional | Ordered reference URLs or image data URLs. Native: one `image` content item per reference. | | `n` | integer | No | Output count, 1–6; default `1`. | | `size` | string | No | `WIDTHxHEIGHT`, `WIDTH*HEIGHT`, or `auto`. See limits below. | | `seed` | integer | No | 0–2147483647. | | `negative_prompt` | string | No | 3.0 and 2.0 families only. | | `prompt_extend` | boolean | No | Enable prompt expansion. | | `prompt_extend_mode` | string | No | `direct` or `agent`; 3.0 and 2.1 only. `agent` is text-to-image only. | | `enable_thinking` | boolean | No | 3.0 and 2.1 families only. | | `watermark` | boolean | No | Add a watermark. | | `response_format` | string | No | OpenAI only: `url`. | OpenAI also accepts `num_images` as an alias for `n`, and `image_url`, `image_urls`, or `images` for references. Use one reference field; `n` and `num_images` must match if both are present. Generation options may be supplied in `extra_body`; duplicated top-level values must match. ## OpenAI Images {/* #openai-images */} ### Generate ```bash curl "https://api.uniall.ai/v1/images/generations" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen-image-3.0", "prompt": "A blue ceramic cup on a wooden table", "n": 1, "size": "1024x1024", "seed": 0, "prompt_extend": false, "enable_thinking": false, "watermark": false }' ``` ### Edit with a reference URL ```bash curl "https://api.uniall.ai/v1/images/edits" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen-image-2.1-pro", "prompt": "Turn the cup blue and keep the rest unchanged", "image": ["https://images.example.com/reference.png"], "n": 1, "size": "1024x1024" }' ``` The same JSON body can be sent to `/v1/images/generations`: including `image` selects editing. Reference-array order is preserved. ### Edit with a local file ```bash curl "https://api.uniall.ai/v1/images/edits" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -F "model=qwen-image-2.1-pro" \ -F "prompt=Turn the cup blue and keep the rest unchanged" \ -F "image[]=@reference.png" \ -F "n=1" \ -F "size=1024x1024" \ -F "seed=0" \ -F "enable_thinking=false" ``` Repeat `-F "image[]=@another.png"` for more references. Form options use integer strings and `true` / `false`; let cURL set the multipart Content-Type. ### Response Generation and editing return the same shape. Read image URLs from `data[].url`. ```json { "created": 1792627200, "data": [ { "url": "https://images.example.com/result.png" } ] } ``` ## Bailian native API {/* #bailian-native */} Use exactly one `user` message containing one `text` item. Add `image` items for editing; omit them for text-to-image. ### Generate ```bash curl "https://api.uniall.ai/api/v1/services/aigc/multimodal-generation/generation" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen-image-3.0", "input": { "messages": [{ "role": "user", "content": [{"text": "A blue ceramic cup on a wooden table"}] }] }, "parameters": { "n": 1, "size": "1024*1024", "seed": 0, "prompt_extend": false, "enable_thinking": false, "watermark": false } }' ``` ### Edit ```bash curl "https://api.uniall.ai/api/v1/services/aigc/multimodal-generation/generation" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen-image-2.1-pro", "input": { "messages": [{ "role": "user", "content": [ {"image": "https://images.example.com/reference.png"}, {"text": "Turn the cup blue and keep the rest unchanged"} ] }] }, "parameters": {"n": 1, "size": "1024*1024"} }' ``` ### Response Read image URLs from `output.choices[].message.content[].image`. ```json { "output": { "choices": [ { "finish_reason": "stop", "message": { "role": "assistant", "content": [ { "image": "https://images.example.com/result.png" } ] } } ] }, "request_id": "req_example" } ``` ## Limits - Output area: 262,144–4,194,304 pixels (512²–2048²); aspect ratio: 1:8–8:1. This is an area limit, not a 2048-pixel limit on each edge. Standard 4K sizes such as `3840x2160` exceed it. - References: up to 10 MB each; per-model counts are listed above. - Results are PNG images. For transparent output on 2.1 models, request a transparent background in the prompt. - Streaming, mask editing and Base64 output are unsupported. Omit `quality`, `output_format` and `operation`. Requests can take tens of seconds. After a timeout, check request records before resubmitting. Save returned images before their URLs expire. ## Request errors For HTTP 400, check required fields, model-specific options, reference counts and size limits. For HTTP 401, check the Bearer key. `/v1/images/edits` requires at least one reference image. --- # Seedream Locale: en URL: https://docs.uniall.ai/models/image/seedream Source: site-docs/models/image/seedream.md Description: Seedream image generation source documentation. this page Seedream image generation model, image model Endpoint, Parameters, constraints, responsesandExample. ## Basic Information ### Authentication All `/v1/*` endpoints require an API key: ```http Authorization: Bearer ``` ### supports Model | Public model | Capability | Billing basis | |---|---|---:| | `seedream-4.0` |, image editing | image | | `seedream-4.5` |, image editing | image | | `seedream-5.0-lite` |, image editing | image | Model name supports andimage editing: | | OperationType | |---|---| | passreference | | | pass `image`/`image_url`/`image_urls`/`images` | image editing | > billing detail recommended: image billing detail. `custom_size`, Landscape, Portrait, Ratio billing detail. ## recommended | scenario | Endpoint | result | return | |---|---|---:|---| |, synchronous | `POST /v1/images/generations`| Yes |`data[].url` | | image editing, synchronous | `POST /v1/images/edits`| Yes |`data[].url` | ## Parameters ### supported parameters | Parameters | Type | | Required | Note | |---|---|---|---:|---| | `model`| string | body | Yes |`seedream-4.0`, `seedream-4.5`, `seedream-5.0-lite` | | `prompt` | string | body | Yes | oreditingprompt | | `n`| integer | body | No | image,`1` `6`. OpenAI compatibility field | | `custom_size`| object | body | No | size,`{"width": 2048, "height": 2048}` | | `image` | string / array | body / form | required for editing | reference URL, pass or | | `image_url`| string / object / array | body / form | required for editing | reference URL, compatibility `{"url": "..."}` | | `image_urls` | array | body / form | required for editing | multiple reference images URL | | `images` | array | body | required for editing | multiple reference images URL, supportsstringorobject | | `timeout_seconds` | integer | body | No | synchronousEndpoint | ### `n` - defaultvalue: `1` - value: `1` - value: `6` Example: ```json { "num_images": 3 } ``` or: ```json { "n": 3 } ``` ## `custom_size` sizeRules format: ```json { "custom_size": { "width": 2048, "height": 2048 } } ``` sizeconstraints: | Model | | | | Whether 16 | |---|---:|---:|---:|---:| | `seedream-4.0`|`921600`|`16777216`|`4096` | No | | `seedream-4.5`|`3686400`|`16777216`|`4096` | No | | `seedream-5.0-lite`|`3686400`|`16777216`|`4096` | No | size: | size | Ratio | `seedream-4.0`|`seedream-4.5`|`seedream-5.0-lite` | |---|---|---:|---:|---:| | `960x960`|`1:1` | | unavailable, below the minimum pixel size | unavailable, below the minimum pixel size | | `1280x720`|`16:9` | | unavailable, below the minimum pixel size | unavailable, below the minimum pixel size | | `720x1280`|`9:16` | | unavailable, below the minimum pixel size | unavailable, below the minimum pixel size | | `2048x2048`|`1:1` | | | | | `2560x1440`|`16:9` | | | | | `1440x2560`|`9:16` | | | | | `2304x1728`|`4:3` | | | | | `1728x2304`|`3:4` | | | | | `4096x4096`|`1:1` |, |, |, | ## reference image editingmode supports URL reference. does not support pass file.: ```json { "image": "https://example.com/a.png" } ``` ```json { "image_url": "https://example.com/a.png" } ``` ```json { "image_url": { "url": "https://example.com/a.png" } } ``` ```json { "image_urls": [ "https://example.com/a.png", "https://example.com/b.png" ] } ``` ```json { "images": [ "https://example.com/a.png", { "url": "https://example.com/b.png" }, { "image_url": "https://example.com/c.png" } ] } ``` editingconstraints: | constraints | value | |---|---:| | reference up to | `10` | | up to | `6` | | + up to | `15` | Example: | reference | `num_images` | |---:|---:| | `1`|`6` | | `5`|`6` | | `9`|`6` | | `10`|`5` | ## synchronous ### ```bash curl -X POST "$BASE_URL/v1/images/generations" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "seedream-4.0", "prompt": "one, and "}' ``` responses: ```json { "created": 1778688000, "data": [ { "url": "https://example.com/generated-1.png" } ] } ``` ### generation 6 ```bash curl -X POST "$BASE_URL/v1/images/generations" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "seedream-4.5", "prompt": ", ", "num_images": 6, "custom_size": {"width": 2048, "height": 2048}}' ``` ### 16:9 Landscape `seedream-4.5` and `seedream-5.0-lite`, recommended `2560x1440`: ```bash curl -X POST "$BASE_URL/v1/images/generations" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "seedream-5.0-lite", "prompt": "16:9, ", "n": 2, "custom_size": {"width": 2560, "height": 1440}}' ``` ### 9:16 Portrait ```bash curl -X POST "$BASE_URL/v1/images/generations" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "seedream-4.5", "prompt": "Portrait, ", "num_images": 1, "custom_size": {"width": 1440, "height": 2560}}' ``` ### `seedream-4.0` sizeExample `1280x720` `seedream-4.0`, `seedream-4.5` and `seedream-5.0-lite`. ```bash curl -X POST "$BASE_URL/v1/images/generations" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "seedream-4.0", "prompt": "Landscape, ", "custom_size": {"width": 1280, "height": 720}}' ``` ## synchronousimage editing ### JSON reference ```bash curl -X POST "$BASE_URL/v1/images/edits" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "seedream-4.0", "prompt": "change image into style, reserved subject ", "image": "https://example.com/source.png", "num_images": 1, "custom_size": {"width": 2048, "height": 2048}}' ``` ### JSON multiple reference images ```bash curl -X POST "$BASE_URL/v1/images/edits" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "seedream-4.5", "prompt": " reference, ", "image_urls": ["https://example.com/product.png", "https://example.com/background.png"], "n": 3, "custom_size": {"width": 2560, "height": 1440}}' ``` ### `images` arrayobject ```bash curl -X POST "$BASE_URL/v1/images/edits" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "seedream-5.0-lite", "prompt": "reference one and, generationone style ", "images": [{"url": "https://example.com/person.png"}, {"image_url": "https://example.com/outfit.png"}], "num_images": 2, "custom_size": {"width": 2048, "height": 2048}}' ``` --- # Seedream 5.0 Pro Locale: en URL: https://docs.uniall.ai/models/image/seedream-5-0-pro Source: site-docs/models/image/seedream-5-0-pro.md Description: Generate or edit images with seedream-5.0-pro through the synchronous UniAll.ai image API. Use `seedream-5.0-pro` through separate synchronous endpoints for text-to-image generation and image editing. Use `/v1/images/generations` without `image` for text-to-image generation. Use `/v1/images/edits` with one to ten reference images for image-to-image generation and editing. This guide reflects the public contract updated on July 25, 2026. ## Overview - Both endpoints return the final image in the same HTTP response. No task polling is required. - Each request generates exactly one image. - You can select a `1K` or `2K` tier with an aspect ratio, or pass exact pixel dimensions. - Reference images can use public URLs or Base64 Data URLs. - The response can contain a temporary image URL or raw Base64 data. ## Endpoint And Authentication ```http POST https://api.uniall.ai/v1/images/generations POST https://api.uniall.ai/v1/images/edits Authorization: Bearer sk-*** Content-Type: application/json ``` - Text to image: call `/v1/images/generations` without `image`. - Image to image or image editing: call `/v1/images/edits` and provide `image`. The Base URL is: ```uri https://api.uniall.ai ``` If the UniAll.ai console provides a dedicated API address for your account, use the address shown in the console. ## Quick Start ### Text To Image ```bash curl -X POST "https://api.uniall.ai/v1/images/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedream-5.0-pro", "prompt": "Premium skincare advertising image, a glass bottle on light stone, soft natural light, sharp and readable brand typography", "size": "2K", "aspect_ratio": "16:9", "output_format": "jpeg", "response_format": "url" }' ``` ### Image To Image ```bash curl -X POST "https://api.uniall.ai/v1/images/edits" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedream-5.0-pro", "prompt": "Keep the product shape and label text, then replace the background with a bright studio scene.", "image": "https://example.com/source-product.png", "size": "1K", "aspect_ratio": "1:1", "output_format": "png", "response_format": "url" }' ``` ### Exact Dimensions Pass exact dimensions through `size` when the output requires a fixed width and height. Do not pass `aspect_ratio` in the same request. ```bash curl -X POST "https://api.uniall.ai/v1/images/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedream-5.0-pro", "prompt": "Wide product-launch key visual, centered technology product, clean background", "size": "2048x1024", "output_format": "jpeg", "response_format": "url" }' ``` ## Request Parameters | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `model` | string | Yes | None | Must be `seedream-5.0-pro`. | | `prompt` | string | Yes | None | Instructions for image generation or editing. | | `image` | string / string[] | Required for image editing | None | Reference images for `/v1/images/edits`. Accepts public URLs or Base64 Data URLs. Maximum: 10 images. | | `size` | string | No | `2K` | `1K`, `2K`, or exact `WIDTHxHEIGHT` dimensions. | | `aspect_ratio` | string | No | Model-selected | Supported with the `1K` and `2K` tiers. Do not use with exact dimensions. | | `output_format` | string | No | `jpeg` | `jpeg` or `png`. | | `response_format` | string | No | `url` | `url` or `b64_json`. | | `watermark` | boolean | No | `true` | Whether to add an "AI generated" watermark. | The model always generates one image per request. ## Size And Aspect Ratio Choose one of the following size modes. ### Resolution Tier And Aspect Ratio ```json { "size": "2K", "aspect_ratio": "16:9" } ``` `size` supports `1K` and `2K`. `aspect_ratio` supports `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, and `21:9`. Common output dimensions are shown below. Treat `data[0].size` in the response as the final value. | Resolution | `1:1` | `4:3` | `3:4` | `16:9` | `9:16` | `3:2` | `2:3` | `21:9` | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `1K` | `1024x1024` | `1152x864` | `864x1152` | `1424x800` | `800x1424` | `1248x832` | `832x1248` | `1568x672` | | `2K` | `2048x2048` | `2368x1776` | `1776x2368` | `2816x1584` | `1584x2816` | `2496x1664` | `1664x2496` | `3136x1344` | When `aspect_ratio` is omitted, the model chooses the composition from the prompt and any reference images. ### Exact Dimensions ```json { "size": "2048x1024" } ``` Exact dimensions must satisfy all of these conditions: - `width * height` must be between `921600` and `4624220`, inclusive. - The width-to-height ratio must be between `1/16` and `16`, inclusive. - There is no separate 4096-pixel maximum edge. For example, `4200x1000` is valid. - `aspect_ratio` must not be present because exact dimensions already determine the composition. ## Reference Images All image-to-image and image-editing requests use `/v1/images/edits`. Pass a string for one reference image or an array for multiple images: ```json { "image": [ "https://example.com/product.png", "data:image/png;base64,..." ] } ``` Public URLs and Base64 Data URLs can be mixed in one request. ### Public URLs - The file must be directly reachable from the public internet. - The request must not depend on cookies, login state, or custom headers. ### Base64 Data URLs Use the complete Data URL format: ```uri data:image/png;base64,... ``` - The image media subtype must be lowercase. This rule does not require the Base64 payload itself to be lowercase. - Supported formats: JPEG, PNG, WEBP, BMP, TIFF, GIF, HEIC, and HEIF. - Each Data URL image can be up to `30 MB`. - A request can contain at most 10 reference images in total. ## Response Formats Input and output formats are independent. A URL input can return Base64 data, and a Base64 input can return a URL. ### URL Response Request field: ```json { "response_format": "url" } ``` Response example: ```json { "created": 1784900000, "data": [ { "url": "https://example.com/generated.jpeg", "size": "2816x1584", "output_format": "jpeg" } ], "usage": { "generated_images": 1, "input_images": 0, "output_tokens": 17424, "total_tokens": 17424 } } ``` The returned URL may expire 24 hours after generation. Download and store the image promptly. ### Base64 Response Request field: ```json { "response_format": "b64_json" } ``` The image item contains `b64_json` instead of `url`: ```json { "data": [ { "b64_json": "...", "size": "2048x1024", "output_format": "png" } ] } ``` `b64_json` contains raw Base64 data without a Data URL prefix. ### Response Fields | Field | Type | Description | | --- | --- | --- | | `created` | integer | Unix timestamp for the response. | | `data` | array | Generated image items. The array contains one item. | | `data[].url` | string | Temporary image URL when `response_format` is `url`. | | `data[].b64_json` | string | Raw Base64 image data when `response_format` is `b64_json`. | | `data[].size` | string | Final output dimensions as `WIDTHxHEIGHT`. | | `data[].output_format` | string | Final image format. | | `usage.generated_images` | integer | Number of generated images. | | `usage.input_images` | integer | Number of reference images. | | `usage.output_tokens` | integer | Output usage reported by the API. | | `usage.total_tokens` | integer | Total usage reported by the API. | ## Prompt Positioning And Markup Express point placement, region edits, text replacement, arrows, sketches, and annotation boxes through the reference image and `prompt`. No additional request parameter is required. ```markdown Replace the sign inside 100 200 800 900 with "New collection" Add a small desk lamp near 520 380 ``` Coordinates use the `0..999` range. You can also draw arrows, boxes, or other marks directly on the input image and describe the intended edit in the prompt. ## Billing Notes - Each request produces exactly one output image. - The number of input images may affect billing. Use the current UniAll.ai model page as the source of truth. - Output billing is split by actual pixel count: up to `2360000` pixels, or more than `2360000` pixels. - The `1K` and `2K` labels do not determine billing directly. The final tier is based on `width * height` from the generated image. - Current unit prices, group multipliers, and final charges are shown on the UniAll.ai model page and in usage records. ## Common Errors | Problem | Likely cause | Resolution | | --- | --- | --- | | The request uses a reference image but does not run as an edit | The request was sent to `/v1/images/generations`. | Send every request containing `image` to `/v1/images/edits`. | | Exact dimensions are rejected | `aspect_ratio` was also provided, or the pixel and ratio limits were exceeded. | Remove `aspect_ratio` and verify the exact-size constraints. | | Reference image is rejected | More than 10 images were provided, the URL is not publicly reachable, or the Data URL is malformed. | Reduce the image count and verify direct access or the complete Data URL format. | | Image format is rejected | The format is unsupported or the Data URL media subtype is not lowercase. | Use a supported format and a lowercase subtype such as `image/png`. | | The expected response field is missing | The client is reading `url` while requesting `b64_json`, or the reverse. | Read the field selected by `response_format`. | | The client times out before receiving an image | The HTTP client timeout is too short for synchronous generation. | Increase the client timeout and wait for the original request instead of polling a task endpoint. | ## Related Pages - [Seedream Image Generation](/models/image/seedream) - [Image Generation Overview](/models/image/overview) - [Models](/models) --- # Gemini Omni Flash Preview Locale: en URL: https://docs.uniall.ai/models/video/gemini-omni-flash-preview Source: site-docs/models/video/gemini-omni-flash-preview.md Description: Generate videos with gemini-omni-flash-preview through the UniAll.ai Gemini Interactions API. Use `gemini-omni-flash-preview` through the UniAll.ai Gemini Interactions API to generate videos from text, one image, multiple images, one video, or a supported combination of images and video. ## Base URL All examples on this page use: ```uri https://api.uniall.ai ``` If the UniAll.ai console provides a dedicated API address for your account, use the address shown in the console. ## Quick Start Generate a video: ```http POST /v1beta/interactions ``` Authenticate with: ```http Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` Minimal text-to-video request: ```bash curl -X POST "https://api.uniall.ai/v1beta/interactions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-omni-flash-preview", "input": "A cinematic robot walking through rain at night.", "response_format": { "type": "video", "aspect_ratio": "16:9" }, "generation_config": { "video_config": { "task": "text_to_video", "resolution": "720p", "duration_seconds": 4 } } }' ``` ## Supported Capabilities | Capability | `task` | Input | | --- | --- | --- | | Text to video | `text_to_video` | A prompt with no image or video | | Image to video | `image_to_video` | A prompt and exactly one image | | Reference generation | `reference_to_video` | A prompt plus images, one video, or a supported image-and-video combination | The following inputs and operations are not currently supported: - audio reference assets; - first-frame and last-frame interpolation; - continuation or editing based on an earlier `interaction_id`; - video extension; - Base64, `inline_data`, or multipart file uploads; - custom resolution, width, or height. ## Request Parameters ### Top-Level Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | Must be `gemini-omni-flash-preview`. | | `input` | string / object / array | Yes | Prompt and optional public image or video URLs. | | `response_format` | object | Yes | Output type and aspect ratio. | | `generation_config` | object | Recommended | Video generation settings. Pass it explicitly for predictable results. | | `timeout_seconds` | integer | No | Maximum time the server waits for a result. Default: `300`. This is not the video duration. | `POST /v1beta/interactions` waits for generation to finish before returning. Set the client-side HTTP timeout higher than `timeout_seconds`; use `600` seconds or more for reference-video requests. ### `response_format` | Parameter | Type | Required | Supported values | Default | | --- | --- | --- | --- | --- | | `type` | string | Yes | `video` | None | | `aspect_ratio` | string | No | `16:9`, `9:16` | `16:9` | - `16:9` creates a landscape video. - `9:16` creates a portrait video. ### `generation_config.video_config` | Parameter | Type | Required | Supported values | Description | | --- | --- | --- | --- | --- | | `task` | string | Recommended | `text_to_video`, `image_to_video`, `reference_to_video` | Pass explicitly so the requested input mode is unambiguous. | | `resolution` | string | No | `720p` | The only supported resolution. Default: `720p`. | | `duration_seconds` | integer | No | `4`, `6`, `8`, `10` | Requested duration. Default: `4`. | When a request includes a video reference, the model may choose the final duration based on that reference. `duration_seconds` does not guarantee the exact output duration in that case. Inspect the returned video file when exact duration matters. ### Task And Asset Combinations | `task` | Images | Videos | Allowed input | | --- | ---: | ---: | --- | | `text_to_video` | 0 | 0 | Prompt only | | `image_to_video` | 1 | 0 | Exactly one image | | `reference_to_video` | 0-7 | 0-1 | Images, multiple images, one video, or images plus one video; at least one asset is required | If `task` is omitted, the API infers it from the supplied assets: - no image or video: `text_to_video`; - exactly one image: `image_to_video`; - multiple images or any video: `reference_to_video`. For stable production behavior, always pass `task` explicitly. ## Input Formats ### Text For text-to-video generation, `input` can be a string: ```json { "input": "A paper boat sailing through a neon city during heavy rain." } ``` ### Content Array The array format is the clearest option and is recommended for requests with reference assets: ```json { "input": [ { "type": "text", "text": "Animate the subject with a slow cinematic camera push-in." }, { "type": "image", "url": "https://example.com/subject.webp" }, { "type": "video", "url": "https://example.com/motion-reference.mp4" } ] } ``` | `type` | Field | Description | | --- | --- | --- | | `text` | `text` | Text prompt | | `image` | `url` | Publicly accessible image URL | | `video` | `url` | Publicly accessible video URL | ### Object Shorthand You can also provide an object with URL fields: ```json { "input": { "text": "Use the references to create one cohesive cinematic shot.", "image_urls": [ "https://example.com/character.png", "https://example.com/environment.jpg" ], "video_urls": [ "https://example.com/camera-motion.mp4" ] } } ``` | Field | Type | Description | | --- | --- | --- | | `text` | string | Prompt | | `image_url` | string | One image URL | | `image_urls` | string[] | Multiple image URLs | | `video_url` | string | One video URL | | `video_urls` | string[] | Video URL array; currently limited to one video | ## Prompt And Asset Limits ### Prompt - Every task should include a non-empty prompt. - The maximum prompt length is `20000` characters. - Multiple text items are combined in order. - Describe the subject, action, camera movement, scene, lighting, pacing, and style. - For reference generation, explain the intended role of each asset. Example: ```markdown Use the first image for the character appearance, the second image for the environment, and the video for camera motion. Create one continuous cinematic shot with natural movement and consistent lighting. ``` ### Images - Supported formats: JPEG, PNG, and WEBP. - Maximum size: `20 MB` per image. - Each URL must be directly reachable from the public internet without cookies, login state, or custom headers. - Up to seven images are allowed when no video is supplied. - `image_to_video` requires exactly one image. ### Video - A request can include at most one reference video. - Maximum file size: `100 MB`. - Maximum input duration: `30` seconds. - MP4 is recommended for broad compatibility. - The model uses at most the first 10 seconds of the reference. - The URL must be directly reachable from the public internet. ### Reference Asset Quota Each image uses one asset unit and each video uses two. The total must not exceed seven: ```uri image count + video count * 2 <= 7 ``` | Images | Videos | Allowed | | ---: | ---: | --- | | 7 | 0 | Yes | | 5 | 1 | Yes | | 6 | 1 | No | | 0 | 1 | Yes | | 0 | 2 | No | ## Request Examples The following examples pass the task and video settings explicitly. ### Landscape Text To Video ```bash curl -X POST "https://api.uniall.ai/v1beta/interactions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-omni-flash-preview", "input": "A wide cinematic shot of an astronaut walking through a field of glowing flowers at dusk, gentle wind, slow dolly-in camera movement.", "response_format": { "type": "video", "aspect_ratio": "16:9" }, "generation_config": { "video_config": { "task": "text_to_video", "resolution": "720p", "duration_seconds": 6 } }, "timeout_seconds": 600 }' ``` ### Portrait Text To Video ```bash curl -X POST "https://api.uniall.ai/v1beta/interactions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-omni-flash-preview", "input": [ { "type": "text", "text": "Vertical fashion film, a model walking through a minimalist white gallery, soft shadows, smooth handheld camera, premium editorial style." } ], "response_format": { "type": "video", "aspect_ratio": "9:16" }, "generation_config": { "video_config": { "task": "text_to_video", "resolution": "720p", "duration_seconds": 10 } }, "timeout_seconds": 600 }' ``` ### Image To Video ```bash curl -X POST "https://api.uniall.ai/v1beta/interactions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-omni-flash-preview", "input": [ { "type": "image", "url": "https://example.com/portrait.webp" }, { "type": "text", "text": "Keep the character appearance consistent. Add subtle breathing and blinking, hair moving gently in the wind, and a slow camera push-in." } ], "response_format": { "type": "video", "aspect_ratio": "9:16" }, "generation_config": { "video_config": { "task": "image_to_video", "resolution": "720p", "duration_seconds": 4 } }, "timeout_seconds": 600 }' ``` ### Multiple Image References ```bash curl -X POST "https://api.uniall.ai/v1beta/interactions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-omni-flash-preview", "input": { "text": "Use the first image for the character, the second for clothing, and the third for the environment. Create one continuous shot of the character entering the cafe and looking toward the camera.", "image_urls": [ "https://example.com/character.png", "https://example.com/outfit.jpg", "https://example.com/cafe.webp" ] }, "response_format": { "type": "video", "aspect_ratio": "16:9" }, "generation_config": { "video_config": { "task": "reference_to_video", "resolution": "720p", "duration_seconds": 8 } }, "timeout_seconds": 600 }' ``` ### One Video Reference ```bash curl -X POST "https://api.uniall.ai/v1beta/interactions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-omni-flash-preview", "input": [ { "type": "video", "url": "https://example.com/dance-motion.mp4" }, { "type": "text", "text": "Create a cinematic dancer performance using the reference for body movement and rhythm. Use dramatic blue stage lighting and a slowly orbiting camera." } ], "response_format": { "type": "video", "aspect_ratio": "16:9" }, "generation_config": { "video_config": { "task": "reference_to_video", "resolution": "720p", "duration_seconds": 8 } }, "timeout_seconds": 600 }' ``` ### Mixed Image And Video References ```bash curl -X POST "https://api.uniall.ai/v1beta/interactions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-omni-flash-preview", "input": { "text": "Use the character image for appearance, the city image for the environment, and the video for camera motion. Keep the character identity and clothing consistent throughout the shot.", "image_urls": [ "https://example.com/character.png", "https://example.com/night-city.jpg" ], "video_urls": [ "https://example.com/camera-reference.mp4" ] }, "response_format": { "type": "video", "aspect_ratio": "16:9" }, "generation_config": { "video_config": { "task": "reference_to_video", "resolution": "720p", "duration_seconds": 10 } }, "timeout_seconds": 600 }' ``` ### Python ```python import requests api_url = "https://api.uniall.ai/v1beta/interactions" headers = { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", } payload = { "model": "gemini-omni-flash-preview", "input": [ { "type": "image", "url": "https://example.com/product.png", }, { "type": "text", "text": ( "Create a premium product film with a slow 360-degree camera " "move, soft studio reflections, and a dark background." ), }, ], "response_format": { "type": "video", "aspect_ratio": "16:9", }, "generation_config": { "video_config": { "task": "image_to_video", "resolution": "720p", "duration_seconds": 6, } }, "timeout_seconds": 600, } response = requests.post( api_url, headers=headers, json=payload, timeout=660, ) response.raise_for_status() result = response.json() print(result["interaction_id"]) print(result["response"]["video"]["uri"]) ``` ### JavaScript ```javascript const response = await fetch("https://api.uniall.ai/v1beta/interactions", { method: "POST", headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ model: "gemini-omni-flash-preview", input: "A tiny red train crossing a snowy mountain bridge at sunrise.", response_format: { type: "video", aspect_ratio: "16:9", }, generation_config: { video_config: { task: "text_to_video", resolution: "720p", duration_seconds: 4, }, }, timeout_seconds: 600, }), }); const result = await response.json(); if (!response.ok) { throw new Error(result.error?.message ?? "Video generation failed"); } console.log(result.interaction_id); console.log(result.response.video.uri); ``` ## Success Response A successful request returns a Gemini Interactions-style response: ```json { "interaction_id": "task_xxx", "model": "gemini-omni-flash-preview", "response": { "video": { "uri": "https://api.uniall.ai/media/generated-video.mp4" } } } ``` | Field | Description | | --- | --- | | `interaction_id` | Unique generation ID that can be used to query the result | | `model` | Public model name used for the request | | `response.video.uri` | Generated video URL | Download and store the generated result promptly. Do not assume that the video URL remains available indefinitely. ## Task Status And Result `POST /v1beta/interactions` normally waits for the interaction result. When a follow-up query is needed, save `interaction_id` and call `GET /v1/videos/generations/{interaction_id}` instead of the default task route. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared terminal statuses, error contract, and result fields. ## Errors And Troubleshooting Errors use a consistent structure: ```json { "error": { "code": 400, "message": "`duration_seconds` must be one of 4, 6, 8, or 10", "status": "INVALID_ARGUMENT" } } ``` | HTTP status | `error.status` | Meaning | | ---: | --- | --- | | `400` | `INVALID_ARGUMENT` | Invalid parameter, asset count, or task mode | | `400` | `FAILED_PRECONDITION` | Request did not pass safety checks | | `401` | `UNAUTHENTICATED` | Missing or invalid API key | | `404` | `NOT_FOUND` | Model or query ID does not exist | | `429` | `RESOURCE_EXHAUSTED` | Request rate is too high | | `503` | `UNAVAILABLE` | Service is temporarily unavailable | | `504` | `DEADLINE_EXCEEDED` | No result was returned within `timeout_seconds` | ## Billing Notes Pricing and billing rules can change. Use the current model price and usage records shown in the UniAll.ai console as the source of truth. Keep the `interaction_id` when reconciling a request or contacting support. ## Recommendations - Pass `task`, `resolution`, `duration_seconds`, and `aspect_ratio` explicitly. - Use HTTPS asset URLs and verify that each URL downloads without authentication. - Set the client HTTP timeout 30-60 seconds higher than `timeout_seconds`. - Treat the output file as the source of truth for the duration of video-reference results. - Explain the role of every asset in the prompt for reference-generation requests. - Retry `429` and `503` responses with exponential backoff. - Never expose an API key in logs, frontend code, or a public repository. --- # Grok Imagine Locale: en URL: https://docs.uniall.ai/models/video/grok-imagine Source: site-docs/models/video/grok-imagine.md Description: Grok Imagine video source documentation. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. Updated: 2026-06-03 This document explains how to call Grok Imagine video model. user requires using this sitestable model and OpenAI compatibilityvideo task endpoint. ## 1. Model | Model | scenario | Billing basis | | --- | --- | --- | | `grok-imagine` | text-to-video, image-to-video, reference-image-to-video, video editing, video extension | capability type, /Output video duration billing detail; image-to-video input image | For new integrations, use `grok-imagine`, input form and `extra_body.operation` Capability. this site's model list Model do not call. ## 2. Endpoint Overview ### 2.1 recommended: OpenAI compatibilityvideo task endpoint ```http POST /v1/videos GET /v1/videos/{task_id} GET /v1/videos/{task_id}/content ``` `POST /v1/videos` submit task, return video task ID. poll `GET /v1/videos/{task_id}` Status. task completed, read response URL,`/v1/videos/{task_id}/content` Get Video File. ### 2.2 compatibility: video task endpoint ```http POST /v1/videos/generations GET /v1/videos/generations/{task_id} POST /v1/video/generations GET /v1/video/generations/{task_id} ``` Endpoint, new recommended `/v1/videos`. ### 2.3 Details ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## 3. fast | | recommendedModel | | Capability | | --- | --- | --- | --- | | promptgenerate video | `grok-imagine`|`prompt`+`duration` | | | oneimage | `grok-imagine`|`prompt`+`image`+`duration` | | | multiple reference imagesgenerate video | `grok-imagine`|`prompt`+`images`+`duration` | | | editing video | `grok-imagine`|`prompt`+`video`+`extra_body.operation=edit_video`, recommended `extra_body.input_video_seconds`|`edit_video` | | video | `grok-imagine`|`prompt`+`video`+`duration`+`extra_body.operation=video_extend`, recommended `extra_body.input_video_seconds`|`video_extend` | Note: `extra_body.operation` Yesthis sitestableCapability. input form the platform; video editingand pass `video`, recommended pass `extra_body.operation`. ## 4. Parameter Reference | Parameters | Type | Required | Note | | --- | --- | --- | --- | | `model`| string | Yes | always pass `grok-imagine` | | `prompt` | string | Yes | video generation, editingor prompt | | `image`| string/object | image-to-videoRequired | single image URL; supports `{"url": "..."}` | | `images` | string[] | multiple reference imagesRequired | multiple reference images URL | | `image_url`/`image_urls` | string/string[] | No | image compatibility field | | `video`| string/object | editing/ Required | video URL; supports `{"url": "..."}` | | `videos` | string[] | No | reference video URL array, reference video Capability | | `size`| string | No |,`480p`, `720p`; video extension does not support Parameters | | `aspect_ratio`| string | No | output aspect ratio; text-to-video `16:9`, `1:1`, `9:16`, single-image-to-video `auto` | | `duration` | integer/string | Conditional | duration., multiple reference images and use; video editing do not pass Field | | `seconds`| string | Conditional | OpenAI compatibilitydurationField; pass `duration` pass `seconds`, do notand `duration` pass both | | `extra_body.operation`| string | No | stableCapability:`text_to_video`, `image_to_video`, `reference_to_video`, `edit_video`, `video_extend` | | `extra_body.input_video_seconds` | integer | editing/ recommended to pass | video billing detail duration, passpositive integer. video duration recommended to pass; pass the platform oruse value | ## 5. duration rules, multiple reference images and pass duration. video editing do not pass duration. | scenario | durationField | supports value | video duration | | --- | --- | --- | --- | | text-to-video | `duration` or `seconds`|`1-15` integer seconds | requires | | single-image-to-video | `duration` or `seconds`|`1-15` integer seconds | requires | | reference-image-to-video | `duration` or `seconds`|`1-10` integer seconds | requires | | video editing | pass `duration`/`seconds`| | recommended to pass `extra_body.input_video_seconds` | | video extension | `duration` or `seconds`|`2-10` integer seconds | recommended to pass `extra_body.input_video_seconds` | Note: - recommended to use `duration`, `"duration": 6`. - If can onlyuse OpenAI compatibility field, pass `seconds`, `"seconds": "6"`. - `duration` and `seconds` one of two required, do not pass both. - video editingand `extra_body.input_video_seconds` Yes video duration, Yes duration. - If video duration, pass `extra_body.input_video_seconds`; the platform video, billing detail duration. - billing detail userpass, Yes task / duration. ## 6. Capability Rules requires pass `extra_body.operation`: - imageandvideo: text-to-video. - one `image`: image-to-video. - `images`: reference-image-to-video. - `video`: recommended pass `edit_video` or `video_extend`. editing video: ```json { "extra_body": { "operation": "edit_video", "input_video_seconds": 8 } } ``` video: ```json { "duration": 6, "extra_body": { "operation": "video_extend", "input_video_seconds": 8 } } ``` ## 7. Request Examples ### 7.1 text-to-video ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{"model": "grok-imagine", "prompt": " camera, fast, camera. ", "size": "720p", "aspect_ratio": "16:9", "duration": 6}' ``` submitresponses: ```json { "id": "task_xxx", "task_id": "task_xxx", "object": "video", "model": "grok-imagine", "status": "queued", "progress": 0, "created_at": 1773980459, "seconds": "6" } ``` ### 7.2 single-image-to-video ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{"model": "grok-imagine", "prompt": " camera, camera. ", "image": "https://example.com/portrait.png", "size": "480p", "aspect_ratio": "auto", "duration": 10}' ``` ### 7.3 reference-image-to-video ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{"model": "grok-imagine", "prompt": " @Image1 @Image2, slow camera push-in. ", "images": ["https://example.com/person.png", "https://example.com/street.png"], "size": "720p", "aspect_ratio": "4:3", "duration": 10}' ``` ### 7.4 video editing ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{"model": "grok-imagine", "prompt": "to change videointo, reserved action and. ", "video": "https://example.com/source.mp4", "size": "720p", "extra_body": {"operation": "edit_video", "input_video_seconds": 8}}' ``` video editing do not pass `duration`/`seconds`. If video duration, recommended to pass `extra_body.input_video_seconds`, and; pass the platform oruse value. ### 7.5 video extension ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{"model": "grok-imagine", "prompt": " camera, video and Orientation. ", "video": "https://example.com/source.mp4", "duration": 6, "extra_body": {"operation": "video_extend", "input_video_seconds": 8}}' ``` video extension `duration` duration, supports `2-10`. If video duration, recommended to pass both `extra_body.input_video_seconds`. ## 8. Task Status And Result After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow. ## 9. Billing Notes Grok video this siteuse billing detail, publicpricing Model. | scenario | billing detail | | --- | --- | | text-to-video | Resolution tier, Output video duration | | single-image-to-video | Resolution tier, Output video duration | | reference-image-to-video | Resolution tier, Output video duration | | video editing | Resolution tier, video duration, Output video duration | | video extension | video duration, Output video duration | public " Parameters "and,: - video: - video 480P: - video 720P: image-to-videoand reference-image-to-video Input image facts, Grok videoRules to change. submit. tasksubmit balance, Yesto change value public. ## 10. Common Errors ### to changevideo model imageEndpoint `grok-imagine` call `/v1/videos`, do not `/v1/images/generations`. ### editingand only pass `video`. editingpass: --- # Grok Imagine Image Locale: en URL: https://docs.uniall.ai/models/video/grok/grok-imagine-image Source: site-docs/models/video/grok/grok-imagine-image.md Description: Grok Imagine image source documentation. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. Updated: 2026-05-29 This document explains how to call Grok Imagine image model. user requires using this sitestable model and OpenAI compatible image endpoint. ## 1. Model | Model | scenario | Billing basis | | --- | --- | --- | | `grok-imagine-image` | standard, image editing | image, Input image billing detail | | `grok-imagine-image-quality` | quality, image editing | quality, image billing detail | recommended generate and editing use `grok-imagine-image`. requires quality or resolution use `grok-imagine-image-quality`. ## 2. Endpoint Overview ### 2.1 recommended: async image task ```http POST /v1/images/tasks GET /v1/images/tasks/{task_id} ``` async task Grok generation. supports, pass through this site supports Parameters, `resolution`, `aspect_ratio`, `output_format`, `num_images`. ### 2.2 compatibility: OpenAI imageEndpoint ```http POST /v1/images/generations POST /v1/images/edits ``` Endpoint OpenAI image format. `/v1/images/edits` supports JSON image URL, supports `multipart/form-data` pass image file. ### 2.3 Details Endpoint use Bearer Token: ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## 3. fast ### 3.1 async ```bash curl -X POST "{BASE_URL}/v1/images/tasks" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{"model": "grok-imagine-image", "task_type": "text2image", "prompt": ", and ", "aspect_ratio": "1:1", "resolution": "1k", "output_format": "jpeg", "num_images": 1, "response_format": "url"}' ``` submitSuccess returntask ID: ```json { "task_id": "task_xxx", "status": "queued", "progress": "0%", "result_url": "", "metadata": { "task_type": "text2image" }, "error": null } ``` Query Task: ```bash curl "{BASE_URL}/v1/images/tasks/task_xxx" \ -H "Authorization: Bearer sk-***" ``` completed responses: ```json { "code": "success", "message": "", "data": { "task_id": "task_xxx", "status": "succeeded", "progress": "100%", "result_url": "https://example.com/result-1.jpeg", "metadata": { "task_type": "text2image", "result_count": 1, "result_urls": [ "https://example.com/result-1.jpeg" ] }, "error": null } } ``` ### 3.2 async image editing ```bash curl -X POST "{BASE_URL}/v1/images/tasks" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{"model": "grok-imagine-image-quality", "task_type": "image2image", "prompt": " subject structure, to change into style, ", "image": "https://example.com/source-watch.png", "aspect_ratio": "auto", "resolution": "2k", "output_format": "webp", "num_images": 2, "response_format": "url"}' ``` ### 3.3 multiple reference imagesediting ```bash curl -X POST "{BASE_URL}/v1/images/tasks" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{"model": "grok-imagine-image-quality", "task_type": "image2image", "prompt": "to change one, Ratioand, style", "images": ["https://example.com/product.png", "https://example.com/stage.png"], "aspect_ratio": "16:9", "resolution": "2k", "output_format": "png", "num_images": 1, "response_format": "url"}' ``` ### 3.4 synchronous compatibilitycall ```bash curl -X POST "{BASE_URL}/v1/images/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{"model": "grok-imagine-image", "prompt": "one, ", "n": 1, "response_format": "url"}' ``` responses: ```json { "created": 1773980459, "data": [ { "url": "https://example.com/image.png", "revised_prompt": "" } ] } ``` ### 3.5 synchronousimage editingcompatibilitycall JSON image URL: ```bash curl -X POST "{BASE_URL}/v1/images/edits" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{"model": "grok-imagine-image", "prompt": "reserved, to change, ", "image": "https://example.com/person.png", "n": 1, "response_format": "url"}' ``` multipart file pass: ```bash curl -X POST "{BASE_URL}/v1/images/edits" \ -H "Authorization: Bearer sk-***" \ -F "model=grok-imagine-image" \ -F "prompt=reserved subject, into " \ -F "n=1" \ -F "response_format=url" \ -F "image=@/path/to/source.png" ``` ## 4. Parameter Reference | Parameters | Type | Required | Note | | --- | --- | --- | --- | | `model`| string | Yes |`grok-imagine-image` or `grok-imagine-image-quality` | | `prompt` | string | Yes | generation or editing prompt | | `task_type`| string | No | async taskuse,`text2image` or `image2image`; pass the platform Whether image | | `image` | string | Required | Input image URL; synchronouseditingandasyncediting supports | | `images` | string[] | editingRequired | multiple reference images URL; recommendedFor new integrations, use Field | | `image_url` | string | No | URL compatibility field | | `image_urls` | string[] | No | URL compatibility field | | `aspect_ratio`| string | No | output aspect ratio;`1:1`, `16:9`, `9:16`, `4:3`, `3:4`, image editing `auto` | | `resolution`| string | No | Resolution tier,`1k`, `2k`; recommended `/v1/images/tasks` use | | `output_format`| string | No |`jpeg`, `png`, `webp` | | `num_images`| integer | No | Generate Images,`1-4`; async taskrecommended to use | | `n`| integer | No | OpenAI compatibility Field, default `1` | | `response_format`| string | No | recommended `url` | recommended: - use for single-image input `image`. - use for multi-image input `images`. - do not `image`, `image_url`, `images`, `image_urls`. ## 5. Billing Notes Grok image this siteuse billing detail, publicpricing Model. | scenario | billing detail | | --- | --- | | | image, Resolution tier, quality | | image editing | Input image, image, Resolution tier, quality | publicpricing Model, " image / ""Input image / "" image / ". submit, Yestask andbalance, public. ## 6. Common Errors ### to changevideo model imageEndpoint `grok-imagine` Yesvideo model, call `/v1/videos` orcompatibilityvideo task endpoint. ### image editing do not pass image `/v1/images/edits` and `task_type=image2image` pass `image` or `images`. ### pass `aspect_ratio=auto` `auto` image editing. recommended pass `1:1`, `16:9`, `9:16` Ratio. ### synchronousEndpointandasyncEndpoint Field If required `resolution`, `num_images` Grok Parameters, prefer using `/v1/images/tasks`. synchronouscompatibilityEndpoint OpenAI image. --- # Grok Video 1.5 Locale: en URL: https://docs.uniall.ai/models/video/grok/grok-video-1-5 Source: site-docs/models/video/grok/grok-video-1-5.md Description: Create text-to-video, single-image, and multi-reference video tasks with Grok Video 1.5 through the UniAll async video API. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. Updated: 2026-08-03 Use the public model `grok-video-1.5` for text-to-video, single-image animation, and multi-image reference generation. Submit a task through the UniAll async video API, then poll the task until it completes or fails. ## 1. Capability Scope | Mode | Image Input | Prompt | Maximum Resolution | | --- | --- | --- | --- | | Text-to-video | No image field | Required | `1080p` | | Single-image-to-video | One `image` or `image_url` | Optional | `1080p` | | Reference-to-video | 1 to 7 `reference_images` or `reference_image_urls` | Required | `720p` | The model also supports: - durations from `1` to `15` seconds, defaulting to `8` seconds; - `480p`, `720p`, and `1080p` output, defaulting to `480p`; - `auto`, `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, and `2:3` aspect ratios; - HTTP(S) image URLs and complete image Data URLs. This public model does not support reference audio, source-video editing, or video extension. Use the existing Grok Imagine video models for edit and extend workflows. ## 2. When To Use It Use `grok-video-1.5` when you need to: - create a video directly from a text prompt; - animate one source image, with or without an additional prompt; - keep a character, product, or visual style consistent across 1 to 7 reference images; - request up to `1080p` for text-to-video or single-image generation. Do not use this model for first-and-last-frame generation, reference audio, video editing, or video extension. ## 3. Endpoint And Authentication Use the primary endpoints for new integrations: | Purpose | Method | Path | | --- | --- | --- | | Create a video task | `POST` | `/v1/videos` | | Query a video task | `GET` | `/v1/videos/{task_id}` | The compatible `/v1/videos/generations` create and query paths remain available. Every request requires a Bearer token: ```http Authorization: Bearer sk-*** ``` Task creation also requires: ```http Content-Type: application/json ``` ## 4. Request Body Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | Must be `grok-video-1.5`. | | `prompt` | string | Conditional | Required for text and reference generation; optional for single-image generation. | | `duration` | integer or integer string | No | `1` to `15`. Defaults to `8`. | | `seconds` | integer or integer string | No | Compatible alias for `duration`. If both are present, their values must match. | | `resolution` | string | No | `480p`, `720p`, or `1080p`. Defaults to `480p`. Reference generation supports up to `720p`. | | `size` | string | No | Compatible alias for `resolution`. If both are present, their values must match. | | `aspect_ratio` | string | No | `auto`, `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, or `2:3`. | | `image` | object | No | One structured image in the form `{"url":"..."}`. | | `image_url` | string | No | Compatible single-image field. | | `reference_images` | object[] | No | 1 to 7 structured images in the form `[{"url":"..."}]`. | | `reference_image_urls` | string[] | No | Compatible array containing 1 to 7 image URLs or Data URLs. | Prefer `duration` over `seconds`, `resolution` over `size`, and the structured `image` or `reference_images` fields in new integrations. ### Image Field Selection The four image fields are mutually exclusive. Choose exactly one field for an image-based request: | Input Shape | Use | | --- | --- | | One structured image | `image: {"url":"..."}` | | One compatible string field | `image_url: "..."` | | Multiple structured references | `reference_images: [{"url":"..."}]` | | Multiple compatible string references | `reference_image_urls: ["..."]` | Do not combine single-image fields with reference-image fields in the same request. ### Supported Image Values Every image value must be either: - a server-accessible `http://` or `https://` URL; or - a complete image Data URL such as `data:image/png;base64,...`. Bare Base64 strings, local file paths, browser-session URLs, `images`, `image_urls`, and every form of `file_id` are rejected. ## 5. Request Examples ### 5.1 Text-To-Video This request uses `1080p` and the default 8-second duration: ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-video-1.5", "prompt": "A quiet mountain lake at sunrise, gentle camera movement, realistic reflections.", "resolution": "1080p", "aspect_ratio": "16:9" }' ``` ### 5.2 Single Image From An HTTP URL The prompt is optional for single-image generation: ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-video-1.5", "image": { "url": "https://example.com/product.jpg" }, "duration": 6, "resolution": "720p" }' ``` ### 5.3 Single Image From A Data URL Pass the complete Data URL, including its media type and Base64 prefix: ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-video-1.5", "prompt": "Subtle camera push-in and natural fabric movement.", "image_url": "data:image/png;base64,iVBORw0KGgo...", "duration": 5, "size": "480p", "aspect_ratio": "9:16" }' ``` ### 5.4 Multiple Reference Images Reference generation accepts 1 to 7 images and is limited to `480p` or `720p`: ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-video-1.5", "prompt": "Keep the character identity and clothing consistent while the character turns toward the camera.", "reference_images": [ {"url": "https://example.com/character-front.jpg"}, {"url": "https://example.com/character-side.jpg"} ], "duration": 5, "resolution": "720p", "aspect_ratio": "9:16" }' ``` ## 6. Response Examples ### Task Created Save `id` or the compatible `task_id` value for polling. ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "grok-video-1.5", "status": "queued", "raw_status": "PENDING", "progress": 0, "created_at": 1785715200, "video_url": null } ``` ## 7. Task Status And Result After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow. ## 8. Aspect Ratio Behavior - If text-to-video omits `aspect_ratio`, the effective default is normally `16:9`. - If single-image generation omits it, output normally follows the source image ratio. - `auto` is accepted as a compatibility value. - For predictable framing, prepare source and reference images in the desired output orientation. ## 9. Billing Notes This page does not define an exact user price. The normalized duration, resolution, and number of input images affect billing: - omitted duration is billed using the 8-second default; - text-to-video has no input-image charge dimension; - single-image generation counts one input image; - reference generation counts every supplied reference image; - higher resolution generally costs more. Check current pricing in the UniAll console and review account usage after task creation. Wait for the original task's terminal state before retrying it. ## 10. Common Errors ### Missing `prompt` `prompt` is required for text-to-video and reference-to-video. It may be omitted only for a single-image request. ### Conflicting Image Fields Do not combine `image`, `image_url`, `reference_images`, or `reference_image_urls`. Choose one field only. ### Invalid Image Encoding Use an HTTP(S) URL or a complete Data URL. A bare Base64 string such as `iVBORw0KGgo...` is invalid. ### Reference Generation At `1080p` Reference generation supports at most `720p`. Use `480p` or `720p`, or switch to text or single-image generation for `1080p`. ### Too Many Reference Images `reference_images` and `reference_image_urls` accept 1 to 7 images. An empty array or more than 7 images is invalid. ### Unsupported Fields Do not pass `file_id`, `reference_audios`, `reference_audio_urls`, `voice_id`, `output`, `storage_options`, or `user`. Do not place them inside `extra_body`. ### Unsupported Video Operations Reference audio, first-and-last-frame generation, video editing, and video extension are not part of `grok-video-1.5`. ## 11. Migration From The Previous Contract | Item | Previous Contract | Current Contract | | --- | --- | --- | | Generation modes | Single-image only | Text, single-image, and 1-to-7-image reference generation | | Image fields | `image_url` only | Structured `image` / `reference_images` plus compatible URL fields | | Image values | HTTP(S) URL only | HTTP(S) URL or complete image Data URL | | Single-image prompt | Required | Optional | | Duration | Required integer `duration` | `duration` or `seconds`, `1..15`, default `8` | | Resolution | `480p` or `720p` | Also `1080p` for text and single-image generation | | Aspect ratio | Six values plus `auto` | Adds `4:3` and `3:4` | Do not migrate to provider-native model names or file IDs. Keep using the stable public model `grok-video-1.5` and the UniAll task endpoints. ## 12. Related Pages - [Query Balance](/balance) - [Grok Imagine Video Generation](/models/video/grok-imagine) - [Grok Imagine Image Generation](/models/video/grok/grok-imagine-image) --- # Hailuo Locale: en URL: https://docs.uniall.ai/models/video/hailuo Source: site-docs/models/video/hailuo.md Description: Create text, single-image, and first-and-last-frame videos with the Hailuo series through the UniAll video task API. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. Updated: 2026-08-04 ## Overview UniAll provides three stable public Hailuo models through the OpenAI-compatible asynchronous video task API. | Model | Text To Video | Single Image | First And Last Frame | | --- | --- | --- | --- | | `hailuo-02` | Supported | Supported | Supported | | `hailuo-2.3` | Supported | Supported | Not supported | | `hailuo-2.3-fast` | Not supported | Supported | Not supported | All three models use the same create, query, and content-download endpoints. The request shape determines the generation mode. ## When To Use It Use the Hailuo series when you need to: - create a 6-second or 10-second video from a prompt; - animate one publicly accessible source image; - generate a first-and-last-frame transition with `hailuo-02`; - choose between `768p` and `1080p` output. The public Hailuo contract does not support audio, multiple reference images, reference videos, aspect-ratio controls, or video editing. ## Limits - `duration` must be `6` or `10` seconds. - `resolution` must be `768p` or `1080p`. - `1080p` only supports a 6-second duration. - Input images must be publicly accessible HTTP(S) URLs. - Prompts can contain up to 2,000 characters. ## Endpoints | Purpose | Method | Path | | --- | --- | --- | | Create a video task | `POST` | `/v1/videos` | | Query a video task | `GET` | `/v1/videos/{task_id}` | | Download the video | `GET` | `/v1/videos/{task_id}/content` | ## Authentication Every request requires a UniAll Bearer token: ```http Authorization: Bearer sk-*** ``` Task creation also requires: ```http Content-Type: application/json ``` ## Request Body Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | `hailuo-02`, `hailuo-2.3`, or `hailuo-2.3-fast`. | | `prompt` | string | Yes | Video description with a maximum length of 2,000 characters. | | `image` | string | Conditional | Public HTTP(S) URL for single-image generation or the first frame. | | `last_image` | string | Conditional | Public HTTP(S) URL for the last frame; only supported by `hailuo-02` and requires `image`. | | `duration` | integer | Yes | `6` or `10`. | | `resolution` | string | Yes | `768p` or `1080p`; `1080p` only supports 6 seconds. | | `prompt_optimizer` | boolean | No | Whether to optimize the prompt before generation. | | `fast_pretreatment` | boolean | No | Whether to use fast preprocessing; do not set it to `true` for first-and-last-frame generation. | | `watermark` | boolean | No | Whether to add an AIGC watermark. | Choose input fields according to the generation mode: | Mode | Model | Input Fields | | --- | --- | --- | | Text to video | `hailuo-02` or `hailuo-2.3` | `prompt` | | Single image | Any Hailuo model | `prompt` + `image` | | First and last frame | `hailuo-02` | `prompt` + `image` + `last_image` | Follow these validation rules: - Do not pass `image` or `last_image` for text-to-video requests. - `hailuo-2.3-fast` only supports single-image generation and therefore requires `image`. - Do not pass `last_image` without `image`. - Use `last_image` only with `hailuo-02`. - Pass all supported parameters at the top level of the request body. - Do not send audio, reference-image arrays, reference videos, aspect ratios, or video-editing fields. ## Request Examples ### Text To Video ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "hailuo-2.3", "prompt": "A cinematic train passes through a snowy mountain canyon while morning mist drifts slowly and the camera moves forward.", "duration": 6, "resolution": "1080p", "prompt_optimizer": true, "watermark": false }' ``` ### Single Image To Video ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "hailuo-2.3-fast", "prompt": "The person naturally raises their head and looks at the camera while face and clothing remain consistent.", "image": "https://example.com/source.png", "duration": 6, "resolution": "768p", "fast_pretreatment": true, "watermark": false }' ``` ### First And Last Frame ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "hailuo-02", "prompt": "Transition naturally from day to night while the building structure remains stable and the motion stays smooth.", "image": "https://example.com/first.png", "last_image": "https://example.com/last.png", "duration": 6, "resolution": "1080p", "prompt_optimizer": true, "watermark": false }' ``` ## Response Examples ### Task Created Save the returned `id` for later queries: ```json { "id": "task_xxxxxxxxxxxxx", "object": "video", "model": "hailuo-2.3", "status": "queued", "progress": 0, "created_at": 1785772800 } ``` ## Task Status And Result After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow. ## Billing Notes The selected model, `duration`, and `resolution` affect billing. A 10-second request is not available at `1080p`. Check the UniAll model page and consumption log for current pricing and final settlement. ## Common Errors Requests are rejected when they: - use a model that does not support the requested generation mode; - pass a `duration` other than `6` or `10`; - request a 10-second video at `1080p`; - omit `image` for `hailuo-2.3-fast`; - pass `last_image` without `image`, or use `last_image` with a model other than `hailuo-02`; - use an image URL that the service cannot access publicly; - request audio, reference videos, multiple reference images, aspect-ratio control, or video editing. Set `watermark` to `false` to request output without an AIGC watermark. Final watermark behavior can also depend on platform availability and model policy. Contact UniAll support when a completed result still contains a watermark unexpectedly. ## Related Pages - [Video Generation Overview](/models/video/overview) - [Models](/models) --- # Happy Horse Locale: en URL: https://docs.uniall.ai/models/video/happy-horse Source: site-docs/models/video/happy-horse.md Description: Create text, image, multi-reference, and video-editing tasks with the unified Happy Horse model through UniAll. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. Updated: 2026-08-10 ## Overview UniAll exposes one stable Happy Horse public model: `happy-horse`. The current public contract provides Happy Horse 1.0 capabilities. Select the generation mode and output tier with request parameters instead of using separate model names. | Operation | `operation` | Required media | Resolution | | --- | --- | --- | --- | | Text-to-video | `text_to_video` | None | `720p`, `1080p` | | Image-to-video | `image_to_video` | Exactly one image | `720p`, `1080p` | | Multi-reference video | `reference_to_video` | 1 to 9 images | `720p`, `1080p` | | Video editing | `edit_video` | Exactly one video; up to 5 optional images | `720p`, `1080p` | Previous tier-specific model IDs are not supported. Always send `model: "happy-horse"` together with `operation` and `resolution`. The public HappyHorse 1.0 contract does not offer `480p`. A request using that resolution is rejected before a task is created. ## When To Use It Use `happy-horse` to: - generate a video from a text prompt; - animate one source image while preserving its composition; - keep characters, products, or styles consistent across multiple reference images; - edit a source video while preserving or automatically handling its original audio. ## Endpoint Use the primary endpoints for new integrations: | Purpose | Method | Path | | --- | --- | --- | | Create a video task | `POST` | `/v1/videos` | | Query a video task | `GET` | `/v1/videos/{task_id}` | | Retrieve the completed video | `GET` | `/v1/videos/{task_id}/content` | The compatible `/v1/videos/generations` and `/v1/video/generations` create and query paths remain available. New clients should use `/v1/videos`. ## Authentication ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## Quick Request Example ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "happy-horse", "operation": "text_to_video", "resolution": "1080p", "prompt": "A white horse runs across a misty grassland at sunrise, cinematic camera movement.", "duration": 7, "aspect_ratio": "16:9", "seed": 12345, "watermark": false }' ``` The create response contains `id` and the compatible `task_id` field. Store either value and poll the task endpoint. ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "happy-horse", "status": "queued", "progress": 0, "created_at": 1785801600, "video_url": null } ``` ## Task Status And Result After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow. ## Billing Notes - Generation tasks are billed by operation, selected resolution tier, and generated duration. - Video editing is finally settled using the actual input and output video durations, so the final charge may differ from the initial estimate. - `resolution` selects a public service tier, not a guaranteed exact pixel width and height. Inspect the returned media metadata when exact dimensions matter. - Use the current UniAll pricing page and task settlement record as the final price source. ## Common Errors - Using a removed tier-specific model ID instead of `happy-horse`. - Omitting the required `operation` or `resolution` parameter. - Sending `resolution: "480p"`; use `720p` or `1080p`. - Sending `size`; Happy Horse uses `resolution` and rejects `size`. - Sending `duration` or `aspect_ratio` for `edit_video`. - Sending `aspect_ratio` for `image_to_video`; this mode follows the source image. - Using private, expired, or otherwise unreachable media URLs. ## Related Pages - [Create a Happy Horse Task](/models/video/happy-horse/create-task) - [Video Generation Overview](/models/video/overview) --- # Create a Happy Horse Video Task Locale: en URL: https://docs.uniall.ai/models/video/happy-horse/create-task Source: site-docs/models/video/happy-horse/create-task.md Description: Create text, image, multi-reference, and video-editing tasks with the unified happy-horse model. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. Updated: 2026-08-10 ## Overview Use the single public model `happy-horse`. Select text generation, image animation, multi-reference generation, or video editing through `operation`, and select the output tier through `resolution`. Do not use the removed tier-specific model IDs. They are intentionally incompatible with the current public contract. ## Endpoint ```http POST /v1/videos ``` Compatible create paths: ```http POST /v1/videos/generations POST /v1/video/generations ``` New integrations should use `/v1/videos`. ## Authentication ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## Operation Matrix | `operation` | Prompt | Image input | Video input | Resolution | `duration` | `aspect_ratio` | | --- | --- | --- | --- | --- | --- | --- | | `text_to_video` | Required | None | None | `720p`, `1080p` | Optional, default `5` | Optional, default `16:9` | | `image_to_video` | Optional | Exactly 1 | None | `720p`, `1080p` | Optional, default `5` | Not supported | | `reference_to_video` | Required | 1 to 9 | None | `720p`, `1080p` | Optional, default `5` | Optional, default `16:9` | | `edit_video` | Required | 0 to 5 | Exactly 1 | `720p`, `1080p` | Not supported | Not supported | ## Request Body Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | Must be `happy-horse`. | | `operation` | string | Yes | `text_to_video`, `image_to_video`, `reference_to_video`, or `edit_video`. | | `resolution` | string | Yes | `720p` or `1080p` for every operation. | | `prompt` | string | Conditional | Required except for `image_to_video`; maximum `2500` characters. | | `duration` | integer | No | Generation only. `3` to `15`, default `5`. Do not send it for editing. | | `aspect_ratio` | string | No | Text and multi-reference generation only. Do not send it for image animation or editing. | | `image` | string | Conditional | Recommended field for the one HTTP(S) image used by `image_to_video`. | | `images` | string[] | Conditional | 1 to 9 HTTP(S) images for `reference_to_video`. | | `reference_image_urls` | string[] | No | Alias for multi-reference images; also supports up to 5 edit reference images. | | `video` | string | Conditional | One HTTP(S) source video for `edit_video`. | | `seed` | integer | No | Random seed from `0` to `2147483647`. | | `watermark` | boolean | No | Whether to add a watermark. Default `false`. | | `audio_setting` | string | No | Editing only: `auto` or `origin`. Default `auto`. | Supported `aspect_ratio` values for text and multi-reference generation: - `16:9` - `9:16` - `1:1` - `4:3` - `3:4` - `4:5` - `5:4` - `9:21` - `21:9` `size` and `enable_safety_checker` are not Happy Horse public parameters and are rejected. `480p` is not available for the public HappyHorse 1.0 contract. Requests that set `resolution` to `480p` are rejected before a task is created. ## Input Rules | Mode | Valid media fields | | --- | --- | | Text-to-video | No image or video field | | Image-to-video | `image`, or one item through a supported image alias | | Multi-reference video | `images` or `reference_image_urls`, with 1 to 9 URLs | | Video editing | `video`, plus up to 5 optional `reference_image_urls` | All media inputs must be complete public HTTP or HTTPS URLs. File uploads, bare Base64 values, and Data URLs are not accepted by this model contract. ## Request Examples ### Text-to-video ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "happy-horse", "operation": "text_to_video", "resolution": "1080p", "prompt": "A white horse runs across a misty grassland at sunrise, realistic movement and soft rim light.", "duration": 7, "aspect_ratio": "21:9", "seed": 12345, "watermark": false }' ``` ### Image-to-video The output composition follows the source image, so do not send `aspect_ratio`. ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "happy-horse", "operation": "image_to_video", "resolution": "720p", "image": "https://example.com/source-frame.png", "prompt": "The subject walks forward naturally while the camera slowly pushes in.", "duration": 5, "seed": 67890, "watermark": false }' ``` The prompt may be omitted for `image_to_video`. ### Multi-reference video Use `character1` through `character9` in the prompt to refer to images in array order. ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "happy-horse", "operation": "reference_to_video", "resolution": "720p", "prompt": "character1 drives character2 across the lunar surface while both identities remain consistent.", "reference_image_urls": [ "https://example.com/character.png", "https://example.com/vehicle.png" ], "duration": 8, "aspect_ratio": "16:9", "seed": 24680, "watermark": false }' ``` ### Video editing Editing follows the source video duration and does not accept `duration` or `aspect_ratio`. ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "happy-horse", "operation": "edit_video", "resolution": "1080p", "prompt": "Replace the jacket with the referenced red jacket while preserving identity, motion, camera movement, and background.", "video": "https://example.com/source-video.mp4", "reference_image_urls": [ "https://example.com/red-jacket.png" ], "audio_setting": "origin", "seed": 13579, "watermark": false }' ``` Use `audio_setting: "origin"` to preserve the original audio. Use `auto` to let the service choose the audio handling behavior. ## `extra_body` Compatibility Top-level parameters are recommended. `operation`, `resolution`, `seed`, `watermark`, and `audio_setting` may also be placed in `extra_body` for compatible clients. Do not send conflicting top-level and nested values. ```json { "model": "happy-horse", "prompt": "Turn the room into a warm wooden studio.", "video": "https://example.com/source-video.mp4", "extra_body": { "operation": "edit_video", "resolution": "720p", "audio_setting": "auto", "watermark": false } } ``` ## Response Examples ### Task accepted ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "happy-horse", "status": "queued", "progress": 0, "created_at": 1785801600, "video_url": null } ``` ## Task Status And Result After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow. For final-settlement operations such as video editing, read `billing_contract` again after completion. ## Media Constraints ### Image-to-video source image - Formats: JPEG, JPG, PNG, BMP, or WebP. - Minimum dimensions: `300px`. - Aspect ratio: from `1:2.5` through `2.5:1`. - Maximum file size: `10MB`. ### Multi-reference images - Formats: JPEG, JPG, PNG, or WebP. - Count: 1 to 9. - Minimum short edge: `400px`; 720p or higher is recommended. - Maximum file size: `10MB` per image. ### Video-editing source - Formats: MP4 or MOV; H.264 is recommended. - Input duration: 3 to 60 seconds; the editing service processes at most 15 seconds. - Dimensions: long edge up to `2160px`, short edge at least `320px`. - Aspect ratio: from `1:2.5` through `2.5:1`. - Frame rate: greater than `8fps`. - Maximum file size: `100MB`. Edit reference images support JPEG, JPG, PNG, or WebP, must be at least `300px`, and are limited to `10MB` each. ## Billing Notes - Text, image, and multi-reference generation use the requested output duration and resolution tier for settlement. - Editing is finally settled from the actual input and output video durations. The final charge can differ from the initial estimate. - `resolution` is a service tier and does not guarantee one exact pixel dimension for every aspect ratio or source image. - Refer to the current UniAll pricing page and task settlement record for the final amount. ## Common Errors | Error | Cause | Fix | | --- | --- | --- | | Invalid model | A removed tier-specific model ID was used | Set `model` to `happy-horse` | | Missing parameter | `operation` or `resolution` is absent | Send both parameters explicitly | | Unsupported parameter | `size` or `enable_safety_checker` was sent | Remove the unsupported field | | Invalid media count | The selected operation received the wrong number of images or videos | Follow the operation matrix | | Invalid resolution | `resolution` is `480p` or another unsupported value | Use `720p` or `1080p` | | Invalid edit options | Editing includes `duration` or `aspect_ratio` | Remove the unsupported fields | | Media download failed | A media URL is private, expired, redirected incorrectly, or unreachable | Use a stable public HTTPS URL | ## Related Pages - [Happy Horse Video Generation](/models/video/happy-horse) - [Video Generation Overview](/models/video/overview) --- # Kling Locale: en URL: https://docs.uniall.ai/models/video/kling Source: site-docs/models/video/kling.md Description: Create Kling text, image, reference, motion-control, and video-editing tasks through UniAll. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. ## Overview Kling video capabilities use stable version-level model IDs. Select quality with the top-level `resolution` field and select the workflow with `operation`; do not encode quality, audio, or an upstream route in the model name. | Model | Video capabilities | Resolution | | --- | --- | --- | | `kling-v3-turbo` | Text-to-video and single-first-frame image-to-video | `720p`, `1080p` | | `kling-v3` | Text-to-video, image-to-video, first-last-frame, motion control, and digital human | `std`, `pro` | | `kling-v3-omni` | Text-to-video, image-to-video, first-last-frame, multimodal reference, and video editing | `std`, `pro` | | `kling-o1` | Text-to-video, image-to-video, first-last-frame, multimodal reference, and video editing | `std`, `pro` | Availability depends on the model catalog, the API key's model permissions, and currently enabled routes. Historical quality, audio, silent, and digital-human tier model IDs are no longer accepted and are not converted automatically. ## When To Use It - Use `kling-v3-turbo` for fast text or single-image video generation with `720p` or `1080p` output. - Use `kling-v3` for first-last-frame generation, motion control, or digital-human video. - Use `kling-v3-omni` for multimodal references and video editing with up to four reference images. - Use `kling-o1` for the same reference and editing request shape with a `3` to `10` second generation range. ## Endpoint | Action | Method | Path | | --- | --- | --- | | Create a video task | `POST` | `/v1/videos` | | Query a video task | `GET` | `/v1/videos/{task_id}` | | Download a completed video | `GET` | `/v1/videos/{task_id}/content` | `POST /v1/videos/generations` and `POST /v1/video/generations` remain compatible creation paths. New integrations should use `POST /v1/videos`. ## Authentication ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## Resolution And Audio Pass `resolution` at the request body's top level. Do not use `size` in its place. When omitted, Turbo defaults to `720p`; the other Kling video models default to `std`. Pass it explicitly when predictable output and billing records matter. Kling video requests do not accept a `sound` switch. Describe dialogue, music, ambient sound, or silence in `prompt`. The `audio_url` and `voice_id` fields used by digital-human tasks are lip-sync inputs, not sound switches. ## Operations | `operation` | Supported models | Required input | | --- | --- | --- | | `text_to_video` | Turbo, V3, Omni, O1 | `prompt` | | `image_to_video` | Turbo, V3, Omni, O1 | `prompt` and `image` | | `first_last_frame` | V3, Omni, O1 | `prompt`, `image`, and `last_image` | | `reference_to_video` | Omni, O1 | `prompt` and image or video references | | `edit_video` | Omni, O1 | `prompt` and `video_url`; reference images are optional | | `motion_control` | V3 | `prompt`, `image`, `video`, and `character_orientation` | | `avatar` | V3 | See [Digital Human Video](/models/avatar/digital-human) | Duration rules: - Turbo and V3 generation operations accept `3` to `15` seconds. - Omni text-to-video, image-to-video, and first-last-frame operations accept `3` to `15` seconds; `reference_to_video` accepts `3` to `10` seconds. - O1 generation operations accept `3` to `10` seconds. - Motion control, digital human, and video editing use the duration rules of their operation; omit `duration` unless the operation explicitly accepts it. - Turbo text-to-video accepts `aspect_ratio`; Turbo image-to-video does not. ## Request Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | Stable Kling video model ID. | | `prompt` | string | Yes | Prompt required by the UniAll video task interface. | | `operation` | string | Recommended | Workflow from the operations table. | | `resolution` | string | No | Model-specific quality value; defaults are described above. | | `duration` | integer | Conditional | Output duration for operations that accept it. | | `aspect_ratio` | string | Conditional | `16:9`, `9:16`, or `1:1`. | | `image` | string | Conditional | Public HTTP(S) image URL for image-to-video or the first frame. | | `last_image` | string | Conditional | Last-frame image URL; use it together with `image`. | | `reference_image_urls` | string[] | No | Up to four reference-image URLs for multimodal reference or editing. | | `video_url` | string | Conditional | Base video URL for reference or editing operations. | | `video` | string | Conditional | Motion-reference video URL for `motion_control`. | | `keep_original_sound` | string | No | `yes` or `no` for multimodal reference and video editing. | | `character_orientation` | string | Conditional | `image` or `video` for `motion_control`. | | `watermark` | boolean | No | Whether to add an AIGC watermark. | ## Request Examples ### Turbo Text-To-Video ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3-turbo", "operation": "text_to_video", "prompt": "A paper airplane crosses a quiet city street at dawn, cinematic camera movement, soft ambient sound.", "duration": 3, "resolution": "720p", "aspect_ratio": "16:9", "watermark": false }' ``` ### Turbo Image-To-Video ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3-turbo", "operation": "image_to_video", "prompt": "The paper airplane glides steadily forward while the camera follows slowly.", "image": "https://example.com/plane.png", "duration": 5, "resolution": "1080p" }' ``` Do not pass `aspect_ratio` for Turbo image-to-video. ### V3 First-Last-Frame ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3", "operation": "first_last_frame", "prompt": "The subject turns naturally toward the camera with a continuous, smooth transition.", "image": "https://example.com/first.png", "last_image": "https://example.com/last.png", "duration": 5, "resolution": "pro" }' ``` ### V3 Motion Control ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3", "operation": "motion_control", "prompt": "Preserve the subject identity and clothing while reproducing the motion from the reference video.", "image": "https://example.com/person.png", "video": "https://example.com/motion.mp4", "resolution": "pro", "character_orientation": "image" }' ``` ### Omni Multimodal Reference ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3-omni", "operation": "reference_to_video", "prompt": "Preserve the subject and clothing while applying the referenced motion to the base video.", "reference_image_urls": [ "https://example.com/person.png", "https://example.com/clothes.png" ], "video_url": "https://example.com/base.mp4", "duration": 8, "resolution": "pro", "keep_original_sound": "yes" }' ``` ### Omni Video Editing ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3-omni", "operation": "edit_video", "prompt": "Keep the subject motion unchanged and replace the background with a city street at night.", "video_url": "https://example.com/source.mp4", "reference_image_urls": [ "https://example.com/city-style.png" ], "resolution": "pro", "keep_original_sound": "yes" }' ``` Use the same text, image, first-last-frame, reference, and editing request shape with `kling-o1`; its generation duration range is `3` to `10` seconds. ## Response Example ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "kling-v3", "status": "queued", "progress": 0 } ``` ## Task Status And Result Save `id` or `task_id`, then follow [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared 3-to-10-second polling interval, terminal statuses, result fields, error contract, and authenticated download flow. ## Billing Notes Video billing normally depends on the public model, `operation`, `resolution`, and actual output duration. Task submission may reserve balance; the task settlement record and current model catalog price are the final billing source. ## Common Errors - Using a historical quality, audio, silent, or digital-human tier model ID instead of one of the version-level IDs above. - Passing `size` instead of `resolution`, or passing `sound` to a video request. - Passing `aspect_ratio` to Turbo image-to-video. - Requesting a duration outside the selected model and operation range. - Mixing `image`, `reference_image_urls`, and video inputs in a way that duplicates the same reference. - Passing image or video URLs that the service cannot access publicly. - Resubmitting a paid task after one polling request times out instead of continuing to query the original `task_id`. Public responses do not expose provider names, upstream task IDs, routes, credentials, or raw upstream requests. ## Related Pages - [Kling Image](/models/image/kling) - [Digital Human Video](/models/avatar/digital-human) - [Video Generation Overview](/models/video/overview) --- # MiniMax H3 / H3 Max Locale: en URL: https://docs.uniall.ai/models/video/minimax-h3 Source: site-docs/models/video/minimax-h3.md Description: Create MiniMax H3 and H3 Max video tasks with the native JSON API, including query, media references, Context, regeneration and task management. Use the MiniMax native video API with your UniAI API key. - Base URL: `https://api.uniall.ai` - Models: `MiniMax-H3`, `MiniMax-H3-Max` - Content type: `application/json` ## Endpoints | Method | Path | Use | | --- | --- | --- | | POST | `/v2/video_generation` | Create a video | | POST | `/v2/h3_context_ir` | Create a Context prompt | | POST | `/v2/video_regeneration` | Regenerate an H3 video at 2K | | GET | `/v2/query/video_generation/{task_id}` | Query a task | | GET | `/v2/query/video_generation` | List tasks | | DELETE | `/v2/video_generation/{task_id}` | Cancel or delete a task | ## Create a video See [request examples](/models/video/minimax-h3/examples) for frame, reference, H3 Max, Context, and regeneration requests. ```bash curl -X POST "https://api.uniall.ai/v2/video_generation" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniMax-H3", "content": [ { "type": "text", "text": "A paper boat crosses a quiet pond in warm morning light." } ], "duration": 5, "resolution": "768P", "ratio": "16:9" }' ``` Response: ```json { "task_id": "task_YOUR_VIDEO" } ``` ## Parameters | Field | Required | Values | | --- | --- | --- | | `model` | Yes | `MiniMax-H3` or `MiniMax-H3-Max` | | `content` | Yes | One `text` item and optional media items | | `duration` | Yes | H3: integer 4–15; H3 Max: integer 5–15 | | `resolution` | No | H3: `768P` or `2K`; H3 Max: `480P` or `768P`. Default: `768P` | | `ratio` | Text only | Text-only requests require a concrete ratio. Frame input uses `adaptive`; references default to `adaptive`. Accepted values: `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `adaptive`. | | `aigc_watermark` | No | Boolean; default `false` | | `extra.prompt_expansion_mode` | H3 Max only | `disabled`, `balanced` (default), or `quality` | | `callback_url` | No | Public HTTP(S) URL. Return the verification `challenge` unchanged within 3 seconds; otherwise poll the query endpoint. | ## Add images, video, or audio Put media in `content`. Each request must contain one text item (up to 7,000 characters). | Type | Role | | --- | --- | | `image_url` | `first_frame`, `last_frame`, or `reference_image` | | `video_url` | `reference_video`; use `base_video` only for regeneration | | `audio_url` | `reference_audio` | Use `{"url":"https://..."}` for each media field. Image role defaults to `first_frame`. Frame images and reference media cannot be mixed. Example with a first frame: ```json { "model": "MiniMax-H3", "content": [ { "type": "text", "text": "A paper boat crosses a quiet pond in warm morning light." }, { "type": "image_url", "image_url": { "url": "https://YOUR_PUBLIC_URL/first.png" }, "role": "first_frame" } ], "duration": 5, "resolution": "768P" } ``` Limits: up to 9 images, 3 videos, and 3 audio files (12 media items total). Images: JPEG, PNG, WEBP, HEIC, or HEIF; 30 MB each; dimensions 256–5,760 px. Video: MP4 or MOV, 50 MB each, 23.976–60 fps; 2–15 seconds each and 15 seconds total. Audio: WAV or MP3, 15 MB each; 2–15 seconds each and 15 seconds total. Use publicly accessible URLs or matching data URIs. This API does not upload media. ## Query a task Poll the returned ID: ```bash curl "https://api.uniall.ai/v2/query/video_generation/task_YOUR_VIDEO" \ -H "Authorization: Bearer $UNIAI_API_KEY" ``` Video task response: ```json { "task": { "id": "task_YOUR_VIDEO", "model": "MiniMax-H3", "status": "succeeded", "task_type": "generation", "modality": "video", "content": { "url": "https://YOUR_RESULT_URL/video.mp4" } } } ``` Statuses: `queued`, `running`, `succeeded`, `failed`, `cancelled`. Download a completed video from `task.content.url`. ## Context Context returns an enhanced prompt; it does not create a video. Use H3 and omit `resolution`. ```bash curl -X POST "https://api.uniall.ai/v2/h3_context_ir" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniMax-H3", "content": [ { "type": "text", "text": "A paper boat crosses a quiet pond in warm morning light." } ], "duration": 5, "ratio": "16:9" }' ``` Query it with the same task endpoint. The result prompt is in `task.content.prompt`. ## Regenerate at 2K Regeneration is H3 only. Use a completed H3 768P task created by your account within the last seven days: ```bash curl -X POST "https://api.uniall.ai/v2/video_regeneration" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniMax-H3", "source_task_id": "task_YOUR_COMPLETED_H3_768P", "resolution": "2K" }' ``` Alternatively, send the original prompt and all original inputs with one `base_video` item in `content`. Do not send `duration` or `ratio`. ## List, cancel, or delete tasks ```bash curl "https://api.uniall.ai/v2/query/video_generation?page_num=1&page_size=10" \ -H "Authorization: Bearer $UNIAI_API_KEY" ``` List response contains `items` and `total`. Use `page_num`, `page_size` and `filter.model`, `filter.task_type`, `filter.task_ids`, or `filter.status`. Native task history is available for seven days. ```bash curl -X DELETE "https://api.uniall.ai/v2/video_generation/task_YOUR_VIDEO" \ -H "Authorization: Bearer $UNIAI_API_KEY" ``` DELETE cancels a queued task or deletes a succeeded/failed task. It does not cancel a running task. ## Errors HTTP errors use this response shape: ```json { "type": "error", "error": { "type": "bad_request_error", "message": "Invalid request parameters.", "http_code": "400" }, "request_id": "opaque_request_id" } ``` A failed task is returned with `task.status` set to `failed` and an `task.error` object. If a create request times out, check for the task before submitting again. --- # MiniMax H3 / H3 Max Examples Locale: en URL: https://docs.uniall.ai/models/video/minimax-h3/examples Source: site-docs/models/video/minimax-h3/examples.md Description: Copyable MiniMax native API requests for H3 and H3 Max video generation, media references, Context, and 2K regeneration. # MiniMax H3 / H3 Max Request Examples Replace `$UNIAI_API_KEY` and media URLs with your own values. Send one request at a time. ## Text to video ```bash curl -X POST "https://api.uniall.ai/v2/video_generation" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniMax-H3", "content": [ { "type": "text", "text": "A paper boat crosses a quiet pond in warm morning light." } ], "duration": 5, "resolution": "2K", "ratio": "16:9" }' ``` ## First and last frame ```bash curl -X POST "https://api.uniall.ai/v2/video_generation" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniMax-H3", "content": [ { "type": "text", "text": "The camera moves from the first frame to the last." }, { "type": "image_url", "image_url": { "url": "https://YOUR_PUBLIC_URL/first.png" }, "role": "first_frame" }, { "type": "image_url", "image_url": { "url": "https://YOUR_PUBLIC_URL/last.png" }, "role": "last_frame" } ], "duration": 5, "resolution": "768P" }' ``` ## Image, video, and audio references ```bash curl -X POST "https://api.uniall.ai/v2/video_generation" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniMax-H3", "content": [ { "type": "text", "text": "A person speaks while walking through the city." }, { "type": "image_url", "image_url": { "url": "https://YOUR_PUBLIC_URL/person.png" }, "role": "reference_image" }, { "type": "video_url", "video_url": { "url": "https://YOUR_PUBLIC_URL/walking.mp4" }, "role": "reference_video" }, { "type": "audio_url", "audio_url": { "url": "https://YOUR_PUBLIC_URL/voice.mp3" }, "role": "reference_audio" } ], "duration": 5, "resolution": "768P", "ratio": "adaptive" }' ``` ## H3 Max ```bash curl -X POST "https://api.uniall.ai/v2/video_generation" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniMax-H3-Max", "content": [ { "type": "text", "text": "A paper boat crosses a quiet pond in warm morning light." } ], "duration": 5, "resolution": "768P", "ratio": "16:9", "extra": { "prompt_expansion_mode": "balanced" } }' ``` ## Context Returns a processed prompt; it does not create a video. Omit `resolution`. ```bash curl -X POST "https://api.uniall.ai/v2/h3_context_ir" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniMax-H3", "content": [ { "type": "text", "text": "A paper boat crosses a quiet pond in warm morning light." } ], "duration": 5, "ratio": "16:9" }' ``` ## Regenerate at 2K Use your own completed H3 768P task, created within the last seven days. ```bash curl -X POST "https://api.uniall.ai/v2/video_regeneration" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniMax-H3", "source_task_id": "task_YOUR_COMPLETED_H3_768P", "resolution": "2K" }' ``` --- # Video Generation Overview Locale: en URL: https://docs.uniall.ai/models/video/overview Source: site-docs/models/video/overview.md Description: Create, poll, and retrieve UniAll video generation tasks through one shared lifecycle. UniAll video models share one default asynchronous task lifecycle. Use each model page for model IDs, input fields, and capability limits; use this page for task polling, status handling, errors, and result retrieval. ## Models - [Happy Horse](/models/video/happy-horse) - [Seedance 2.0](/models/video/seedance-2-0) - [Seedance 2.5](/models/video/seedance-2-5), including [Draft to final video](/models/video/seedance-2-5#draft-to-final) - [Grok Video 1.5](/models/video/grok/grok-video-1-5) - [Grok Imagine](/models/video/grok-imagine) - [Veo 3.1](/models/video/veo-3-1) - [Gemini Omni Flash Preview](/models/video/gemini-omni-flash-preview) - [Vidu Q3](/models/video/vidu) - [Hailuo](/models/video/hailuo) - [MiniMax H3 / H3 Max native API](/models/video/minimax-h3) - [Kling](/models/video/kling) - [Wan 2.6](/models/video/wan-2-6) - [Sora 2](/models/video/sora-2) ## Default Endpoints `{BASE_URL}` is `https://api.uniall.ai`. | Action | Method | Endpoint | | --- | --- | --- | | Create a task | `POST` | `/v1/videos` | | Query status and result | `GET` | `/v1/videos/{task_id}` | | Download completed content | `GET` | `/v1/videos/{task_id}/content` | Send `Authorization: Bearer sk-***` on every request. A model page may document a compatible creation path or a protocol-specific exception; its model IDs and request body still come from that model page. ## Video Task Lifecycle ### 1. Save The Task ID A successful create request returns a public `id`. Some responses also include the same value as `task_id` for compatibility. Store either value before leaving the request flow. ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "model-name", "status": "queued", "progress": 0, "created_at": 1785801600 } ``` ### 2. Poll The Task Query the task every 3 to 10 seconds: ```bash curl "{BASE_URL}/v1/videos/task_xxxxxxxxxxxxx" \ -H "Authorization: Bearer sk-***" ``` Stop only when `status` becomes `completed` or `failed`. Do not create a duplicate task only because the current task remains `queued` or `in_progress`. | Status | Terminal | Meaning | | --- | --- | --- | | `queued` | No | The task was accepted and is waiting for processing. | | `in_progress` | No | Generation or result processing is still running. | | `completed` | Yes | The final result is ready. | | `failed` | Yes | The task ended without a result; inspect `error`. | ### 3. Read The Result A completed task returns the public result in `video_url`, `result.video_url`, or `result.outputs[0]`. These fields can point to the same video. ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "model-name", "status": "completed", "progress": 100, "video_url": "https://example.com/generated-video.mp4", "result": { "video_url": "https://example.com/generated-video.mp4", "outputs": [ "https://example.com/generated-video.mp4" ] }, "error": null } ``` Prefer the returned `video_url` to download the completed video. The authenticated content endpoint is also available: ```bash curl -L "{BASE_URL}/v1/videos/task_xxxxxxxxxxxxx/content" \ -H "Authorization: Bearer sk-***" \ -o output.mp4 ``` Do not call the content endpoint before completion. Download generated media promptly instead of treating a result URL as permanent storage. ### 4. Handle Failure ```json { "id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "model-name", "status": "failed", "progress": 100, "result": null, "error": { "code": "task_failed", "message": "Video generation failed" } } ``` Fix invalid inputs before creating a new task. Retry transient service errors with backoff, but do not repeatedly resubmit the same request while the original task is still active. For Seedance 2.5, do not automatically retry creation after failure, a client timeout, or an uncertain outcome. Continue querying the existing task ID, or establish the original request's outcome before submitting again. This includes Draft finalization; see the [model-specific workflow](/models/video/seedance-2-5#draft-to-final). ## Shared Response Fields | Field | Type | Description | | --- | --- | --- | | `id` | string | Public task ID used for polling. | | `task_id` | string | Compatible alias of `id` when present. | | `object` | string | Task object type, commonly `video.generation.job`. | | `model` | string | Public model ID used for creation. | | `status` | string | `queued`, `in_progress`, `completed`, or `failed`. | | `progress` | integer | Progress from `0` to `100` when available; it does not replace `status`. | | `video_url` | string or null | Public result URL after completion. | | `result` | object or null | Completed output details, including `video_url` or `outputs`. | | `error` | object or null | Public `code` and `message` for a failed task. | | `created_at` | integer | Unix creation timestamp when available. | | `completed_at` | integer | Unix completion timestamp when available. | ## Model-Specific Exceptions MiniMax H3 task details use a `task` object and the statuses `queued`, `running`, `succeeded`, `failed`, and `cancelled`. Use the [H3 native API guide](/models/video/minimax-h3) for request and response examples. Gemini Omni Flash Preview creates requests through `POST /v1beta/interactions`. When a follow-up query is needed, use the returned `interaction_id` with `GET /v1/videos/generations/{interaction_id}`. Its terminal statuses, error handling, and result fields follow the same rules above. Protocol-specific pages such as Sora 2 Native OpenAI Format may stream their own response instead of returning a standard video task. Follow the response flow documented on that page. --- # Seedance 2.0 Locale: en URL: https://docs.uniall.ai/models/video/seedance-2-0 Source: site-docs/models/video/seedance-2-0.md Description: Generate videos with Seedance 2.0 models through UniAll video APIs. Seedance 2.0 supports text-to-video, image-to-video, first-and-last-frame generation, multimodal references, video editing, and video extension. Start with the [Seedance 2.0 Series Guide](/models/video/seedance-2-0/series-guide) for new integrations. Use the [Seedance 2.0 Material Library](/models/video/seedance-2-0/material-library) to create reusable media, wait for `available`, and use the returned `uri` in video requests. ## Supported Models | Model | Supported Resolutions | Recommended Use | | --- | --- | --- | | `seedance2.0` | `480p`, `720p`, `1080p`, `4k` | Full capabilities with quality prioritized. | | `seedance2.0-fast` | `480p`, `720p` | Faster generation. | | `seedance2.0-mini` | `480p`, `720p` | Lightweight and speed-focused tasks. | ## Endpoint ```http POST /v1/videos GET /v1/videos/{task_id} GET /v1/videos/{task_id}/content ``` The older `/v1/videos/generations` and `/v1/video/generations` creation endpoints remain available for compatible clients. ## Authentication ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## Request Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | `seedance2.0`, `seedance2.0-fast`, or `seedance2.0-mini`. | | `resolution` | string | Yes | A resolution supported by the selected model. | | `prompt` | string | Conditional | Video prompt. Use a `type=text` item for `content[]` requests. | | `duration` | integer/string | Yes | Output duration from `4` to `15` seconds. | | `aspect_ratio` | string | No | Output aspect ratio; `ratio` is the compatibility alias. | | `content` | object[] | No | Multimodal text, image, video, and audio inputs with explicit roles. | | `operation` | string | Conditional | `reference_to_video`, `edit_video`, or `extend_video`. | | `generate_audio` | boolean | No | Whether to generate a video with audio. | | `return_last_frame` | boolean | No | Whether to return the generated video's last frame. | ## Request Example ```bash curl -X POST "https://api.uniall.ai/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0", "prompt": "A clean commercial product video with slow camera movement, soft reflections, and realistic lighting.", "resolution": "720p", "duration": 8, "aspect_ratio": "16:9", "generate_audio": false, "seed": 42, "watermark": false }' ``` ## Multi-Reference Example ```bash curl -X POST "https://api.uniall.ai/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0-fast", "resolution": "720p", "duration": 6, "aspect_ratio": "9:16", "operation": "reference_to_video", "content": [ { "type": "text", "text": "Create a fast fashion lookbook clip while preserving the product identity." }, { "type": "image_url", "image_url": {"url": "https://example.com/model.png"}, "role": "reference_image" }, { "type": "image_url", "image_url": {"url": "https://example.com/outfit.png"}, "role": "reference_image" } ], "generate_audio": true }' ``` ## Task Status And Result After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow. ## Common Errors - Using an old create task interface for a new integration. - Sending more than `9` reference images. - Sending more than `3` reference videos or reference videos whose total duration exceeds `15` seconds. - Using a `duration` outside `4` to `15`. - Passing incompatible operation hints together with the new input format. ## Related Pages - [Seedance 2.0 Series Guide](/models/video/seedance-2-0/series-guide) - [Seedance 2.0 Material Library](/models/video/seedance-2-0/material-library) - [Video Generation Overview](/models/video/overview) --- # Seedance 2.0 Material Library Locale: en URL: https://docs.uniall.ai/models/video/seedance-2-0/material-library Source: site-docs/models/video/seedance-2-0/material-library.md Description: Create a material, wait until available, use its returned URI in Seedance, then list or delete materials with your UniAI API key. Create reusable image, video or audio materials, then use the returned `uri` in a Seedance video request. All requests use `https://api.uniall.ai` and `Authorization: Bearer $UNIAI_API_KEY`. ## 1. Create a material `POST /v1/materials` requires an `Idempotency-Key` header and a JSON body: | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `url` | string | Yes | Public HTTP(S) media URL, up to 4,096 characters. | | `type` | string | Yes | `image`, `video` or `audio`; must match the media. | | `name` | string | No | Material name, up to 64 characters. | ```bash curl "https://api.uniall.ai/v1/materials" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: product-reference-001" \ -d '{ "url": "https://cdn.example.com/product.png", "type": "image", "name": "Product reference" }' ``` HTTP `202` response: ```json { "id": "mat_EXAMPLE", "object": "material", "name": "Product reference", "type": "image", "status": "processing", "uri": null, "preview_url": null, "created_at": "2026-10-29T10:00:00Z", "available_at": null, "expires_at": null } ``` - Use a key of 1–200 visible ASCII characters without spaces. Retrying the same request with the same key returns the same material; changed parameters return HTTP `409` (`material_idempotency_conflict`). After a timeout, retry with the original key. - Keep the URL publicly reachable during processing, without login, cookies or custom headers. The current website's Create Material form takes a source URL; this API accepts JSON URLs, not multipart files or Base64. For a local file, first make it available at a public HTTP(S) URL.

Images and videos of people use the same creation request. Follow any additional verification instructions returned by the API.

## 2. Wait until available Query the returned `id` every 3–5 seconds until `status` is `available`: ```bash curl "https://api.uniall.ai/v1/materials/mat_EXAMPLE" \ -H "Authorization: Bearer $UNIAI_API_KEY" ``` Example response; timestamps are illustrative: ```json { "id": "mat_EXAMPLE", "object": "material", "name": "Product reference", "type": "image", "status": "available", "uri": "asset://asset-EXAMPLE", "preview_url": "https://cdn.example.com/preview.png", "created_at": "2026-10-29T10:00:00Z", "available_at": "2026-10-29T10:01:00Z", "expires_at": "2026-10-30T12:00:00Z" } ``` Use the exact `uri` returned by the API. `mat_*` is the ID for querying and deleting a material; do not construct an `asset://` URI from it. The expiry time is `expires_at`; use the material before that time. | Status | Action | | --- | --- | | `creating`, `processing` | Continue querying. | | `available` | The returned `uri` is ready to use. | | `failed` | Read `error.code` and `error.message`. To create a new material, use a new idempotency key. | | `delete_pending`, `deleted` | Stop using the material. | ## 3. Generate a video with the URI Replace `asset://asset-EXAMPLE` below with the `uri` from your available image material: ```bash curl "https://api.uniall.ai/v1/videos" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0-fast", "resolution": "480p", "duration": 4, "aspect_ratio": "16:9", "generate_audio": false, "content": [ { "type": "text", "text": "Keep the product appearance consistent as the camera slowly moves around it." }, { "type": "image_url", "image_url": {"url": "asset://asset-EXAMPLE"}, "role": "reference_image" } ] }' ``` Put the URI in a structured media field such as `image_url.url`, not in the prompt. For video or audio materials, use the matching `video_url` or `audio_url` field. Use materials owned by the same UniAI user and still available and unexpired. Use the returned video task ID to [query the video and retrieve its result](/models/video/overview#video-task-lifecycle). ## List materials ```bash curl "https://api.uniall.ai/v1/materials?type=image&status=available&limit=20" \ -H "Authorization: Bearer $UNIAI_API_KEY" ``` The response contains `data`, `has_more` and `next_cursor`. Filters: `type`, `status`; `limit` is 1–100, default `50`. Pass a returned `next_cursor` unchanged as `after` for the next page. Expired and deleted materials are not listed. ## Delete a material ```bash curl -X DELETE "https://api.uniall.ai/v1/materials/mat_EXAMPLE" \ -H "Authorization: Bearer $UNIAI_API_KEY" ``` HTTP `200` with `status: "deleted"` means deletion is complete; HTTP `202` with `status: "delete_pending"` means it is still processing. Repeating DELETE is safe. A completed deletion removes the material from the list, and its detail endpoint returns `404 material_not_found`. ## Request errors | Error code | What to check | | --- | --- | | `invalid_idempotency_key` | Include a valid `Idempotency-Key` when creating a material. | | `invalid_material_request` | Check the URL, media type and name length. | | `material_idempotency_conflict` | Reuse the original request with that key, or use a new key for a different material. | | `material_not_found` | Check the ID and current user; the material may be deleted or expired. | | `material_not_available` | Wait for `available` and check `expires_at`. | | `material_not_managed` | Copy the returned `uri` from your material instead of constructing one. | See the [Seedance 2.0 Series Guide](/models/video/seedance-2-0/series-guide) for generation parameters. --- # Seedance 2.0 Series Guide Locale: en URL: https://docs.uniall.ai/models/video/seedance-2-0/series-guide Source: site-docs/models/video/seedance-2-0/series-guide.md Description: Use Seedance 2.0, Seedance 2.0 Fast, and Seedance 2.0 Mini through UniAll with multimodal input, video editing, extension, and task polling. Updated: 2026-07-29 Use the Seedance 2.0 series through UniAll. New integrations should use one of the three stable public model IDs and select the resolution and generation capability through request parameters. ## 1. Choose a Model | Public Model | Supported Resolutions | Recommended Use | | --- | --- | --- | | `seedance2.0` | `480p`, `720p`, `1080p`, `4k` | Full capabilities with quality prioritized | | `seedance2.0-fast` | `480p`, `720p` | Faster generation | | `seedance2.0-mini` | `480p`, `720p` | Lightweight and speed-focused tasks | All three models support: - text-to-video; - single-image-to-video; - first-and-last-frame generation; - multimodal image, video, and audio references; - video editing and extension; - generated audio, watermarks, and random seeds; - web search for text-only requests; - returning the generated video's last frame; - the `uri` returned for an available material. ## 2. Endpoints and Authentication Use the OpenAI-compatible video task endpoints: ```http POST /v1/videos GET /v1/videos/{task_id} GET /v1/videos/{task_id}/content ``` Request headers: ```http Authorization: Bearer sk-*** Content-Type: application/json ``` Use this value for `{BASE_URL}` in the examples: ```uri https://api.uniall.ai ``` The following compatibility endpoints remain available: ```http POST /v1/videos/generations GET /v1/videos/generations/{task_id} POST /v1/video/generations GET /v1/video/generations/{task_id} ``` New integrations should use `/v1/videos` consistently. ## 3. Common Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | One of the three public models, or a fixed-resolution model ID during the compatibility period. | | `prompt` | string | Conditional | Video prompt. When using `content[]`, include at least one `type=text` item instead. | | `resolution` | string | Yes for new public models | Output resolution from the selected model's supported values. | | `size` | string | No | Compatibility alias for `resolution`. | | `duration` | integer/string | Yes | Output duration from `4` to `15` seconds. The compatible value `auto` is accepted, but an explicit integer is recommended. | | `aspect_ratio` | string | No | `auto`, `21:9`, `16:9`, `4:3`, `3:2`, `2:3`, `1:1`, `3:4`, or `9:16`. | | `ratio` | string | No | Compatibility alias for `aspect_ratio`; `adaptive` is equivalent to `auto`. | | `content` | object[] | No | Recommended multimodal input format described in the next section. | | `operation` | string | Required for specific capabilities | `reference_to_video`, `edit_video`, or `extend_video`. | | `generate_audio` | boolean | No | Whether to generate a video with audio. | | `watermark` | boolean | No | Whether to add a watermark. | | `seed` | integer | No | Random seed. | | `return_last_frame` | boolean | No | Whether to return a last-frame URL in the completed result. | | `tools` | object[] | No | Currently supports only `[{"type":"web_search"}]`. | Compatibility rules: - `resolution` and `size` must match when both are present. - `aspect_ratio` and `ratio` must express the same ratio when both are present. - `ratio: "adaptive"` is equivalent to `aspect_ratio: "auto"`. - `operation`, `generate_audio`, `watermark`, `seed`, `return_last_frame`, and `tools` may also be placed inside `extra_body`. Do not repeat the same parameter at the top level and in `extra_body`. - `draft`, `frames`, `camera_fixed`, and `service_tier: "flex"` are outside the current public contract. ## 4. Multimodal `content[]` Format Use `content[]` for complex inputs: ```json { "content": [ { "type": "text", "text": "Video prompt" }, { "type": "image_url", "image_url": { "url": "https://example.com/image.png" }, "role": "reference_image" }, { "type": "video_url", "video_url": { "url": "https://example.com/video.mp4" }, "role": "reference_video" }, { "type": "audio_url", "audio_url": { "url": "https://example.com/audio.mp3" }, "role": "reference_audio" } ] } ``` Supported types and roles: | `type` | `role` | Meaning | | --- | --- | --- | | `text` | None | One or more prompt items. | | `image_url` | `image` | Input image for single-image-to-video. | | `image_url` | `reference_image` | Reference image. | | `image_url` | `first_frame` | First-frame image. | | `image_url` | `last_frame` | Last-frame image. | | `video_url` | `source_video` | Source video for editing or extension. | | `video_url` | `reference_video` | Reference video. | | `audio_url` | `reference_audio` | Reference audio. | Input constraints: - `content[]` must contain at least one non-empty text item. - Use no more than 9 images, 3 videos, and 3 audio files. - `first_frame` and `last_frame` must be provided together, with one image for each role. - First-and-last-frame mode cannot include videos, audio, or other images. - Do not mix the `image` and `reference_image` roles in one request. - Use no more than one `source_video`. - Reference audio requires at least one image or video. Audio-only and text-plus-audio requests are not accepted. - With multiple reference assets, use `@Image1`, `@Video1`, and `@Audio1` in the prompt to identify assets by order. Simple requests remain compatible with `image`, `images`, `last_image`, `video`, `videos`, and `audios`. Use `content[]` for new capabilities and multimodal combinations so each input role is explicit. ## 5. Request Examples ### 5.1 Text-to-Video ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0", "prompt": "A futuristic city street after rain, neon reflections, and a slow cinematic camera push forward.", "resolution": "1080p", "duration": 5, "ratio": "16:9", "generate_audio": true }' ``` ### 5.2 Single-Image-to-Video ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0-fast", "resolution": "720p", "duration": 6, "content": [ { "type": "text", "text": "The person turns naturally toward the camera, clothing moves gently in the wind, and identity remains consistent." }, { "type": "image_url", "image_url": { "url": "https://example.com/person.png" }, "role": "image" } ] }' ``` ### 5.3 First-and-Last-Frame Video ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0", "resolution": "720p", "duration": 6, "content": [ { "type": "text", "text": "Transition naturally from day to night with continuous motion and stable building structure." }, { "type": "image_url", "image_url": { "url": "https://example.com/first.png" }, "role": "first_frame" }, { "type": "image_url", "image_url": { "url": "https://example.com/last.png" }, "role": "last_frame" } ] }' ``` ### 5.4 Multimodal Reference-to-Video ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0-mini", "resolution": "720p", "duration": 8, "operation": "reference_to_video", "content": [ { "type": "text", "text": "Show the product from @Image1 with the camera motion from @Video1 and the rhythm from @Audio1." }, { "type": "image_url", "image_url": { "url": "https://example.com/product.png" }, "role": "reference_image" }, { "type": "video_url", "video_url": { "url": "https://example.com/motion.mp4" }, "role": "reference_video" }, { "type": "audio_url", "audio_url": { "url": "https://example.com/music.mp3" }, "role": "reference_audio" } ] }' ``` ### 5.5 Video Editing ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0", "resolution": "720p", "duration": 6, "operation": "edit_video", "content": [ { "type": "text", "text": "Replace the background with a neon street at night while preserving the person's motion and identity." }, { "type": "video_url", "video_url": { "url": "https://example.com/source.mp4" }, "role": "source_video" }, { "type": "image_url", "image_url": { "url": "https://example.com/style.png" }, "role": "reference_image" } ] }' ``` ### 5.6 Video Extension ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0-fast", "resolution": "720p", "duration": 5, "operation": "extend_video", "content": [ { "type": "text", "text": "Continue the camera motion as the person walks forward, preserving the lighting and scene." }, { "type": "video_url", "video_url": { "url": "https://example.com/source.mp4" }, "role": "source_video" } ] }' ``` ### 5.7 Text-Only Web Search Web search works only with text input. Do not include images, video, or audio in the same request. ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0-mini", "prompt": "Create a concise news video from today's publicly available technology news without showing brand logos.", "resolution": "720p", "duration": 5, "tools": [ { "type": "web_search" } ] }' ``` `web_search` allows the model to retrieve public information, but it does not guarantee that every generation will perform a search. ### 5.8 Return the Last Frame ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0", "prompt": "A paper boat slowly stops beside a stone bridge, with a stable final frame.", "resolution": "720p", "duration": 5, "return_last_frame": true }' ``` When the task completes, the last frame is returned as `result.last_frame_url` and is not mixed into the video `outputs` array. ### 5.9 Use a material URI Create and query reusable inputs through the [Seedance 2.0 Material Library](/models/video/seedance-2-0/material-library). When the material reaches `status=available`, replace a regular media URL with the returned `uri`: ```json { "model": "seedance2.0-fast", "resolution": "480p", "duration": 4, "content": [ { "type": "text", "text": "Keep the product appearance consistent as the camera slowly moves around it." }, { "type": "image_url", "image_url": { "url": "asset://asset-EXAMPLE" }, "role": "reference_image" } ] } ``` Copy `uri` from your material response; do not construct it from `mat_*`. Put it in the matching structured media field, not in the prompt, and use it before `expires_at`. ## 6. Task Status And Result A successful create request returns an asynchronous task: ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "seedance2.0", "status": "queued", "progress": 0, "created_at": 1784640000 } ``` After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow. When a Seedance request produces a last frame, the completed response may also include `result.last_frame_url`. ## 7. Fixed-Resolution Model Compatibility Existing clients may continue using fixed-resolution model IDs: | Model Series | Compatible Model IDs | | --- | --- | | Standard | `seedance2.0-480p`, `seedance2.0-720p`, `seedance2.0-1080p`, `seedance2.0-4k` | | Fast | `seedance2.0-fast-480p`, `seedance2.0-fast-720p` | | Mini | `seedance2.0-mini-480p`, `seedance2.0-mini-720p` | The following earlier IDs also remain compatible: - `seedance2.0-video-480p` - `seedance2.0-video-720p` - `seedance2.0-fast-video-480p` - `seedance2.0-fast-video-720p` Fixed-resolution model IDs determine the resolution and do not require an additional `resolution` field. They support the same parameters and capabilities as the corresponding public model. If `resolution` or `size` is still present, its value must match the resolution in the model ID. New projects should migrate to the three public model IDs so output resolution can be changed through a request parameter. ## 8. Common Errors | Scenario | Result | Fix | | --- | --- | --- | | New public model is missing `resolution`/`size` | HTTP `400` | Pass a supported resolution. | | `resolution` and `size` differ | HTTP `400` | Pass one field, or make both values identical. | | `aspect_ratio` and `ratio` conflict | HTTP `400` | Pass one field, or make both express the same ratio. | | Missing `duration` | HTTP `400` | Pass an integer from `4` to `15`. | | `content[]` has no text item | HTTP `400` | Add a non-empty `type=text` item. | | First and last frames are not paired | HTTP `400` | Pass both `first_frame` and `last_frame`. | | Audio-only or text-plus-audio input | HTTP `400` | Add at least one image or video. | | Web-search request contains media | HTTP `400` | Keep only text input in a search request. | | Too many images, videos, or audio files | HTTP `400` | Keep the counts at or below 9, 3, and 3. | | `draft`, `frames`, `camera_fixed`, or `service_tier=flex` is used | HTTP `400` | Remove the unsupported parameter. | For safety-review, media-format, or parameter errors, fix the input and create a new task instead of repeatedly submitting the same invalid request. ## 9. Related Pages - [Seedance 2.0](/models/video/seedance-2-0) - [Seedance 2.0 Material Library](/models/video/seedance-2-0/material-library) - [Video Generation Overview](/models/video/overview#video-task-lifecycle) --- # Seedance 2.5 Locale: en URL: https://docs.uniall.ai/models/video/seedance-2-5 Source: site-docs/models/video/seedance-2-5.md Description: Create 480p/720p/1080p Seedance 2.5 videos, audio-reference tasks, Draft previews and 1080p final videos, with editing, extension, and advanced controls. `{BASE_URL}` is `https://api.uniall.ai` throughout this page. Updated: 2026-10-19 ## Overview UniAll exposes Seedance 2.5 through one stable public model ID: `seedance2.5`. It supports text-to-video, first-frame and first-and-last-frame generation, multimodal references, video editing, video extension, reusable `asset://` media, optional web search, and 480p Draft previews followed by 1080p finalization. | Capability | Required input | Key rule | | --- | --- | --- | | Text-to-video | Prompt | Defaults to `720p` and automatic duration; explicit controls are optional. | | First-frame video | One first-frame image | Omit `aspect_ratio` or use `auto`. | | First-and-last-frame video | One first-frame and one last-frame image | Omit `aspect_ratio` or use `auto`. | | Multimodal reference | Images, videos, or audio | Text is optional; audio-only reference requests are allowed. | | Video editing | Prompt and one video | Set `omni_reference_task_type: "edit"` and use automatic duration. | | Video extension | Prompt and one video | Set `omni_reference_task_type: "extend"` explicitly. | | Draft to final video | Your completed Draft task ID | Create a `480p` preview, then finalize it at `1080p` within seven days using inherited settings. | ## Endpoints And Authentication | Action | Method | Path | | --- | --- | --- | | Create task | `POST` | `/v1/videos` | | Query task | `GET` | `/v1/videos/{task_id}` | Compatible creation and query aliases remain available to existing clients: ```http POST /v1/videos/generations POST /v1/video/generations GET /v1/videos/generations/{task_id} GET /v1/video/generations/{task_id} ``` New integrations should use `/v1/videos` and `/v1/videos/{task_id}`. ```http Authorization: Bearer Content-Type: application/json ``` ## Request Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | `seedance2.5`. | | `prompt` | string | Conditional | Text instruction. Required for text-only generation, editing, and extension. May be omitted with image, video, or audio references; omit when finalizing a Draft. | | `resolution` | string | No | `480p`, `720p`, or `1080p`. Ordinary requests default to `720p`; Draft defaults to and requires `480p`; Draft finalization defaults to and requires `1080p`. | | `duration` | integer/string | No | `"auto"`, `-1`, or an integer from `4` to `30`. Defaults to automatic duration. Editing requires automatic duration; omit when finalizing a Draft. | | `aspect_ratio` | string | No | `auto`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, or `9:16`. Frame inputs, editing, and extension require omission or `auto`. Omit when finalizing a Draft. | | `content` | object[] | No | Text, image, video, or audio parts. A text part uses `{"type":"text","text":"..."}`. See media roles below. | | `omni_reference_task_type` | string | No | `auto`, `reference`, `edit`, or `extend`. Set `edit` or `extend` explicitly for those workflows; omit when finalizing a Draft. | | `draft` | boolean | No | `true` creates a 480p preview; defaults to `false`. Do not set `true` when finalizing a Draft. | | `draft_task_id` | string | Conditional | The completed Draft's UniAI task ID, owned by the same user and created less than seven days ago. Use it to create the 1080p final video. | | `output_format` | string | No | `mp4` or `mov`; defaults to `mp4`. | | `generate_audio` | boolean | No | Whether to generate audio. Explicit `false` is preserved. Inherited during Draft finalization; omit it then. | | `watermark` | boolean | No | Whether to add a watermark. Explicit `false` is preserved. | | `return_last_frame` | boolean | No | Whether to return the generated last frame when available. Explicit `false` is preserved. | | `seed` | integer | No | `-1` to `2147483647`. Omit when finalizing a Draft. | | `priority` | integer | No | `0` to `9`; explicit `0` is preserved. | | `execution_expires_after` | integer | No | Execution expiry in seconds, from `3600` to `259200`. | | `safety_identifier` | string | No | `1` to `64` visible ASCII characters, without spaces or control characters. Use a non-sensitive identifier. | | `tools` | object[] | No | Web search uses `[{"type":"web_search"}]`. Omit when finalizing a Draft. | | `service_tier` | string | No | Only `default` is supported. `flex` is unavailable. | | `size` | string | No | Compatibility alias for `resolution`; if both are present, they must describe the same resolution. Prefer `resolution`. | | `seconds` | integer/string | No | Compatibility alias for `duration`. Prefer `duration`. Omit when finalizing a Draft. | | `ratio` | string | No | Compatibility alias for `aspect_ratio`; `adaptive` is normalized to `auto`. Omit when finalizing a Draft. | | `operation` | string | No | Compatible workflow selector: `reference_to_video`, `edit_video`, or `extend_video`. Prefer `omni_reference_task_type` in new examples and avoid conflicting selectors. Omit when finalizing a Draft. | Use top-level parameters. Compatible clients may use `extra_body` for controls; any field present both there and at the top level must have identical values. Explicit `false` and `0` are values, not omitted settings. 4K, `frames`, `camera_fixed`, and the `flex` service tier are unsupported. ## Minimal Text-To-Video Request ```bash curl -X POST "https://api.uniall.ai/v1/videos" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.5", "prompt": "A mechanical bird unfolds its wings on a wooden table." }' ``` Omitting `resolution` and `duration` uses `720p` and automatic duration for ordinary generation. To choose explicit output settings and advanced controls: ```json { "model": "seedance2.5", "prompt": "A mechanical bird unfolds its wings on a wooden table.", "resolution": "1080p", "duration": 4, "aspect_ratio": "16:9", "output_format": "mp4", "generate_audio": true, "watermark": false, "return_last_frame": true, "seed": 250628, "priority": 0, "execution_expires_after": 86400, "safety_identifier": "video-demo-01" } ``` ## Media Inputs Use `content[]` for new multimodal integrations. Each item carries one media type and an explicit role. | Item type | URL field | Supported roles | | --- | --- | --- | | `text` | `text` | Generation or editing instruction | | `image_url` | `image_url.url` | `first_frame`, `last_frame`, `reference_image` | | `video_url` | `video_url.url` | `reference_video` | | `audio_url` | `audio_url.url` | `reference_audio` | Media URLs may be public HTTP(S) URLs or valid `asset://` references. HTTP(S) media must remain reachable by the UniAll service without cookies or custom request headers. See the [Seedance Material Library](/models/video/seedance-2-0/material-library) for creating reusable `asset://` inputs. Wait for `available`, then copy the returned `uri`; do not construct it from `mat_*`. Use the material before `expires_at`. The image and audio compatibility fields `image`, `images`, `audios`, and `last_image` remain accepted. Do not send conflicting values through both `content[]` and compatibility fields. For video reference, use a `content[]` item with `type: "video_url"` and `role: "reference_video"`. Top-level `video` / `video_url` fields use editing or extension semantics and cannot directly replace a reference-video item. For editing or extension, explicitly set `omni_reference_task_type` to `edit` or `extend`. ### Media Limits - Up to `30` images. - Up to `10` videos. - Up to `10` audio files. - Up to `50` media items in total. - A multimodal request may omit text. - An audio-only reference request is valid. ## Operation Rules | Mode | `omni_reference_task_type` | `duration` | `aspect_ratio` | | --- | --- | --- | --- | | Text-to-video | Omit or `auto` | Omit, `"auto"`, `-1`, or integer `4..30` | Any supported value | | First-frame / first-and-last-frame video | Omit or `auto` | Omit, `"auto"`, `-1`, or integer `4..30` | Omit or `auto` | | Multimodal reference | `reference` when specified | Omit, `"auto"`, `-1`, or integer `4..30` | Follow the media mode; frame inputs require `auto` | | Video editing | `edit` required | Omit, `"auto"`, or `-1` | Omit or `auto` | | Video extension | `extend` required | Omit, `"auto"`, `-1`, or integer `4..30` | Omit or `auto` | | Draft finalization | Omit; inherited | Omit; inherited | Omit; inherited | Editing and extension require both a prompt and a source video. Do not rely on prompt keywords to select the workflow. Existing `operation` selectors remain compatible; new examples use `omni_reference_task_type`. ## Request Examples ### First-And-Last-Frame Video ```json { "model": "seedance2.5", "prompt": "Move naturally from the first composition to the last while preserving the subject.", "resolution": "720p", "duration": 10, "aspect_ratio": "auto", "content": [ { "type": "image_url", "image_url": { "url": "https://example.com/first.png" }, "role": "first_frame" }, { "type": "image_url", "image_url": { "url": "https://example.com/last.png" }, "role": "last_frame" } ] } ``` For a single first frame, send only the `first_frame` item. In both frame modes, fixed aspect ratios are rejected because the source frame determines the composition. ### Multimodal Reference ```json { "model": "seedance2.5", "omni_reference_task_type": "reference", "resolution": "720p", "duration": 12, "content": [ { "type": "image_url", "image_url": { "url": "https://example.com/product.png" }, "role": "reference_image" }, { "type": "video_url", "video_url": { "url": "https://example.com/motion.mp4" }, "role": "reference_video" }, { "type": "audio_url", "audio_url": { "url": "https://example.com/music.mp3" }, "role": "reference_audio" } ] } ``` ### Audio-Only Reference Without A Prompt ```json { "model": "seedance2.5", "resolution": "480p", "duration": 4, "content": [ { "type": "audio_url", "audio_url": { "url": "https://example.com/reference.wav" }, "role": "reference_audio" } ] } ``` ### Video Editing ```json { "model": "seedance2.5", "prompt": "Replace the sky and preserve the subject", "video": "https://example.com/source.mp4", "omni_reference_task_type": "edit", "resolution": "720p", "duration": "auto", "aspect_ratio": "auto" } ``` ### Video Extension ```json { "model": "seedance2.5", "prompt": "Continue the camera movement into the illuminated square.", "video": "asset://asset-EXAMPLE", "omni_reference_task_type": "extend", "resolution": "720p", "duration": 8, "aspect_ratio": "auto", "output_format": "mov" } ``` ### Web Search ```json { "model": "seedance2.5", "prompt": "Create a concise visual recap of the latest public spaceflight milestone.", "resolution": "720p", "duration": 8, "tools": [ { "type": "web_search" } ] } ``` Web search can be combined with media inputs. No other `tools` shape is accepted. ## Draft Preview To 1080p Final Video {/* #draft-to-final */} ### 1. Create A 480p Draft Set `draft: true`. Omitting `resolution` selects `480p`; any other explicit tier is rejected. A Draft may also use the media-reference inputs on this page. ```bash curl -X POST "https://api.uniall.ai/v1/videos" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.5", "prompt": "A mechanical bird unfolds its wings on a wooden table.", "draft": true, "duration": 4, "aspect_ratio": "16:9", "generate_audio": true, "seed": 250628 }' ``` ### 2. Save The UniAI Task ID And Wait For Completion Poll using the create response's `id` or `task_id` until `status` is `completed`. Replace the placeholder `task_YOUR_COMPLETED_DRAFT` below with the actual UniAI task ID you received. ```bash curl "https://api.uniall.ai/v1/videos/task_YOUR_COMPLETED_DRAFT" \ -H "Authorization: Bearer " ``` ### 3. Create The Final Video The parent must be a completed Seedance 2.5 Draft owned by the same UniAI user and created less than seven days ago. Pending, failed, expired, non-Draft, or another user's tasks cannot be reused. ```bash curl -X POST "https://api.uniall.ai/v1/videos" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.5", "draft_task_id": "task_YOUR_COMPLETED_DRAFT", "output_format": "mov", "watermark": false, "return_last_frame": true, "priority": 0 }' ``` Finalization defaults to `1080p`; you may explicitly set `resolution: "1080p"`. Other resolutions are rejected. A successful submission returns a new final-video task ID; poll it in the same way. The final video inherits the Draft's prompt, all media, duration, aspect ratio, `seed`, `generate_audio`, and task type. Omit these fields instead of repeating or overriding them; also omit `tools`, `operation`, and `omni_reference_task_type`. Do not repeat the original `content` or resend even `generate_audio: false`. You may separately set `output_format`, `watermark`, `return_last_frame`, `priority`, `execution_expires_after`, and `safety_identifier`. Do not set `draft: true`. A `content` array containing exactly one Draft reference is also accepted: ```json { "model": "seedance2.5", "content": [ { "type": "draft_task", "draft_task": { "id": "task_YOUR_COMPLETED_DRAFT" } } ] } ``` Its `id` must also be the public task ID returned by UniAI. Do not mix it with text or media parts. If `draft_task_id` is also present, both IDs must match. ## Create Response And Task Lifecycle ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "seedance2.5", "status": "queued", "progress": 0, "created_at": 1792368000 } ``` Store the public `id` or `task_id` and poll `GET /v1/videos/{task_id}` every 2 to 5 seconds until `status` is `completed` or `failed`. After completion, prefer the returned `video_url` to download the video; compatible responses may also expose it in `result.video_url` or `result.outputs`. Do not treat result URLs as permanent storage. Query an ordinary task in the same way: ```bash curl "https://api.uniall.ai/v1/videos/task_YOUR_VIDEO" \ -H "Authorization: Bearer " ``` If you requested `return_last_frame: true`, read the returned last-frame result when available. 1080p output uses HEVC/10bit and needs a compatible player. MP4 and MOV select the output container. Do not automatically retry Seedance 2.5 creation requests after failure, a client timeout, or an uncertain outcome. If you have a task ID, continue querying that task. If no ID was received, establish the original request's outcome first. This rule also applies to Draft finalization. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for public status fields, completed/failed responses, and error handling. This model's no-automatic-retry rule takes precedence over general retry guidance. ## Billing Notes Use each task's actual Token usage and final settlement record; pre-deduction is only an estimate. A Draft and its final video are separate billable tasks. The Draft does not offset the final video and is not counted again as an input video for finalization. Check the current UniAll price available to your account. ## Common Errors | Error | Cause | Fix | | --- | --- | --- | | Missing input | No prompt, media, or valid Draft reference | Supply the required input for the selected workflow. | | Invalid resolution | 4K or a mismatched Draft/final-video tier | Use `480p`/`720p`/`1080p` for ordinary tasks, only `480p` for Drafts, and only `1080p` for finalization. | | Conflicting aliases | `resolution` and `size` contain different values | Remove `size` or make the values identical. | | Invalid edit duration | Editing uses an integer duration | Omit `duration` or use `"auto"`/`-1`. | | Invalid aspect ratio | A frame, edit, or extension request uses a fixed ratio | Omit `aspect_ratio` or set it to `auto`. | | Media limit exceeded | Per-type or total media limits were exceeded | Reduce media to the documented limits. | | Media unavailable | A URL is private, expired, or unreachable from the public internet | Use a stable public URL or an available `asset://` material. | | Invalid tools | `tools` is not exactly the supported web-search structure | Send `[{"type":"web_search"}]` or omit `tools`. | | Unsupported field | `frames`, `camera_fixed`, or `service_tier: "flex"` was sent | Remove the unsupported field. | | Invalid Draft reference | Missing, incomplete, non-Draft, expired, or another user's task | Use your completed Draft's UniAI task ID within seven days of creation. | | Repeated inherited fields | Finalization resends the prompt, media, duration, ratio, seed, audio, or task type | Omit inherited fields; send the Draft ID and permitted output controls only. | | Invalid parameter type or range | String booleans or out-of-range priority, seed, or expiry | Use JSON booleans and the integer ranges in the parameter table. | ## Related Pages - [Video Generation Overview](/models/video/overview) - [Seedance 2.0](/models/video/seedance-2-0) - [Seedance Material Library](/models/video/seedance-2-0/material-library) - [Models](/models) --- # Seedance Global Locale: en URL: https://docs.uniall.ai/models/video/seedance-global Source: site-docs/models/video/seedance-global.md Description: Call the four overseas Seedance models with text, frame images, and multimodal references through the UniAll video API. Use the exact model IDs below with the UniAll video API. The `-global` suffix is part of each model name. These models support text-to-video, image-to-video, first-and-last-frame generation, and multimodal references. ## Supported Models | Model | Resolutions | Output duration | | --- | --- | --- | | `seedance2.0-global` | 480p, 720p, 1080p, 4k | 4–15 seconds | | `seedance2.0-fast-global` | 480p, 720p | 4–15 seconds | | `seedance2.0-mini-global` | 480p, 720p | 4–15 seconds | | `seedance2.5-global` | 480p, 720p, 1080p | 4–30 seconds | ## Endpoints And Authentication The API base URL is `https://api.uniall.ai`. ```http POST /v1/videos GET /v1/videos/{task_id} GET /v1/videos/{task_id}/content ``` Send your UniAll API key on every request: ```http Authorization: Bearer Content-Type: application/json ``` ## Request Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | One of the four exact model IDs above. | | `prompt` | string | Yes | Video instruction; alternatively, provide a type=text item in content. | | `resolution` | string | Yes | A resolution supported by the selected model. | | `duration` | integer | Yes | Output duration within the selected model's range. Automatic duration is not supported. | | `aspect_ratio` | string | No | auto, 21:9, 16:9, 4:3, 1:1, 3:4, or 9:16. | | `image` | string | No | First-frame image URL. Use it alone for image-to-video, or with last_image for first-and-last-frame generation. | | `last_image` | string | No | Last-frame image URL; requires a first-frame image. | | `images` | string[] | No | Reference image URLs for multimodal generation. | | `videos` | string[] | No | Reference video URLs for multimodal generation. | | `audios` | string[] | No | Reference audio URLs for multimodal generation. | | `content` | object[] | No | Structured text and reference-media parts; see the example below. | | `generate_audio` | boolean | No | Whether to generate audio; defaults to true. Explicit false is preserved. | | `seed` | integer | No | Random seed. | | `return_last_frame` | boolean | No | Only seedance2.5-global; requests the generated last frame when available. Omit this field for all 2.0 models. | | `output_format` | string | No | Only mp4; defaults to mp4. | Use top-level parameters. `size` is a compatibility alias for `resolution`; `ratio` is an alias for `aspect_ratio`, with `adaptive` equivalent to `auto`. If both an alias and its canonical field are present, their values must agree. These models do not support `watermark`, Draft generation, video editing or extension, web search, or the domestic models' advanced controls. Omit unsupported fields even when their value is `false`. ## Text-To-Video Example ```bash curl -X POST "https://api.uniall.ai/v1/videos" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0-global", "prompt": "A small sailboat crosses a calm lake at sunrise, with a slow cinematic camera movement.", "resolution": "720p", "duration": 5, "aspect_ratio": "16:9", "generate_audio": true }' ``` ## Image And Reference Inputs Use public HTTP(S) media URLs. For a first-and-last-frame request, send the following body to `POST /v1/videos`: ```json { "model": "seedance2.0-fast-global", "prompt": "Move smoothly from the first frame to the last frame while preserving the product appearance.", "resolution": "720p", "duration": 5, "image": "https://example.com/first.png", "last_image": "https://example.com/last.png", "generate_audio": false } ``` For multimodal references, use `images`, `videos`, and `audios`, or structured `content` with explicit media roles: ```json { "model": "seedance2.5-global", "resolution": "720p", "duration": 6, "content": [ { "type": "text", "text": "Animate the reference product using the camera movement in the reference video." }, { "type": "image_url", "image_url": { "url": "https://example.com/product.png" }, "role": "reference_image" }, { "type": "video_url", "video_url": { "url": "https://example.com/motion.mp4" }, "role": "reference_video" } ], "generate_audio": true } ``` | Model family | Maximum images | Maximum videos | Maximum audio clips | | --- | --- | --- | --- | | 2.0 Global, Fast Global, Mini Global | `9` | `3` | `3` | | 2.5 Global | `30` | `10` | `10` | Do not combine first/last-frame inputs with multimodal references in the same request. The 2.0 models require at least one image or video alongside audio references. ## Response And Task Result A successful creation returns a task object. Save its public task ID: ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "seedance2.0-global", "status": "queued", "progress": 0 } ``` Poll `GET /v1/videos/{task_id}` every 3 to 10 seconds until `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the complete status, result, and authenticated-download contract. Download the returned `video_url` promptly; result URLs may expire. Do not automatically repeat task creation after a timeout or uncertain outcome. Query the existing task ID when one was returned, and establish the original request's outcome before submitting again. ## Overseas Material Library The separate overseas material API is pending release. Use ordinary HTTP(S) references until it is enabled for your integration. The following describes its prepared calling contract. | Action | Method | Path | | --- | --- | --- | | Create material | `POST` | `/v1/materials/global` | | Query one material | `GET` | `/v1/materials/global/{id}` | | Delete material | `DELETE` | `/v1/materials/global/{id}` | Material calls do not take a model name. There is no material-list endpoint. To create material, provide a URL, type, optional name, and an `Idempotency-Key` header: ```bash curl -X POST "https://api.uniall.ai/v1/materials/global" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "Idempotency-Key: global-reference-001" \ -d '{ "url": "https://example.com/product.png", "type": "image", "name": "product-reference" }' ``` `type` accepts `image`, `video`, or `audio`. `name` retains up to 50 characters. The idempotency key must contain 1–191 visible ASCII characters without spaces. Keep the same key and body for retries; do not switch to a new key after an uncertain upload. Creation returns HTTP 202 with a `gmat-*` ID. Query its details until `status=available`, then use the returned `uri` in the corresponding media field: ```json { "id": "gmat-example", "object": "material", "type": "image", "name": "product-reference", "status": "available", "uri": "asset://gmat-example", "created_at": "2026-11-09T03:00:00+00:00" } ``` ```json { "model": "seedance2.0-global", "prompt": "Show the reference product turning slowly under soft studio lighting.", "resolution": "720p", "duration": 5, "image": "asset://gmat-example" } ``` Use the same UniAll user for material and video requests. Domestic material IDs cannot be used here. Reuse across the four overseas models remains subject to availability; cross-model reuse is not yet verified. No fixed material lifetime is promised. A material in use by a generation task cannot be deleted until that task finishes. ## Billing Notes Use the current pricing shown for the selected model in UniAll. Resolution, duration, and reference-video inputs can affect the charge; the final usage record is authoritative. ## Common Errors - Missing the `-global` suffix, or using the suffix in the wrong position. - Omitting `resolution` or `duration`, or sending `duration: "auto"`. - Selecting `1080p` or `4k` for Fast/Mini, or `4k` for 2.5 Global. - Sending unsupported fields such as `watermark` or `draft`. - Mixing first/last-frame inputs with multimodal references, or exceeding media-count limits. - Using domestic material IDs, another user's material, or material that is not yet available. --- # Sora 2 Locale: en URL: https://docs.uniall.ai/models/video/sora-2 Source: site-docs/models/video/sora-2.md Description: Generate videos with Sora 2 models through UniAll video APIs. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. Sora 2 supports prompt-based video generation with optional reference image input. The source scope includes the UniAll video generation endpoint and an OpenAI-native compatibility page. ## Supported Models | Model | Notes | | --- | --- | | `sora2-landscape-4s` | Landscape output, 4 seconds. | | `sora2-landscape-8s` | Landscape output, 8 seconds. | | `sora2-landscape-12s` | Landscape output, 12 seconds. | | `sora2-portrait-4s` | Portrait output, 4 seconds. | | `sora2-portrait-8s` | Portrait output, 8 seconds. | | `sora2-portrait-12s` | Portrait output, 12 seconds. | | `sora2-pro-720p` | Pro public model, 720p. | | `sora2-pro-1080p` | Pro public model, 1080p. | | `sora2-pro-true-1080p` | Pro true-1080p model when enabled. | ## Endpoint ```http POST /v1/video/generations GET /v1/videos/{task_id} ``` The source also includes a native OpenAI-format page for clients that need OpenAI-compatible request formatting. ## Authentication ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## Request Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | Sora 2 model ID. | | `prompt` | string | Yes | Video prompt. | | `image_url` | string | No | Public reference image URL. | | `aspect_ratio` | string | No | `16:9` or `9:16`. | | `duration` | integer/string | No | Source description lists `4`, `8`, `12`, `16`, or `20`. Model names may already encode duration. | ## Request Example ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "sora2-portrait-12s", "prompt": "A cat running through grass", "image_url": "https://example.com/image.jpg" }' ``` ## Submit Response ```json { "id": "gen_xxxxxxxxxxxx", "object": "video.generation.job", "model": "sora2", "status": "queued", "progress": 0, "created_at": 1770405483, "seconds": "12" } ``` ## Task Status And Result After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow. ## Billing Notes Sora 2 billing depends on model, duration, orientation, resolution, and whether a Pro model is selected. Use the current model pricing surface and task settlement record as the source of truth. ## Common Errors - Passing an unsupported Sora 2 model ID. - Sending a private or expired `image_url`. - Passing an `aspect_ratio` that conflicts with a landscape or portrait model name. - Treating a queued task as complete before polling finishes. - Mixing UniAll task format and native OpenAI format in one request. ## Related Pages - [Video Generation Overview](/models/video/overview) - [Wan 2.6 Video Generation](/models/video/wan-2-6) - [Models](/models) --- # Create Video Generation Task Locale: en URL: https://docs.uniall.ai/models/video/sora-2/create-task Source: site-docs/models/video/sora-2/create-task.md Description: Sora 2 create video generation task endpoint. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. ## Overview new sora2 Pro Public Models `sora2-pro-720p`,`sora2-pro-1080p`,`sora2-pro-true-1080p` ## Endpoint ```http POST /v1/video/generations ``` ## Header Parameters | Name | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `Authorization` | string | No | | Bearer {your_token} | ## Request Body Parameters | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | | `model` | string | Yes | Model name | Optional values: sora2-landscape-4s, sora2-landscape-8s, sora2-landscape-12s, sora2-portrait-4s, sora2-portrait-8s, sora2-portrait-12s, sora2-pro-720p, sora2-pro-1080p | | `prompt` | string | Yes | prompt | | | `image_url` | string | Yes | reference URL | must be public URLimage URL | | `aspect_ratio` | string | No | Ratio | "16:9", "9:16" | | `duration` | string | No | description | 4, 8, 12, 16, 20 | ## Request Examples ### Example 1 ```json {"model": "sora2-portrait-12s", "prompt": " ", "image_url": "https://example.com/image.jpg" // Optional values} ``` ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{"model": "sora2-portrait-12s", "prompt": " ", "image_url": "https://example.com/image.jpg" // Optional values}' ``` ## Response Fields | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | | `id` | string | Yes | task ID | | | `object` | string | Yes | Task type | | | `model` | string | Yes | Model name | | | `status` | string | Yes | Status | | | `progress` | string | Yes | | | | `created_at` | string | Yes | Created time | | | `seconds` | string | Yes | duration | | ## Response Examples ### Example 1 ```json { "id": "gen_xxxxxxxxxxxx", "object": "video.generation.job", "model": "sora2", "status": "queued", "progress": 0, "created_at": 1770405483, "seconds": "12" } ``` ## Task Status And Result After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow. --- # Native OpenAI Format Locale: en URL: https://docs.uniall.ai/models/video/sora-2/openai-format Source: site-docs/models/video/sora-2/openai-format.md Description: Sora 2 native OpenAI format endpoint. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. ## Endpoint ```http POST /v1/chat/completions ``` ## Header Parameters | Name | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `Authorization` | string | No | | Bearer {your_token} | ## Request Body Parameters | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | | `model` | string | Yes | Model name | Optional values: sora2-landscape-4s, sora2-landscape-8s, sora2-landscape-12s, sora2-portrait-4s, sora2-portrait-8s, sora2-portrait-12s | ## Request Examples ### Example 1 ```json // text-to-video {"model": "sora2-landscape-4s", "messages": [{"role": "user", "content": " "}], "stream": true} // image-to-video {"model": "sora2-landscape-4s", "messages": [{"role": "user", "content": [{"type": "text", "text": " "}, {"type": "image_url", "image_url": {"url": "https://example.com/portrait.jpg"}}]}], "stream": true} ``` ```bash curl -X POST "{BASE_URL}/v1/chat/completions" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '// text-to-video {"model": "sora2-landscape-4s", "messages": [{"role": "user", "content": " "}], "stream": true} // image-to-video {"model": "sora2-landscape-4s", "messages": [{"role": "user", "content": [{"type": "text", "text": " "}, {"type": "image_url", "image_url": {"url": "https://example.com/portrait.jpg"}}]}], "stream": true}' ``` ## Response Fields | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | ## Response Examples ### Example 1 ```json { "id": "xxxxxxxxxxxxxxxxxxxxx", "object": "chat.completion.chunk", "created": 1770408254, "model": "sora2", "choices": [ { "index": 0, "delta": { "content": "\n\n✅ **video generation completed! **\n\n**video URL**: https://xxxx.xxxx.cn/xxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.mp4\n**task **: 127 \n" }, "finish_reason": null } ] } ``` ### Example 2 ```json { "id": "chatcmpl-b5e9c8b352cc4dcc81815884ab943", "object": "chat.completion.chunk", "created": 1770408254, "model": "sora2", "choices": [ { "index": 0, "delta": { "content": "\n🖼️ processing. (50%)" }, "finish_reason": null } ] } ``` --- # Veo 3.1 Locale: en URL: https://docs.uniall.ai/models/video/veo-3-1 Source: site-docs/models/video/veo-3-1.md Description: Generate videos with Veo 3.1 models through UniAll video APIs. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. Veo 3.1 supports text-to-video, image-to-video, first-last-frame generation, multi-image reference generation, and video extension. Use the public model name to select the resolution and speed tier. ## Supported Models | Model | Tier | | --- | --- | | `veo3.1-video-720p` | Standard 720p. | | `veo3.1-video-1080p` | Standard 1080p. | | `veo3.1-video-4k` | Standard 4K. | | `veo3.1-fast-video-720p` | Fast 720p. | | `veo3.1-fast-video-1080p` | Fast 1080p. | | `veo3.1-fast-video-4k` | Fast 4K. | ## Endpoint ```http POST /v1/video/generations GET /v1/videos/{task_id} ``` ## Authentication ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## Request Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | Veo 3.1 public model ID. | | `prompt` | string | Strongly recommended | Main prompt. The schema is lenient, but production requests should include it. | | `image` | string | Conditional | Single source image URL for image-to-video. | | `images` | string[] | Conditional | `2` to `3` reference image URLs for multi-image reference generation. | | `last_image` | string | Conditional | Target last-frame image URL; use with `image`. | | `video` | string | Conditional | Source video URL for extension. | | `size` | string | Recommended | Resolution hint, aligned to the selected model tier. | | `aspect_ratio` | string | No | Text-to-video accepts `16:9` or `9:16`. Image-to-video and extension may not honor it. | | `duration` | integer | Conditional | Output seconds. Allowed values: `4`, `6`, or `8`. Not used for video extension. | | `extra_body.generate_audio` | boolean | No | Whether to generate audio; upstream usually defaults to `true`. | | `extra_body.negative_prompt` | string | No | Content to avoid. | | `extra_body.seed` | integer | No | Random seed for reproducibility. | ## Text-To-Video Example ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "veo3.1-video-1080p", "prompt": "A golden-hour street interview shot, slight handheld movement, natural city ambience, realistic human speech.", "size": "1080p", "aspect_ratio": "16:9", "duration": 8, "extra_body": { "generate_audio": true, "negative_prompt": "watermark, blur", "seed": 7 } }' ``` ## Image-To-Video Example ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "veo3.1-video-720p", "prompt": "A product slowly rotates on a clean studio desk with soft reflected light.", "image": "https://example.com/keyframe.png", "size": "720p", "aspect_ratio": "16:9", "duration": 6, "extra_body": { "generate_audio": false, "negative_prompt": "artifacts, camera shake" } }' ``` ## First-Last-Frame Example ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "veo3.1-fast-video-1080p", "prompt": "Transition naturally from the first frame to the last frame, preserving subject identity and camera continuity.", "image": "https://example.com/start-frame.png", "last_image": "https://example.com/end-frame.png", "size": "1080p", "aspect_ratio": "16:9", "duration": 6 }' ``` ## Task Status And Result After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow. ## Billing Notes Veo billing depends on model tier, speed tier, resolution, output duration, and audio generation. Use task settlement and current product pricing as the final source. ## Common Errors - Passing `duration` outside `4`, `6`, or `8`. - Mismatching `size` with the selected model tier. - Expecting `aspect_ratio` to be honored for image-to-video or extension requests. - Sending more than `3` reference images. - Passing `video` without clarifying the extension use case in the prompt or extra body. ## Related Pages - [Video Generation Overview](/models/video/overview) - [Kling Video Generation](/models/video/kling) - [Vidu Video Generation](/models/video/vidu) --- # Create Video Generation Task Locale: en URL: https://docs.uniall.ai/models/video/veo-3-1/create-task Source: site-docs/models/video/veo-3-1/create-task.md Description: Veo 3.1 create video generation task endpoint. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. ## Overview | Public model name | Currently supported video capabilities | |---|---| | `veo3.1-video-720p` | text-to-video, single-image-to-video, first-and-last-frame, multi-image-reference video generation, video extension | | `veo3.1-video-1080p` | text-to-video, single-image-to-video, first-and-last-frame, multi-image-reference video generation, video extension | | `veo3.1-video-4k` | text-to-video, single-image-to-video, first-and-last-frame, multi-image-reference video generation, video extension | | `veo3.1-fast-video-720p` | text-to-video, single-image-to-video, first-and-last-frame, video extension | | `veo3.1-fast-video-1080p` | text-to-video, single-image-to-video, first-and-last-frame, video extension | | `veo3.1-fast-video-4k` | text-to-video, single-image-to-video, first-and-last-frame, video extension | ## Endpoint ```http POST /v1/video/generations ``` ## Query Parameters | Name | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `Authorization` | string | No | | Bearer {your_token} | ## Request Body Parameters | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | | `model` | string | Yes | Public model name | | | `prompt` | string | Yes | prompt | Structure Yes Required, recommended to pass | | `image` | string | Yes | single source image URL | image-to-video | | `images` | string | Yes | multiple reference images URL list | 2 3 multi-image-reference video generation | | `last_image` | string | Yes | URL | first-and-last-frame, andimage use | | `video` | string | Yes | video UR | video extension | | `size` | string | Yes | resolution | and Public Models | | `aspect_ratio`| string | Yes | output aspect ratio | text-to-videoallowed values:`16:9`, `9:16`; image-to-video, video extension use, pass | | `duration`| string | Yes |, | allowed values:`4`, `6`, `8`; video extension use | | `extra_body` | object | Yes | Field | | ## Request Examples ### text-to-video ```json { "model": "veo3.1-video-1080p", "prompt": " camera, camera. ", "size": "1080p", "aspect_ratio": "16:9", "duration": 8, "extra_body": { "generate_audio": true, "negative_prompt": ", blur", "seed": 7 } } ``` ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{"model": "veo3.1-video-1080p", "prompt": " camera, camera. ", "size": "1080p", "aspect_ratio": "16:9", "duration": 8, "extra_body": {"generate_audio": true, "negative_prompt": ", blur", "seed": 7}}' ``` ### single-image-to-video ```json { "model": "veo3.1-video-720p", "prompt": ", and. ", "image": "https://example.com/keyframe.png", "size": "720p", "aspect_ratio": "16:9", "duration": 6, "extra_body": { "generate_audio": false, "negative_prompt": "artifacts, " } } ``` ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{"model": "veo3.1-video-720p", "prompt": ", and. ", "image": "https://example.com/keyframe.png", "size": "720p", "aspect_ratio": "16:9", "duration": 6, "extra_body": {"generate_audio": false, "negative_prompt": "artifacts, "}}' ``` ### first-and-last-frame ```json { "model": "veo3.1-fast-video-1080p", "prompt": ", subject, cameralanguage. ", "image": "https://example.com/start-frame.png", "last_image": "https://example.com/end-frame.png", "size": "1080p", "aspect_ratio": "16:9", "duration": 6, "extra_body": { "generate_audio": true } } ``` ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{"model": "veo3.1-fast-video-1080p", "prompt": ", subject, cameralanguage. ", "image": "https://example.com/start-frame.png", "last_image": "https://example.com/end-frame.png", "size": "1080p", "aspect_ratio": "16:9", "duration": 6, "extra_body": {"generate_audio": true}}' ``` ### reference video ```json { "model": "veo3.1-video-1080p", "prompt": ", and. ", "images": [ "https://example.com/ref-1.png", "https://example.com/ref-2.png" ], "size": "1080p", "aspect_ratio": "9:16", "duration": 6, "extra_body": { "generate_audio": true, "seed": 11 } } ``` ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{"model": "veo3.1-video-1080p", "prompt": ", and. ", "images": ["https://example.com/ref-1.png", "https://example.com/ref-2.png"], "size": "1080p", "aspect_ratio": "9:16", "duration": 6, "extra_body": {"generate_audio": true, "seed": 11}}' ``` ### video extension ```json { "model": "veo3.1-video-720p", "prompt": " video action, scenariostyle. ", "video": "https://example.com/source.mp4", "size": "720p", "duration": 6, "extra_body": { "negative_prompt": ", ", "seed": 9 } } ``` ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{"model": "veo3.1-video-720p", "prompt": " video action, scenariostyle. ", "video": "https://example.com/source.mp4", "size": "720p", "duration": 6, "extra_body": {"negative_prompt": ", ", "seed": 9}}' ``` ## Response Fields | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | ## Response Examples ### Example 1 ```json {} ``` ## Task Status And Result After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow. --- # Vidu Q3 Locale: en URL: https://docs.uniall.ai/models/video/vidu Source: site-docs/models/video/vidu.md Description: Create text, single-image, first-and-last-frame, and multi-reference videos with the Vidu Q3 series through UniAll. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. Updated: 2026-08-04 ## Overview Use the Vidu Q3 series through two stable public model IDs. Select the output resolution with the top-level `resolution` parameter instead of encoding it in the model name. | Public Model | Series | Text To Video | Single Image | First And Last Frame | Multiple References | | --- | --- | --- | --- | --- | --- | | `viduq3p` | Q3 Pro | Supported | Supported | Supported | 1 to 4 images | | `viduq3t` | Q3 Turbo | Supported | Supported | Supported | 1 to 4 images | Both models support `540p`, `720p`, and `1080p`. These are the only public Vidu Q3 model IDs. ## When To Use It Use Vidu Q3 when you need to: - create a video from a text prompt; - animate one publicly accessible image; - interpolate between a first frame and a last frame; - guide generation with 1 to 4 reference images. Clients only select a public model and request parameters. Do not send channel names, upstream model IDs, upstream task fields, or routing controls. ## Endpoints Use these endpoints for new integrations: | Purpose | Method | Path | | --- | --- | --- | | Create a video task | `POST` | `/v1/videos` | | Query a video task | `GET` | `/v1/videos/{task_id}` | | Download the video | `GET` | `/v1/videos/{task_id}/content` | The following compatibility endpoints remain available: | Purpose | Method | Path | | --- | --- | --- | | Create a video task | `POST` | `/v1/videos/generations` | | Query a video task | `GET` | `/v1/videos/generations/{task_id}` | | Create a video task | `POST` | `/v1/video/generations` | | Query a video task | `GET` | `/v1/video/generations/{task_id}` | Prefer `/v1/videos` for all new integrations. ## Authentication Every request requires a UniAll Bearer token: ```http Authorization: Bearer sk-*** ``` Task creation also requires: ```http Content-Type: application/json ``` ## Request Body Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | `viduq3p` or `viduq3t`. | | `prompt` | string | Yes | Video generation prompt. | | `duration` | integer | Yes | Output duration from `1` to `16` seconds. | | `aspect_ratio` | string | No | `16:9`, `9:16`, `3:4`, `4:3`, or `1:1`. | | `image` | string | Conditional | Public HTTP(S) URL for a single image or the first frame. | | `last_image` | string | Conditional | Public HTTP(S) URL for the last frame; requires `image`. | | `reference_image_urls` | string[] | Conditional | 1 to 4 public HTTP(S) image URLs for reference generation. | | `resolution` | string | Yes | `540p`, `720p`, or `1080p`. | | `audio` | boolean | No | Whether to generate audio. | | `bgm` | boolean | No | Background music control for text-to-video generation. | | `seed` | integer | No | Random seed. | Choose input fields according to the generation mode: | Mode | Input Fields | | --- | --- | | Text to video | `prompt` | | Single image | `prompt` + `image` | | First and last frame | `prompt` + `image` + `last_image` | | Multiple references | `prompt` + `reference_image_urls` | Follow these validation rules: - Pass top-level `resolution` on every request. - Do not combine `image` with `reference_image_urls`. - Do not pass `last_image` without `image`. - Do not use `images` or `image_urls` for first-and-last-frame or reference generation. - Pass `resolution`, `audio`, `bgm`, and `seed` at the top level, not inside `extra_body`. - `size` is not an alias for `resolution`. ## Request Examples ### Text To Video ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "viduq3p", "prompt": "A cinematic aerial shot over a futuristic coastal city at sunrise, soft light, slow camera push-in.", "duration": 5, "aspect_ratio": "16:9", "resolution": "720p", "audio": false, "bgm": false, "seed": 42 }' ``` ### Single Image To Video ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "viduq3t", "prompt": "The person slowly raises their head and looks at the camera while the camera gently moves forward.", "image": "https://example.com/source.png", "duration": 5, "aspect_ratio": "9:16", "resolution": "540p", "audio": false, "seed": 42 }' ``` ### First And Last Frame ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "viduq3p", "prompt": "The person turns naturally from a front view to a side view while identity and motion remain consistent.", "image": "https://example.com/head.png", "last_image": "https://example.com/tail.png", "duration": 6, "aspect_ratio": "16:9", "resolution": "720p", "audio": false, "seed": 42 }' ``` ### Multiple Reference Images ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "viduq3p", "prompt": "A @Image1 walking through a beach in the visual style of @Image2", "reference_image_urls": [ "https://example.com/ref-1.png", "https://example.com/ref-2.png" ], "duration": 5, "aspect_ratio": "16:9", "resolution": "1080p", "audio": false, "seed": 42 }' ``` Both public models accept `reference_image_urls`. Reference prompts can use `@Image1`, `@Image2`, and subsequent markers in array order. ## Response Examples ### Task Created Save `id` or the compatible `task_id` value for later queries: ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "viduq3p", "status": "queued", "progress": 0, "created_at": 1785772800 } ``` Public responses do not include channel identifiers, upstream task IDs, credentials, or raw upstream payloads. ## Task Status And Result After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow. ## Billing Notes Billing depends on the public model, requested `resolution`, and actual output duration. The model ID does not carry a resolution or time-based billing tier. The current Baidu VOD/BV channel reference for normal-time text-to-video, single-image-to-video, and first-and-last-frame requests is: | Public Model | `540p` | `720p` | `1080p` | | --- | ---: | ---: | ---: | | `viduq3p` (Q3 Pro) | CNY 0.28125/second | CNY 0.625/second | CNY 0.75/second | | `viduq3t` (Q3 Turbo) | CNY 0.21875/second | CNY 0.375/second | CNY 0.40625/second | Total channel consumption is the rate multiplied by the actual output duration. Reference-image requests may use a different eligible route. Treat these values as the current channel reference, and use the UniAll model page and consumption log as the source of the final user-facing price and settlement. ## Common Errors Requests are rejected before task creation when they: - use a model ID other than `viduq3p` or `viduq3t`; - omit `resolution` or pass a value other than `540p`, `720p`, or `1080p`; - use `size` instead of `resolution`; - omit `duration` or pass a value outside `1` to `16`; - use an unsupported aspect ratio such as `21:9` or `1920x1080`; - pass an empty `reference_image_urls` array or more than 4 references; - combine `image` with `reference_image_urls`, or pass `last_image` alone; - use an image URL that the service cannot access publicly; - place supported top-level controls inside `extra_body`. ## Related Pages - [Video Generation Overview](/models/video/overview) - [Models](/models) --- # Wan 2.6 Locale: en URL: https://docs.uniall.ai/models/video/wan-2-6 Source: site-docs/models/video/wan-2-6.md Description: Generate videos with Wan 2.6 models through UniAll video APIs. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. Wan 2.6 covers text-to-video, image-to-video, and reference-to-video model families. The source scope also includes a duration reference table for the Wan 2.6 public models. ## Supported Models | Model | Type | Duration rules | | --- | --- | --- | | `wan2.6-video-720p` | Text-to-video / image-to-video | Required; `5`, `10`, or `15`. | | `wan2.6-video-1080p` | Text-to-video / image-to-video | Required; `5`, `10`, or `15`. | | `wan2.6-i2v-flash-720p-audio` | Image-to-video with audio | Required; any integer from `5` to `15`. | | `wan2.6-i2v-flash-720p-silent` | Image-to-video silent | Required; any integer from `5` to `15`. | | `wan2.6-i2v-flash-1080p-audio` | Image-to-video with audio | Required; any integer from `5` to `15`. | | `wan2.6-i2v-flash-1080p-silent` | Image-to-video silent | Required; any integer from `5` to `15`. | | `wan2.6-r2v-720p` | Reference-to-video | Required; see account model configuration. | | `wan2.6-r2v-1080p` | Reference-to-video | Required; see account model configuration. | | `wan2.6-r2v-flash-720p-audio` | Reference-to-video with audio | Required; see account model configuration. | | `wan2.6-r2v-flash-720p-silent` | Reference-to-video silent | Required; see account model configuration. | | `wan2.6-r2v-flash-1080p-audio` | Reference-to-video with audio | Required; see account model configuration. | | `wan2.6-r2v-flash-1080p-silent` | Reference-to-video silent | Required; see account model configuration. | ## Endpoint ```http POST /v1/video/generations GET /v1/videos/{task_id} ``` ## Authentication ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## Request Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `model` | string | Yes | Wan 2.6 model ID. | | `prompt` | string | Yes | Prompt. | | `image` | string | Conditional | Reference image for image-to-video. | | `images` | string[] | Conditional | Reference images for R2V models. | | `videos` | string[] | Conditional | Reference videos for R2V models. | | `duration` | integer | Yes | See the supported model table. | | `size` | string | No | Output size. Text-to-video can use this to choose landscape or portrait. Image-to-video follows the reference image orientation. | | `extra_body.negative_prompt` | string | No | Content to avoid. | | `extra_body.shot_type` | string | No | `single` or `multi`. | | `extra_body.seed` | integer | No | `-1` for random; fixed value for reproducibility. | | `extra_body.audio` | string | No | Public audio URL. | | `extra_body.enable_prompt_expansion` | boolean | No | Prompt expansion switch for R2V models. | Common `size` values include `1280*720`, `720*1280`, `1920*1080`, and `1080*1920`. ## Text-To-Video Example ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "wan2.6-video-1080p", "prompt": "sunrise", "duration": 5, "size": "1080*1920", "extra_body": { "negative_prompt": "blur, watermark", "shot_type": "multi", "seed": -1 } }' ``` ## Reference Video Example ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "wan2.6-r2v-flash-720p-audio", "prompt": "Keep the same subject identity and cinematic style, generate a faster-paced new shot.", "videos": [ "https://example.com/reference-shot-1.mp4" ], "size": "1280*720", "duration": 5, "extra_body": { "negative_prompt": "watermark, blur, flicker", "audio": "https://example.com/guide-audio.mp3", "shot_type": "single", "enable_prompt_expansion": false, "seed": -1 } }' ``` ## Multi-Image Reference Example ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "wan2.6-r2v-flash-1080p-silent", "prompt": "Keep the same product identity and style, generate a clean marketing video.", "images": [ "https://example.com/ref-1.png", "https://example.com/ref-2.png" ], "size": "1920*1080", "duration": 10, "extra_body": { "negative_prompt": "watermark, blur", "shot_type": "multi", "enable_prompt_expansion": true, "seed": 42 } }' ``` ## Task Status And Result After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow. ## Billing Notes Wan 2.6 billing depends on model family, output resolution, duration, audio mode, and whether the task is text/image/video reference generation. Use settlement records for final accounting. ## Common Errors - Using a duration value outside the selected model's allowed range. - Expecting `size` to control portrait or landscape for image-to-video; image orientation follows the reference image. - Passing private media URLs. - Using R2V fields with a non-R2V model. - Using `audio` with a silent model. ## Related Pages - [Video Generation Overview](/models/video/overview) - [Vidu Video Generation](/models/video/vidu) - [Sora 2 Video Generation](/models/video/sora-2) --- # Create Video Generation Task Locale: en URL: https://docs.uniall.ai/models/video/wan-2-6/create-task Source: site-docs/models/video/wan-2-6/create-task.md Description: Wan 2.6 create video generation task endpoint. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. ## Endpoint ```http POST /v1/video/generations ``` ## Header Parameters | Name | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `Authorization` | string | No | | Bearer {your_token} | ## Request Body Parameters | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | | `model` | string | Yes | Model name | "wan2.6-video-720p", "wan2.6-video-1080p" | | `prompt` | string | Yes | prompt | | | `image` | string | Yes | reference | | | `duration` | string | Yes | duration | | | `size` | string | Yes | videosize | "1280*720", "720*1280", "1920*1080", "1080*1920", Note: text-to-video Optional valuessizecontrolLandscape Portrait, image-to-video sizeParameters, pass in, Yes videoLandscape Portrait reference | | `extra_body` | object | Yes | | | ## Request Examples ### Example 1 ```json { "model": "wan2.6-video-1080p", "prompt": " ", "duration": 5, "size": "1080*1920", "extra_body": { "negative_prompt": "do not blur, do not ", "shot_type": "multi", "seed": -1 } } ``` ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{"model": "wan2.6-video-1080p", "prompt": " ", "duration": 5, "size": "1080*1920", "extra_body": {"negative_prompt": "do not blur, do not ", "shot_type": "multi", "seed": -1}}' ``` ## Response Fields | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | ## Response Examples ### Success ```json { "id": "task_xxxxxxxxxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "wan2.6-video-1080p", "status": "in_progress", "progress": 5, "created_at": 1773984104 } ``` ## Task Status And Result After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow. --- # Wan Model Duration Reference Locale: en URL: https://docs.uniall.ai/models/video/wan-2-6/duration-table Source: site-docs/models/video/wan-2-6/duration-table.md Description: Wan model duration source reference. ## WAN 2.6 | Public Models | Type | duration | allowed values | |---|---|---|---| | `wan2.6-video-720p`| text-to-video / image-to-video | Required |`5`, `10`, `15` | | `wan2.6-video-1080p`| text-to-video / image-to-video | Required |`5`, `10`, `15` | | `wan2.6-i2v-flash-720p-audio`| image-to-video audio | Required |`5` `15` any integer | | `wan2.6-i2v-flash-720p-silent`| image-to-video silent | Required |`5` `15` any integer | | `wan2.6-i2v-flash-1080p-audio`| image-to-video audio | Required |`5` `15` any integer | | `wan2.6-i2v-flash-1080p-silent`| image-to-video silent | Required |`5` `15` any integer | | `wan2.6-r2v-720p`| reference video | Required |`5`, `10` | | `wan2.6-r2v-1080p`| reference video | Required |`5`, `10` | | `wan2.6-r2v-flash-720p-audio`| reference video audio | Required |`5`, `10` | | `wan2.6-r2v-flash-720p-silent`| reference video silent | Required |`5`, `10` | | `wan2.6-r2v-flash-1080p-audio`| reference video audio | Required |`5`, `10` | | `wan2.6-r2v-flash-1080p-silent`| reference video silent | Required |`5`, `10` | ## - `wan2.6-video-*`: `5 / 10 / 15` - `wan2.6-i2v-flash-*`: `5~15` any integer - `wan2.6-r2v-*`: `5 / 10` - `wan2.6-r2v-flash-*`: `5 / 10` --- # Wan 2.6 R2V Create Video Task Locale: en URL: https://docs.uniall.ai/models/video/wan-2-6/r2v-create-task Source: site-docs/models/video/wan-2-6/r2v-create-task.md Description: Wan 2.6 R2V create video task endpoint. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. ## Endpoint ```http POST /v1/video/generations ``` ## Request Body Parameters | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | | `model` | string | No | Example field | Appears in a request example; no separate field description is provided. | | `prompt` | string | No | Example field | Appears in a request example; no separate field description is provided. | | `videos` | array | No | Example field | Appears in a request example; no separate field description is provided. | | `size` | string | No | Example field | Appears in a request example; no separate field description is provided. | | `duration` | number | No | Example field | Appears in a request example; no separate field description is provided. | | `extra_body` | object | No | Example field | Appears in a request example; no separate field description is provided. | | `images` | array | No | Example field | Appears in a request example; no separate field description is provided. | ## Request Examples ### Example 1: videoreference ```json { "model": "wan2.6-r2v-flash-720p-audio", "prompt": " subject and style, generate a newcamera. ", "videos": [ "https://example.com/reference-shot-1.mp4" ], "size": "1280*720", "duration": 5, "extra_body": { "negative_prompt": "watermark, blur, flicker", "audio": "https://example.com/guide-audio.mp3", "shot_type": "single", "enable_prompt_expansion": false, "seed": -1 } } ``` ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{"model": "wan2.6-r2v-flash-720p-audio", "prompt": " subject and style, generate a newcamera. ", "videos": ["https://example.com/reference-shot-1.mp4"], "size": "1280*720", "duration": 5, "extra_body": {"negative_prompt": "watermark, blur, flicker", "audio": "https://example.com/guide-audio.mp3", "shot_type": "single", "enable_prompt_expansion": false, "seed": -1}}' ``` ### Example 2: reference ```json { "model": "wan2.6-r2v-flash-1080p-silent", "prompt": " andstyle, generate a video. ", "images": [ "https://example.com/ref-1.png", "https://example.com/ref-2.png" ], "size": "1920*1080", "duration": 10, "extra_body": { "negative_prompt": "watermark, blur", "shot_type": "multi", "enable_prompt_expansion": true, "seed": 42 } } ``` ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{"model": "wan2.6-r2v-flash-1080p-silent", "prompt": " andstyle, generate a video. ", "images": ["https://example.com/ref-1.png", "https://example.com/ref-2.png"], "size": "1920*1080", "duration": 10, "extra_body": {"negative_prompt": "watermark, blur", "shot_type": "multi", "enable_prompt_expansion": true, "seed": 42}}' ``` ## Response Fields | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | ## Response Examples ### Example 1 ```json {} ``` ## Task Status And Result After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow. --- # Wan 2.2 Animate Video Editing Locale: en URL: https://docs.uniall.ai/models/video/wan-2-6/wan-2-2-animate Source: site-docs/models/video/wan-2-6/wan-2-2-animate.md Description: Wan 2.2 Animate video editing endpoint. In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`. ## Overview supports mode: - `animate` - video action, Input image orsubject - `replace` - Input image orsubject, video subject: - `animate` "action / action " - `replace` "video / " ## Endpoint ```http POST /v1/video/generations ``` ## Header Parameters | Name | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `Authorization` | string | No | | Bearer {your_token} | ## Request Body Parameters | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | | `model`| string | Yes | Public model name | use `wan2.2-animate-480p` or `wan2.2-animate-720p` | | `prompt` | string | Yes | prompt | Optional values, recommended style, scenario, camera | | `image` | string | Yes | reference URL | Recommended \| image \| can onlyone | | `video` | string | Yes | video URL | Recommended \| actionor video \| can onlya | | `duration` | string | Yes |, | Required | | `mode`| string | Yes | mode | allowed values:`animate`, `replace` (Field, not inextra_body pass) | | `seed` | string | Yes | random seed | random seed, (Field, not inextra_body pass) | | `extra_body` | object | Yes | | | ## Request Examples ### Example ```json { "model": "string", "prompt": "string", "image": "string", "video": "string", "duration": "string", "mode": "string", "seed": "string", "extra_body": { "mode": "string", "seed": "string" } } ``` ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{"model": "string", "prompt": "string", "image": "string", "video": "string", "duration": "string", "mode": "string", "seed": "string", "extra_body": {"mode": "string", "seed": "string"}}' ``` ## Response Fields | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | ## Response Examples ### Example 1 ```json {} ``` ## Task Status And Result After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow. --- # 文档概览 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/overview.md Description: UniAll 开发者文档范围、API 风格和选定模型文档结构。 UniAll Docs 是从当前 Apifox 文档范围中选定 API 和模型页面后整理出的开发者参考。来源菜单只作为内容清单使用，新站点会统一名称、路由、示例和页面结构，让文档呈现为一个完整的 UniAll 产品文档体系。 当前公开文档会保持收敛，只覆盖已确认范围内的余额、模型列表、图像、视频、语音音乐和数字人页面。独立的快速开始、认证说明、完整计费政策、错误码全集、更新日志和自动生成 API Reference 不属于本阶段。 ## 当前包含的文档 | 范围 | 当前页面 | 主要用途 | | --- | --- | --- | | 账户 | [查询余额](/zh-CN/balance) | 在提交任务前确认账户和 API Key 额度。 | | 模型索引 | [模型列表](/zh-CN/models) | 按能力组织模型文档，并说明模型列表接口。 | | 图像生成 | [通用异步图像生成](/zh-CN/models/image/async-image-generation)、Seedream、GPT-Image-2、Nano 系列 | 按模型页面选择异步任务或同步图像接口。 | | 视频生成 | Happy-Horse、Seedance 2.0、[Grok Imagine](/zh-CN/models/video/grok-imagine)、Veo 3.1、Vidu、Kling、Wan 2.6、Sora 2 | 提交视频任务、查询状态并获取完成后的视频。 | | 语音与音乐 | 音乐生成、语音合成 | 使用模型专属字段生成音乐或语音。 | | 数字人 | 数字人口播 | 生成数字人口播视频。 | ## API 风格 大多数模型页面使用任务流程： 1. 使用 `Authorization: Bearer sk-***` 提交任务。 2. 保存返回的任务 ID。 3. 每 2 到 5 秒轮询任务状态。 4. 当任务进入 `succeeded`、`completed` 或 `failed` 等终态时停止轮询。 5. 使用返回的结果 URL 或内容接口下载最终资产。 余额和模型列表属于同步 API 概念页，会立即返回结果，不需要轮询。 ## 通用约定 | 约定 | 规则 | | --- | --- | | Base URL | `https://api.uniall.ai`；示例中的 `{BASE_URL}` 均表示该地址。 | | 认证 | 除非页面说明兼容格式专属 Header，否则使用 `Authorization: Bearer sk-***`。 | | 请求示例 | 优先使用 `curl`。 | | 模型 ID | JSON 中使用精确模型 ID，例如 `grok-imagine` 和 `gpt-image-2`。 | | 结果 URL | 返回的 URL 视为生成资产，除非产品协议另有说明，不应默认永久有效。 | | 计费 | 页面内说明影响费用的维度，精确价格以当前产品价格页为准。 | ## 语言和 AI 可读文档 英文是默认语言，路径为 `/`。中文路径为 `/zh-CN/`。代码示例、JSON key、接口路径和模型 ID 在两种语言中保持一致。 站点同时发布 AI 可读索引： - [`/llms.txt`](/llms.txt) - [`/llms-full.txt`](/llms-full.txt) 当 agent 或外部 AI 工具需要快速理解当前文档范围时，可以使用这两个文件。 ## 相关页面 - [查询余额](/zh-CN/balance) - [模型列表](/zh-CN/models) - [通用异步图像生成](/zh-CN/models/image/async-image-generation) - [Grok Imagine 视频生成](/zh-CN/models/video/grok-imagine) --- # 查询余额 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/balance Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/balance.md Description: 查询账户余额和额度使用情况。 ## 1. 接口说明 该接口用于通过普通 API Key 查询： - 当前 API Key 所属的用户 ID - 用户账户余额 - 用户余额按站点配置换算后的展示金额 - 当前这把 API Key 的额度信息 该接口使用普通 `sk-...` API Key 调用，不需要用户登录态。 --- ## 2. 请求信息 | 项目 | 内容 | | --- | --- | | 请求方法 | `GET` | | 请求路径 | `/api/usage/balance` | | 鉴权方式 | `Authorization: Bearer sk-xxx` | | Content-Type | 无请求体，可不传 | --- ## 3. 请求示例 ```bash curl -X GET "https://api.aijisu.cn/api/usage/balance" \ -H "Authorization: Bearer sk-your-api-key" ``` --- ## 4. 成功响应示例 ```json { "success": true, "message": "", "data": { "object": "api_key_balance", "user_id": 1, "balance": { "quota": 1000000, "amount": 14.6, "display_amount": "¥14.60", "quota_per_unit": 500000, "quota_display_type": "CNY", "currency_symbol": "¥", "exchange_rate": 7.3 }, "token": { "id": 12, "name": "my-key", "remain_quota": 100000, "used_quota": 5000, "total_quota": 105000, "unlimited_quota": false, "expired_time": -1, "status": 1, "model_limits_enabled": false, "model_limits": {} } } } ``` --- ## 5. 响应参数说明 ### 5.1 顶层参数 | 参数 | 类型 | 说明 | | --- | --- | --- | | `success` | boolean | 请求是否成功 | | `message` | string | 响应消息，成功时通常为空字符串 | | `data` | object | 响应数据 | ### 5.2 `data` 参数 | 参数 | 类型 | 说明 | | --- | --- | --- | | `data.object` | string | 对象类型，固定为 `api_key_balance` | | `data.user_id` | number | 当前 API Key 所属的用户 ID | | `data.balance` | object | 用户账户余额信息 | | `data.token` | object | 当前 API Key 的额度信息 | ### 5.3 `data.balance` 参数 | 参数 | 类型 | 说明 | | --- | --- | --- | | `data.balance.quota` | number | 用户账户原始额度，系统内部额度单位 | | `data.balance.amount` | number | 按站点展示配置换算后的余额金额 | | `data.balance.display_amount` | string | 格式化后的展示金额，通常包含货币符号 | | `data.balance.quota_per_unit` | number | 额度换算单位，例如 `500000` 表示 `500000 quota = 1 USD` | | `data.balance.quota_display_type` | string | 余额展示类型，可能值：`USD`、`CNY`、`CUSTOM`、`TOKENS` | | `data.balance.currency_symbol` | string | 当前展示货币符号，例如 `$`、`¥`；当展示类型为 `TOKENS` 时为空字符串 | | `data.balance.exchange_rate` | number | 当前展示币种使用的汇率；`USD` 通常为 `1`，`CNY` 为人民币汇率，`CUSTOM` 为自定义汇率 | ### 5.4 `data.token` 参数 | 参数 | 类型 | 说明 | | --- | --- | --- | | `data.token.id` | number | 当前 API Key 的 ID | | `data.token.name` | string | 当前 API Key 的名称 | | `data.token.remain_quota` | number | 当前 API Key 剩余额度 | | `data.token.used_quota` | number | 当前 API Key 已使用额度 | | `data.token.total_quota` | number | 当前 API Key 总额度，计算方式为 `remain_quota + used_quota` | | `data.token.unlimited_quota` | boolean | 当前 API Key 是否为无限额度 | | `data.token.expired_time` | number | 当前 API Key 过期时间戳；`-1` 表示不过期 | | `data.token.status` | number | 当前 API Key 状态；`1` 表示启用 | | `data.token.model_limits_enabled` | boolean | 当前 API Key 是否启用模型限制 | | `data.token.model_limits` | object | 当前 API Key 的模型限制配置；未限制时通常为空对象 `{}` | --- --- ## 6. 错误响应 ### 6.1 未传 API Key HTTP 状态码：`401` ```json { "success": false, "message": "Token not provided" } ``` ### 6.2 API Key 不存在或无效 HTTP 状态码：`401` ```json { "success": false, "message": "Invalid token" } ``` ### 6.3 API Key 已禁用 HTTP 状态码：`403` ```json { "success": false, "message": "Token invalid" } ``` --- ## 7. 调用注意事项 - 必须使用 `Authorization: Bearer sk-xxx` 传入 API Key。 - 返回的是 API Key 所属用户的账户余额，不是上游渠道余额。 - 接口不会返回原始 API Key 字符串。 - 已禁用的 API Key 不能查询余额。 - API Key 已过期或额度耗尽时，仍可查询余额，只要 Key 未禁用且用户未被封禁。 - `amount` 和 `display_amount` 会根据站点当前余额展示配置动态变化。 --- # 模型列表 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/index.md Description: 按能力分类的 UniAll 模型文档入口，并说明模型列表接口。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 模型列表是当前 UniAll 选定模型文档的统一入口。这里按能力组织页面，而不是沿用原始 Apifox 菜单顺序。 当客户端需要在运行时发现当前 API Key 可用的模型时，可以调用模型列表接口。 ## 能力分类 | 分类 | 页面 | 常用接口 | | --- | --- | --- | | 图像生成 | 通用异步图像生成、Seedream、Seedream 5.0 Pro、GPT-Image-2、GPT-Image-2.5、GPT-Image-2.6、Qwen Image、Nano 系列（含 Nano Banana 2.1）、Kling | `POST /v1/images/tasks`、`POST /v1/images/generations` 或 `POST /v1/images/edits` | | 视频生成 | Happy Horse、Seedance 2.0、Seedance 2.5、Grok Imagine、Veo 3.1、Gemini Omni Flash Preview、Vidu Q3、Hailuo、MiniMax H3 / H3 Max、Kling、Wan 2.6、Sora 2 | `POST /v1/video/generations`、`POST /v1/videos`、`POST /v1beta/interactions` 或 `POST /v2/video_generation` | | 语音与音乐 | 音乐生成、语音合成 | 模型专属音频接口 | | 数字人 | 数字人口播 | 模型专属数字人视频接口 | ## Model List Endpoint ```http GET /v1/models ``` 该接口返回当前模型列表。UniAll 会根据请求 Header 返回不同兼容格式： | 请求风格 | 判断规则 | 响应格式 | | --- | --- | --- | | OpenAI 兼容 | 默认请求风格 | OpenAI 模型列表 | | Anthropic 兼容 | 同时包含 `x-api-key` 和 `anthropic-version` | Anthropic 风格模型列表 | | Gemini 兼容 | 包含 `x-goog-api-key` Header 或 `key` 查询参数 | Gemini 风格模型列表 | 在当前文档范围内，规范化页面重点覆盖已选定的图像、视频、语音音乐和数字人能力。 ## Required Headers ```http Authorization: Bearer sk-*** ``` 兼容格式客户端可以在对应格式文档允许时使用原生认证 Header。 ## Request Example ```bash curl "{BASE_URL}/v1/models" \ -H "Authorization: Bearer sk-***" ``` ## Response Example ```json { "object": "list", "data": [ { "id": "grok-imagine", "object": "model", "created": 0, "owned_by": "uniall" }, { "id": "gpt-image-2.5-flare", "object": "model", "created": 0, "owned_by": "uniall" }, { "id": "gpt-image-2.6-flare", "object": "model", "created": 0, "owned_by": "uniall" }, { "id": "gpt-image-2.6-sunburst", "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 - Nano Banana 2.1：OpenAI 风格使用 `nano-banana-2.1`，参阅 [OpenAI Images 指引](/zh-CN/models/image/nano-series/nano-banana-2-1/openai-format)；Gemini 风格使用官方 ID `gemini-nano-banana-2.1`，参阅 [Gemini generateContent 指引](/zh-CN/models/image/nano-series/nano-banana-2-1/gemini-format)。两种风格均同步返回结果。 - 图像生成或图像编辑任务使用 [通用异步图像生成](/zh-CN/models/image/async-image-generation)。 - 使用 [Qwen Image](/zh-CN/models/image/qwen-image) 调用 3.0、2.1、2.0 系列六个模型的 OpenAI Images 或百炼原生同步生图与编辑接口。 - 使用 [GPT-Image-2.5](/zh-CN/models/image/gpt-image-2-5) 调用 GPT Image 2.5 的同步生成和编辑接口。 - 使用 [GPT-Image-2.6](/zh-CN/models/image/gpt-image-2-6) 调用 `gpt-image-2.6-flare` 和 `gpt-image-2.6-sunburst` 的同步生图、编辑及 GIF 生成接口。 - 当模型 ID 为 `seedream-5.0-pro` 时，使用 [Seedream 5.0 Pro 图像生成](/zh-CN/models/image/seedream-5-0-pro)。 - 模型 ID `seedance2.5` 使用 [Seedance 2.5](/zh-CN/models/video/seedance-2-5)，支持普通 1080p 输出及 [480p Draft 转 1080p 成片流程](/zh-CN/models/video/seedance-2-5#draft-to-final)。 - 使用 [MiniMax H3 原生 API](/zh-CN/models/video/minimax-h3) 调用 `MiniMax-H3` 和 `MiniMax-H3-Max`。 - 当模型 ID 为 `grok-imagine` 时，使用 [Grok Imagine 视频生成](/zh-CN/models/video/grok-imagine)。 - 当模型 ID 为 `gemini-omni-flash-preview` 时，使用 [Gemini Omni Flash Preview 视频生成](/zh-CN/models/video/gemini-omni-flash-preview)。 - 当模型 ID 为 `hailuo-02`、`hailuo-2.3` 或 `hailuo-2.3-fast` 时，使用 [Hailuo 视频生成](/zh-CN/models/video/hailuo)。 - 使用 [Kling 图片](/zh-CN/models/image/kling)调用 `kling-v3`、`kling-v3-omni` 或 `kling-image-o1` 图片任务。 - 使用 [Kling 视频](/zh-CN/models/video/kling)调用版本级可灵视频模型；`operation: avatar` 使用[数字人口播](/zh-CN/models/avatar/digital-human)。 - 能力专属页面会说明模型字段和任务生命周期。 - `/v1/models` 适合运行时发现模型，不应作为唯一集成规则来源。 ## Common Errors | HTTP 状态 | 含义 | | --- | --- | | `401` | 缺少认证或认证无效。 | | `403` | 当前 API Key 已禁用，或没有访问模型列表权限。 | ## Related Pages - [文档概览](/zh-CN/) - [查询余额](/zh-CN/balance) - [通用异步图像生成](/zh-CN/models/image/async-image-generation) - [GPT-Image-2.6](/zh-CN/models/image/gpt-image-2-6) - [Qwen Image](/zh-CN/models/image/qwen-image) - [Seedream 5.0 Pro 图像生成](/zh-CN/models/image/seedream-5-0-pro) - [Seedance 2.5](/zh-CN/models/video/seedance-2-5) - [Grok Imagine 视频生成](/zh-CN/models/video/grok-imagine) - [Gemini Omni Flash Preview 视频生成](/zh-CN/models/video/gemini-omni-flash-preview) - [Hailuo 视频生成](/zh-CN/models/video/hailuo) - [Kling 图片](/zh-CN/models/image/kling) - [Kling 视频](/zh-CN/models/video/kling) - [数字人口播](/zh-CN/models/avatar/digital-human) --- # 音乐生成 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/audio/music-generation Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/audio/music-generation.md Description: MiniMax Music 音乐生成来源文档。 本文档介绍如何在 aijisu 中使用 MiniMax Music 2.6 异步音乐生成接口。 当前支持模型： | 模型名称 | 类型 | 适合场景 | 计费方式 | |---|---|---|---| | `minimax-music-2.6` | 音乐生成 | 广告音乐、短视频 BGM、播客开场、产品宣传曲、纯音乐氛围铺底 | 按输出音频条数计费 | 接口采用异步任务模式： | 操作 | 方法 | 路径 | |---|---|---| | 提交音乐任务 | `POST` | `/v1/audio/tasks` | | 查询音乐任务 | `GET` | `/v1/audio/tasks/{task_id}` | --- ## 1. 通用鉴权 所有接口都需要在请求头中携带 API Key： ```http Authorization: Bearer sk-xxxxxxxxxxxxxxxx Content-Type: application/json ``` 示例域名： ```uri https://api.xxx.xx ``` --- ## 2. 模型简介 `minimax-music-2.6` 用于根据音乐描述和歌词生成音乐音频。它适合生成短视频配乐、广告歌曲、品牌宣传曲、播客片头、课程开场音乐、情绪氛围 BGM 等。 模型支持两类常见方式： - 有歌词歌曲：传 `prompt` + `lyrics` - 纯音乐：传 `prompt` + `is_instrumental: true` --- ## 3. 提交音乐任务 ```http POST https://api.xxx.xx/v1/audio/tasks ``` ### 3.1 请求参数 | 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | `model` | string | 是 | 固定为 `minimax-music-2.6` | | `prompt` | string | 是 | 音乐描述，建议包含风格、情绪、速度、用途、乐器、声音质感 | | `lyrics` | string | 否 | 歌词。非纯音乐时建议提供 | | `lyrics_optimizer` | boolean | 否 | 是否优化歌词 | | `is_instrumental` | boolean | 否 | 是否生成纯音乐 | | `audio_setting` | object | 否 | 音频设置对象，按平台开放能力透传 | ### 3.2 提交响应示例 ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "audio.generation.job", "status": "queued" } ``` 字段说明： | 字段 | 说明 | |---|---| | `id` / `task_id` | 异步任务 ID，用于查询结果 | | `status` | 任务状态，常见值为 `queued`、`processing`、`completed`、`failed` | --- ## 4. 查询音乐任务 ```http GET https://api.xxx.xx/v1/audio/tasks/{task_id} ``` 查询示例： ```bash curl -X GET "https://api.xxx.xx/v1/audio/tasks/task_xxxxxxxxxxxxx" \ -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" ``` 完成响应示例： ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "audio.generation.job", "status": "completed", "audio_url": "https://api.xxx.xx/media/xxxxx.mp3", "result": { "outputs": [ "https://api.xxx.xx/media/xxxxx.mp3" ], "audios": [ { "url": "https://api.xxx.xx/media/xxxxx.mp3" } ] } } ``` --- ## 5. 请求示例 ### 5.1 生成广告歌曲 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-music-2.6", "prompt": "A bright synth pop song for a product launch, upbeat, modern commercial style, clean vocal, energetic chorus", "lyrics": "Hello future, we are ready now\nLight the skyline, make it loud\nEvery step is shining brighter\nWe are here and moving proud", "lyrics_optimizer": true, "is_instrumental": false }' ``` ### 5.2 生成短视频 BGM ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-music-2.6", "prompt": "A catchy 30-second lifestyle vlog background track, light guitar, soft beat, sunny mood, no vocal", "is_instrumental": true }' ``` ### 5.3 生成播客片头音乐 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-music-2.6", "prompt": "A warm podcast intro jingle, 8 to 12 seconds feeling, soft piano, subtle electronic pulse, professional and friendly", "is_instrumental": true }' ``` ### 5.4 生成中文品牌歌曲 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-music-2.6", "prompt": "Chinese mandopop brand song, warm female vocal, inspiring chorus, clean arrangement, suitable for a technology brand", "lyrics": "向前走 不回头\n新的光 落在心口\n每一次 出发的时候\n我们都 把未来握在手中", "lyrics_optimizer": true, "is_instrumental": false }' ``` ### 5.5 生成课程开场音乐 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-music-2.6", "prompt": "Educational course intro music, calm but motivating, soft marimba, piano, gentle percussion, suitable for online learning", "is_instrumental": true }' ``` --- ## 6. 常见错误 ### 6.1 缺少 prompt 错误请求： ```json { "model": "minimax-music-2.6", "lyrics": "Hello world" } ``` 修复方式：补充 `prompt`。 ### 6.2 非纯音乐但缺少歌词 如果设置： ```json { "is_instrumental": false } ``` 建议同时传入 `lyrics`。 --- ## 7. 推荐工作流 1. 根据场景写清楚音乐风格、情绪、用途。 2. 如果需要人声，提供歌词。 3. 提交 `/v1/audio/tasks`。 4. 轮询 `/v1/audio/tasks/{task_id}`。 5. 任务完成后读取 `audio_url`。 --- ## 8. 最小可用请求 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-music-2.6", "prompt": "A bright short commercial pop song, modern and uplifting", "is_instrumental": true }' ``` --- # 语音与音乐概览 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/audio/overview Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/audio/overview.md Description: UniAll 语音合成和音乐生成文档入口。 本分类整理来源菜单中的语音合成和音乐生成。 ## 包含页面 - [音乐生成](/zh-CN/models/audio/music-generation) - [语音合成](/zh-CN/models/audio/speech-synthesis) ## 接入建议 `minimax-music-2.6` 音乐任务使用 [音乐生成](/zh-CN/models/audio/music-generation)。MiniMax Speech HD 文本转语音和音色管理使用 [语音合成](/zh-CN/models/audio/speech-synthesis)。 两个能力都以异步音频任务为主：先提交任务，再根据 `task_id` 轮询，成功后读取返回的音频 URL。 --- # 语音合成 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/audio/speech-synthesis Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/audio/speech-synthesis.md Description: 使用 UniAll 异步音频 API 生成语音并管理 MiniMax 音色。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 使用 MiniMax Speech HD 系列模型可以把文本生成语音。音色管理接口可以查询系统音色，也可以通过声音克隆或声音设计创建可复用的私有 `voice_id`。 ## When To Use It - 为短视频、广告、课程、旁白或数字人生成语音。 - 使用系统公共音色。 - 克隆或设计私有音色，再把返回的 `voice_id` 用在语音任务中。 ## Supported Models | 模型 | 类型 | 推荐场景 | | --- | --- | --- | | `minimax-speech-2.8-hd` | 文本转语音 | 自然短口播、情绪旁白、广告、数字人语音。 | | `minimax-speech-02-hd` | 文本转语音 | 有声书、课程讲解、客服播报、新闻播报、长文本旁白。 | ## Endpoint ```http POST /v1/audio/tasks GET /v1/audio/tasks/{task_id} GET /v1/audio/voices POST /v1/audio/voices/clone POST /v1/audio/voices/design ``` ## Authentication ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## Speech Request Parameters | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | `minimax-speech-2.8-hd` 或 `minimax-speech-02-hd`。 | | `text` | string | 是 | 需要合成的文本。 | | `voice_id` | string | 是 | 公共或私有音色 ID。 | | `speed` | number | 否 | 模型支持时控制语速。 | | `volume` | number | 否 | 模型支持时控制音量。 | | `pitch` | number | 否 | 模型支持时控制音高。 | | `format` | string | 否 | 输出格式，例如 `mp3` 或 `wav`。 | | `language` | string | 否 | 多语言文本的语言提示。 | | `audio_setting` | object | 否 | 模型支持时透传的高级音频设置。 | ## Speech Request Example ```bash curl -X POST "{BASE_URL}/v1/audio/tasks" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-2.8-hd", "text": "Welcome back. Today we will introduce a faster way to build AI applications.", "voice_id": "voice_xxx", "format": "mp3", "speed": 1 }' ``` ## Submit Response ```json { "task_id": "task_xxx", "status": "queued", "model": "minimax-speech-2.8-hd", "created_at": 1773980459 } ``` ## Query Task Status ```bash curl "{BASE_URL}/v1/audio/tasks/task_xxx" \ -H "Authorization: Bearer sk-***" ``` ```json { "task_id": "task_xxx", "status": "succeeded", "progress": "100%", "output": { "audio_url": "https://example.com/speech.mp3" }, "error": null } ``` ## Voice Management 查询可用音色： ```bash curl "{BASE_URL}/v1/audio/voices" \ -H "Authorization: Bearer sk-***" ``` 通过参考音频克隆音色： ```bash curl -X POST "{BASE_URL}/v1/audio/voices/clone" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "name": "brand-narrator", "audio_url": "https://example.com/reference.wav" }' ``` 通过文本描述设计音色： ```bash curl -X POST "{BASE_URL}/v1/audio/voices/design" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "name": "warm-host", "description": "Warm, clear, young adult narrator for product explainers" }' ``` 后续语音任务中使用返回的 `voice_id`。 ## Billing Notes 语音生成按生成音频用量计费。声音克隆和声音设计会创建可复用私有音色，可能单独计费。精确价格应以当前产品价格页为准。 ## Common Errors - 缺少 `text` 或 `voice_id`。 - 传入当前账户不可见的私有 `voice_id`。 - 文本过长但没有拆分为多个任务。 - 输出格式不支持。 - 余额不足或 API Key 已禁用。 ## Related Pages - [语音与音乐概览](/zh-CN/models/audio/overview) - [音乐生成](/zh-CN/models/audio/music-generation) - [数字人口播](/zh-CN/models/avatar/digital-human) --- # MiniMax Speech HD Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/audio/speech/minimax-speech-hd Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/audio/speech/minimax-speech-hd.md Description: MiniMax Speech HD 语音生成来源文档。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 本文档介绍如何在 aijisu 中使用 MiniMax Speech HD 系列异步语音生成模型。 当前支持模型： | 模型名称 | 类型 | 推荐场景 | |---|---|---| | `minimax-speech-2.8-hd` | 文本转语音 | 短视频口播、广告配音、数字人语音、情绪化旁白、自然口语 | | `minimax-speech-02-hd` | 文本转语音 | 有声书、课程讲解、客服播报、新闻播报、长文本旁白、多语言语音 | 接口采用异步任务模式： | 操作 | 方法 | 路径 | |---|---|---| | 提交语音任务 | `POST` | `/v1/audio/tasks` | | 查询语音任务 | `GET` | `/v1/audio/tasks/{task_id}` | 基础请求地址示例： ```uri https://api.xxx.xx ``` ## 1. 模型简介 ### 1.1 minimax-speech-2.8-hd `minimax-speech-2.8-hd` 是更新一代高清语音生成模型，适合需要更强自然感、口语感、停顿感和情绪表现力的语音内容。 适合场景： - 短视频口播 - 广告配音 - 数字人讲解 - 情绪化角色台词 - 播客开场 - 带笑声、叹气、停顿等自然声音细节的内容 推荐文本示例： ```markdown 欢迎回来。<#0.5#> 今天我们聊一个很有意思的话题。(laughs) ``` ### 1.2 minimax-speech-02-hd `minimax-speech-02-hd` 是成熟稳定的高清语音生成模型，适合生产型、稳定型、长文本型语音任务。 适合场景： - 有声书 - 课程讲解 - 企业培训 - 新闻播报 - 客服语音 - 长文本旁白 - 多语言语音生成 推荐文本示例： ```markdown 本节课我们将学习函数的基本概念。函数可以帮助我们封装重复逻辑，提高代码复用性。 ``` ## 2. 鉴权方式 所有请求都需要携带 API Key。 请求头： ```http Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` ## 3. 提交语音生成任务 请求地址： ```http POST https://api.xxx.xx/v1/audio/tasks ``` ### 3.1 请求参数 | 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | `model` | string | 是 | 模型名称，支持 `minimax-speech-2.8-hd`、`minimax-speech-02-hd` | | `text` | string | 是 | 要生成语音的文本 | | `input` | string | 否 | `text` 的别名，适配部分 OpenAI 风格请求 | | `voice_id` | string | 否 | 音色 ID，例如平台提供的预设音色或克隆音色 ID | | `voice` | string | 否 | 音色名称，兼容字段 | | `speed` | number | 否 | 语速，常用范围 `0.5` 到 `2.0` | | `emotion` | string | 否 | 情绪，如 `happy`、`sad`、`angry`、`fearful`、`disgusted`、`surprised`、`neutral` | | `language` | string | 否 | 语言提示，如 `Chinese`、`English`、`Japanese`、`auto` | | `output_format` | string | 否 | 输出格式，建议使用 `url` | | `response_format` | string | 否 | 响应格式，建议使用 `url` | | `sample_rate` | number | 否 | 采样率，如 `32000`、`44100` | | `pronunciation_dict` | object | 否 | 自定义发音词典 | | `timber_weights` | array | 否 | 混合音色权重，高级用法 | | `subtitle_enable` | boolean | 否 | 是否尝试生成字幕信息 | | `metadata` | object | 否 | 自定义业务信息 | | `extra_body` | object | 否 | 高级参数扩展 | 注意： - `text` 和 `input` 二选一即可。 - 推荐优先使用 `text`。 - 如果同时传入 `text` 和 `input`，两者内容必须一致。 - 当前接口为异步任务接口，提交任务后需要通过 `task_id` 查询结果。 - 计费按输入字符数计算，中文、英文、数字、标点、空格、换行、emoji、停顿标签、声音标签都会计入字符数。 - 示例中的 `voice_id` 仅用于演示，请替换为站内实际可用音色 ID。 ### 3.2 最简请求示例 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-2.8-hd", "text": "你好，欢迎使用 aijisu 语音生成服务。" }' ``` ### 3.3 提交成功返回示例 ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "audio.generation.job", "status": "queued", "raw_status": "SUBMITTED", "progress": "0%", "audio_url": null, "result": null, "error": null } ``` ## 4. 查询任务结果 请求地址： ```http GET https://api.xxx.xx/v1/audio/tasks/{task_id} ``` 请求示例： ```bash curl -X GET "https://api.xxx.xx/v1/audio/tasks/task_xxxxxxxxxxxxx" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### 4.1 生成中返回示例 ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "audio.generation.job", "status": "in_progress", "raw_status": "IN_PROGRESS", "progress": "45%", "audio_url": null, "result": null, "error": null } ``` ### 4.2 生成完成返回示例 ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "audio.generation.job", "status": "completed", "raw_status": "SUCCESS", "progress": "100%", "audio_url": "https://example.com/audio.mp3", "result": { "audio_url": "https://example.com/audio.mp3", "outputs": [ "https://example.com/audio.mp3" ], "audios": [ { "url": "https://example.com/audio.mp3" } ] }, "error": null } ``` ### 4.3 生成失败返回示例 ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "audio.generation.job", "status": "failed", "raw_status": "FAILURE", "progress": "100%", "audio_url": null, "result": null, "error": { "message": "audio task failed" } } ``` ## 5. 任务状态说明 | status | 说明 | |---|---| | `queued` | 已提交，等待处理 | | `in_progress` | 正在生成 | | `processing` | 处理中 | | `completed` | 生成完成 | | `failed` | 生成失败 | 建议每 2 到 5 秒查询一次任务状态，不建议高频轮询。 ## 6. 声音标签和停顿 `minimax-speech-2.8-hd` 更适合使用自然声音标签和停顿标记。 | 写法 | 说明 | |---|---| | `<#0.5#>` | 停顿 0.5 秒 | | `<#1.0#>` | 停顿 1 秒 | | `(laughs)` | 笑声 | | `(sighs)` | 叹气 | | `(coughs)` | 咳嗽 | | `(clears throat)` | 清嗓 | | `(gasps)` | 倒吸气 | | `(sniffs)` | 吸鼻 | | `(groans)` | 低哼 | | `(yawns)` | 打哈欠 | 示例： ```markdown 你终于来了。<#0.8#> 我还以为，你已经忘了这个约定。(sighs) ``` ## 7. 使用场景示例 ### 7.1 中文短视频口播 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-2.8-hd", "text": "今天给大家分享一个提高效率的小技巧。<#0.4#> 很简单，但真的很有用。", "voice_id": "Wise_Woman", "speed": 1.05, "emotion": "happy", "output_format": "url" }' ``` ### 7.2 课程讲解 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-02-hd", "text": "本节课我们将学习函数的基本概念。函数可以帮助我们把重复的逻辑封装起来，提高代码的复用性。", "voice_id": "Wise_Woman", "speed": 0.95, "emotion": "neutral", "output_format": "url" }' ``` ### 7.3 广告配音 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-2.8-hd", "text": "全新升级，限时开启。<#0.3#> 现在下单，享受专属优惠！", "voice_id": "Wise_Woman", "speed": 1.12, "emotion": "happy", "output_format": "url" }' ``` ### 7.4 有声书旁白 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-02-hd", "text": "夜色渐深，街边的灯一盏接一盏亮起。她站在窗前，安静地望着远处的城市。", "voice_id": "Wise_Woman", "speed": 0.88, "emotion": "neutral", "output_format": "url" }' ``` ### 7.5 情绪化角色台词 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-2.8-hd", "text": "你终于来了。<#0.6#> 我还以为，你已经忘了这个约定。(sighs)", "voice_id": "Wise_Woman", "speed": 0.92, "emotion": "sad", "output_format": "url" }' ``` ### 7.6 英文播客开场 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-2.8-hd", "text": "Hey, welcome back to the show. <#0.4#> Today we are talking about how AI is changing creative work. (laughs)", "voice_id": "Wise_Woman", "speed": 1.0, "emotion": "happy", "language": "English", "output_format": "url" }' ``` ### 7.7 多语言客服问候 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-02-hd", "text": "您好，欢迎致电客户服务中心。Please hold on for a moment. 我们将尽快为您服务。", "voice_id": "Wise_Woman", "speed": 1.0, "language": "auto", "emotion": "neutral", "output_format": "url" }' ``` ### 7.8 新闻播报 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-02-hd", "text": "今天的主要新闻包括：人工智能产业持续增长，多家企业发布新一代智能创作工具。", "voice_id": "Wise_Woman", "speed": 1.0, "emotion": "neutral", "output_format": "url" }' ``` ### 7.9 数字人口播 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-2.8-hd", "text": "大家好，我是你的 AI 助手。<#0.4#> 接下来，我会用一分钟带你了解今天的重点内容。", "voice_id": "Wise_Woman", "speed": 1.03, "emotion": "happy", "output_format": "url" }' ``` ### 7.10 儿童故事 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-2.8-hd", "text": "很久很久以前，森林里住着一只勇敢的小兔子。它每天最喜欢做的事情，就是去河边看星星。", "voice_id": "Wise_Woman", "speed": 0.9, "emotion": "happy", "output_format": "url" }' ``` ### 7.11 企业培训语音 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-02-hd", "text": "欢迎参加本次企业安全培训。请大家认真阅读操作规范，并在实际工作中严格遵守。", "voice_id": "Wise_Woman", "speed": 0.96, "emotion": "neutral", "output_format": "url" }' ``` ### 7.12 慢速冥想旁白 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-2.8-hd", "text": "闭上眼睛。<#1.0#> 慢慢吸气。<#1.0#> 再缓缓呼出。", "voice_id": "Wise_Woman", "speed": 0.82, "emotion": "neutral", "output_format": "url" }' ``` ### 7.13 使用 input 字段提交 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-02-hd", "input": "这是一条使用 input 字段提交的语音生成任务。", "voice_id": "Wise_Woman", "output_format": "url" }' ``` ### 7.14 自定义发音词典 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-2.8-hd", "text": "欢迎使用 AI极速，新一代智能创作平台。", "voice_id": "Wise_Woman", "output_format": "url", "pronunciation_dict": { "tone_list": [ "AI极速/(A)(I)(ji2)(su4)" ] } }' ``` ### 7.15 高采样率音频 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-2.8-hd", "text": "这是一段用于视频后期制作的高质量配音。", "voice_id": "Wise_Woman", "sample_rate": 44100, "output_format": "url" }' ``` ### 7.16 客服 IVR 菜单播报 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-02-hd", "text": "您好，欢迎致电。业务咨询请按一，订单查询请按二，人工服务请按零。", "voice_id": "Wise_Woman", "speed": 0.98, "emotion": "neutral", "output_format": "url" }' ``` ### 7.17 产品介绍视频旁白 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-2.8-hd", "text": "这是一款为创作者打造的智能工具。<#0.4#> 它可以帮你更快完成脚本、配音和内容生成。", "voice_id": "Wise_Woman", "speed": 1.02, "emotion": "happy", "output_format": "url" }' ``` ### 7.18 严肃纪录片旁白 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-02-hd", "text": "在漫长的时间里，人类不断探索自然、理解世界，并试图找到自身与时代之间的关系。", "voice_id": "Wise_Woman", "speed": 0.9, "emotion": "neutral", "output_format": "url" }' ``` ## 8. JavaScript 调用示例 ```javascript const API_KEY = "YOUR_API_KEY"; const BASE_URL = "https://api.xxx.xx"; async function createAudioTask() { const response = await fetch(`${BASE_URL}/v1/audio/tasks`, { method: "POST", headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" }, body: JSON.stringify({ model: "minimax-speech-2.8-hd", text: "你好，这是一段由 aijisu 生成的语音。", voice_id: "Wise_Woman", speed: 1, emotion: "neutral", output_format: "url" }) }); if (!response.ok) { throw new Error(await response.text()); } return await response.json(); } async function getAudioTask(taskId) { const response = await fetch(`${BASE_URL}/v1/audio/tasks/${taskId}`, { method: "GET", headers: { "Authorization": `Bearer ${API_KEY}` } }); if (!response.ok) { throw new Error(await response.text()); } return await response.json(); } async function main() { const task = await createAudioTask(); console.log("task_id:", task.task_id); while (true) { const result = await getAudioTask(task.task_id); console.log(result.status, result.progress); if (result.status === "completed") { console.log("audio_url:", result.audio_url); break; } if (result.status === "failed") { console.error("failed:", result.error); break; } await new Promise(resolve => setTimeout(resolve, 3000)); } } main().catch(console.error); ``` ## 9. Python 调用示例 ```python import time import requests API_KEY = "YOUR_API_KEY" BASE_URL = "https://api.xxx.xx" headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", } payload = { "model": "minimax-speech-02-hd", "text": "你好，这是一段通过 Python 提交的语音生成任务。", "voice_id": "Wise_Woman", "speed": 1, "emotion": "neutral", "output_format": "url", } create_resp = requests.post( f"{BASE_URL}/v1/audio/tasks", headers=headers, json=payload, ) create_resp.raise_for_status() task = create_resp.json() task_id = task["task_id"] while True: query_resp = requests.get( f"{BASE_URL}/v1/audio/tasks/{task_id}", headers={"Authorization": f"Bearer {API_KEY}"}, ) query_resp.raise_for_status() result = query_resp.json() print(result["status"], result.get("progress")) if result["status"] == "completed": print("audio_url:", result.get("audio_url")) break if result["status"] == "failed": print("failed:", result.get("error")) break time.sleep(3) ``` ## 10. 计费说明 语音生成按输入字符数计费。 会计入字符数的内容包括： - 中文 - 英文 - 数字 - 标点 - 空格 - 换行 - emoji - 声音标签 - 停顿标签 示例： ```markdown 你好，世界！ ``` 字符计算： ```markdown 你 好 ， 世 界 ！ ``` 共 6 个字符。 实际扣费以站内模型价格、分组倍率、套餐规则和账户余额规则为准。 ## 11. 模型选择建议 ### 11.1 优先使用 minimax-speech-2.8-hd 适合： - 需要更自然的口语表达 - 需要笑声、叹气、停顿等声音细节 - 做短视频口播 - 做广告配音 - 做数字人口播 - 做情绪化角色语音 ### 11.2 优先使用 minimax-speech-02-hd 适合： - 长文本旁白 - 有声书 - 课程讲解 - 客服播报 - 新闻播报 - 多语言内容 - 更偏稳定生产的场景 ## 12. 推荐模板 ### 12.1 短视频口播模板 ```json { "model": "minimax-speech-2.8-hd", "text": "今天给大家分享一个非常实用的小技巧。<#0.4#> 学会之后，你的效率会明显提升。", "voice_id": "Wise_Woman", "speed": 1.05, "emotion": "happy", "output_format": "url" } ``` ### 12.2 有声书模板 ```json { "model": "minimax-speech-02-hd", "text": "夜色渐深，城市的喧嚣慢慢退去，只剩窗外微弱的风声。", "voice_id": "Wise_Woman", "speed": 0.88, "emotion": "neutral", "output_format": "url" } ``` ### 12.3 客服播报模板 ```json { "model": "minimax-speech-02-hd", "text": "您好，欢迎致电客户服务中心。请稍候，我们将尽快为您接通人工服务。", "voice_id": "Wise_Woman", "speed": 1, "emotion": "neutral", "output_format": "url" } ``` ### 12.4 情绪角色模板 ```json { "model": "minimax-speech-2.8-hd", "text": "你真的要离开吗？<#0.8#> 我以为，我们还有机会。(sighs)", "voice_id": "Wise_Woman", "speed": 0.92, "emotion": "sad", "output_format": "url" } ``` ### 12.5 英文口播模板 ```json { "model": "minimax-speech-2.8-hd", "text": "Welcome back. <#0.4#> Today we are going to talk about how creators can use AI to work faster.", "voice_id": "Wise_Woman", "speed": 1, "emotion": "happy", "language": "English", "output_format": "url" } ``` ## 13. 常见问题 ### 13.1 为什么提交后没有立刻返回音频？ 因为语音生成是异步任务。提交接口只返回任务 ID，需要通过查询接口获取最终音频 URL。 ### 13.2 `text` 和 `input` 有什么区别？ `input` 是 `text` 的别名。推荐优先使用 `text`。 ### 13.3 能不能一次生成多个音频？ 当前建议一次请求生成一条音频。如果需要多段音频，建议拆成多个任务分别提交。 ### 13.4 长文本怎么处理？ 建议按段落拆分成多个任务。这样更容易控制失败重试、段落顺序和后期拼接。 ### 13.5 如何让语音更自然？ 建议： - 保留标点符号 - 适当加入停顿标签 - 不要把单句写得过长 - 根据场景调整 `speed` - 口播、广告、数字人优先使用 `minimax-speech-2.8-hd` ### 13.6 音频 URL 可以直接播放吗？ 任务完成后返回的 `audio_url` 通常可以直接用于播放器播放、下载或后续处理。实际可访问时长以站点存储策略为准。 ### 13.7 请求失败时怎么排查？ 常见原因： - API Key 未填写或无效 - `model` 写错 - `text` 或 `input` 为空 - 同时传入 `text` 和 `input`，但两者内容不一致 - 音色 ID 不可用 - 参数格式不正确 - 账户余额不足或无权限使用该模型 ## 14. 完整流程示例 ### 第一步：提交任务 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-2.8-hd", "text": "你好，这是一条完整流程测试语音。", "voice_id": "Wise_Woman", "speed": 1, "emotion": "neutral", "output_format": "url" }' ``` 返回： ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "audio.generation.job", "status": "queued", "raw_status": "SUBMITTED", "progress": "0%", "audio_url": null, "result": null, "error": null } ``` ### 第二步：查询任务 ```bash curl -X GET "https://api.xxx.xx/v1/audio/tasks/task_xxxxxxxxxxxxx" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### 第三步：获取音频 URL 当 `status` 为 `completed` 时，读取： ```json { "audio_url": "https://example.com/audio.mp3" } ``` 即可播放或下载生成的音频。 --- # MiniMax Speech 音色管理 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/audio/speech/voice-management Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/audio/speech/voice-management.md Description: MiniMax Speech 音色管理来源文档。 本文档介绍如何在 aijisu 中使用 MiniMax 音色能力，包括音色列表、声音克隆和声音设计。 如果你只是想把文字生成语音，请使用语音生成接口： - `POST /v1/audio/tasks` - `GET /v1/audio/tasks/{task_id}` 如果你想创建自己的 `voice_id`，再把这个 `voice_id` 用到语音生成里，请使用本文档中的音色接口。 ## 1. 支持能力 | 能力 | 接口 | 是否收费 | 说明 | |---|---|---:|---| | 查询音色列表 | `GET /v1/audio/voices` | 否 | 返回系统公共音色和当前账号可见的私有音色 | | 声音克隆 | `POST /v1/audio/voices/clone` | 是 | 通过参考音频生成一个可复用的 `voice_id` | | 声音设计 | `POST /v1/audio/voices/design` | 是 | 通过文字描述设计一个可复用的 `voice_id` | | 使用音色生成语音 | `POST /v1/audio/tasks` | 是 | 将 `voice_id` 传给 TTS 模型生成音频 | 当前推荐配合以下 TTS 模型使用： | 模型名称 | 说明 | |---|---| | `minimax-speech-2.8-hd` | 更新一代高清语音生成模型，适合自然口播、短视频、数字人、广告配音 | | `minimax-speech-02-hd` | 稳定高清语音生成模型，适合旁白、有声书、课程、客服、长文本播报 | 声音克隆和声音设计创建出来的 `voice_id` 可以在以上两个 TTS 模型中使用。 ## 2. 接口地址 示例域名统一使用： ```uri https://api.xxx.xx ``` 实际调用时请替换为你的 aijisu API 域名。 | 操作 | 方法 | 路径 | |---|---|---| | 查询音色列表 | `GET` | `/v1/audio/voices` | | 声音克隆 | `POST` | `/v1/audio/voices/clone` | | 声音设计 | `POST` | `/v1/audio/voices/design` | | 提交语音生成任务 | `POST` | `/v1/audio/tasks` | | 查询语音生成任务 | `GET` | `/v1/audio/tasks/{task_id}` | ## 3. 鉴权方式 所有接口都使用 Bearer Token： ```http Authorization: Bearer YOUR_API_KEY ``` 示例： ```bash curl https://api.xxx.xx/v1/audio/voices \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## 4. 音色 ID 说明 `voice_id` 是调用 TTS 时使用的音色标识。 音色来源分为两类： | 来源 | 说明 | |---|---| | 系统音色 | 平台内置公共音色，所有用户可查询和使用 | | 私有音色 | 当前账号通过声音克隆或声音设计创建的音色，仅当前账号可见和可用 | 声音克隆和声音设计成功后，接口会返回一个 `voice_id`。你可以把它保存到自己的业务系统中，后续在 `/v1/audio/tasks` 中传入该 `voice_id` 来生成语音。 ## 5. 查询音色列表 ### 5.1 请求 ```http GET /v1/audio/voices ``` 可选查询参数： | 参数 | 类型 | 是否必填 | 说明 | |---|---|---:|---| | `model` | string | 否 | 按兼容模型筛选音色，可选 `minimax-speech-2.8-hd` 或 `minimax-speech-02-hd` | ### 5.2 查询全部可见音色 ```bash curl "https://api.xxx.xx/v1/audio/voices" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### 5.3 查询适用于 Speech 2.8 HD 的音色 ```bash curl "https://api.xxx.xx/v1/audio/voices?model=minimax-speech-2.8-hd" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### 5.4 查询适用于 Speech 02 HD 的音色 ```bash curl "https://api.xxx.xx/v1/audio/voices?model=minimax-speech-02-hd" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### 5.5 响应示例 ```json { "object": "audio.voice.list", "model": "minimax-speech-2.8-hd", "data": [ { "voice_id": "Chinese (Mandarin)_Kind-hearted_Elder", "display_name": "Kind-hearted Elder", "language": "Chinese (Mandarin)", "description": "MiniMax system voice", "source_type": "system", "visibility": "public", "status": "active", "compatible_models": [ "minimax-speech-2.8-hd", "minimax-speech-02-hd" ], "preview_audio_url": null, "created_at": "2026-06-23T18:05:59Z" }, { "voice_id": "ttv-voice-2026062416421526-E4jmMP8B", "display_name": "local-design-taskid-smoke", "language": "Chinese (Mandarin)", "description": "Local smoke test for task id in sync response.", "source_type": "voice_design", "visibility": "private", "status": "active", "compatible_models": [ "minimax-speech-2.8-hd", "minimax-speech-02-hd" ], "preview_audio_url": "https://api.xxx.xx/media/preview.mp3", "created_at": "2026-06-24T08:42:23Z" } ] } ``` ### 5.6 响应字段 | 字段 | 说明 | |---|---| | `object` | 固定为 `audio.voice.list` | | `model` | 当前筛选模型 | | `data` | 音色数组 | | `data[].voice_id` | 音色 ID，后续 TTS 调用传这个值 | | `data[].display_name` | 音色名称 | | `data[].language` | 音色语言 | | `data[].description` | 音色描述 | | `data[].source_type` | 音色来源，可能是 `system`、`voice_clone`、`voice_design` | | `data[].visibility` | 可见性，可能是 `public` 或 `private` | | `data[].status` | 状态，通常为 `active` | | `data[].compatible_models` | 可使用该音色的 TTS 模型 | | `data[].preview_audio_url` | 预览音频链接，可能为空 | | `data[].created_at` | 创建时间 | ## 6. 声音克隆 声音克隆用于从一段参考音频中提取声音特征，创建一个新的私有 `voice_id`。 适合场景： - 克隆主播、讲师、客服、品牌代言人的声音 - 为数字人生成固定音色 - 为课程、有声书、短视频矩阵复用同一个声音 - 把线下录音中的声音整理成可重复调用的 TTS 音色 ### 6.1 请求 ```http POST /v1/audio/voices/clone ``` 请求体为 JSON。 | 参数 | 类型 | 是否必填 | 说明 | |---|---|---:|---| | `audio_url` | string | 是 | 参考音频 URL，需要接口服务可访问 | | `text` | string | 建议 | 参考音频对应文本或预览文本，用于提升克隆质量和生成预览 | | `preview_text` | string | 否 | `text` 的兼容字段。若同时传，建议与 `text` 保持一致 | | `display_name` | string | 否 | 音色名称，便于列表展示 | | `name` | string | 否 | `display_name` 的兼容字段 | | `language` | string | 否 | 音色语言，例如 `Chinese (Mandarin)`、`English` | | `description` | string | 否 | 音色描述 | | `noise_reduction` | boolean | 否 | 是否启用降噪 | | `need_volume_normalization` | boolean | 否 | 是否进行音量归一化 | | `accuracy` | number/string | 否 | 克隆精度相关参数，按平台当前支持透传 | ### 6.2 参考音频建议 | 项目 | 建议 | |---|---| | 音频内容 | 单人说话，背景干净 | | 音频时长 | 建议 10 秒以上，过短会影响相似度 | | 录音质量 | 尽量无混响、无音乐、无明显噪声 | | 说话方式 | 自然稳定，不要频繁变声或多人交替 | | 文本匹配 | 如果知道音频原文，建议把原文放到 `text` | | 授权合规 | 仅克隆你有权使用的声音 | ### 6.3 最小请求示例 ```bash curl -X POST "https://api.xxx.xx/v1/audio/voices/clone" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "audio_url": "https://example.com/audio/reference-speaker.mp3", "text": "大家好，欢迎来到今天的课程。我们会用简单的方法讲清楚这个概念。", "display_name": "course-teacher-voice", "language": "Chinese (Mandarin)" }' ``` ### 6.4 带降噪和音量归一化 ```bash curl -X POST "https://api.xxx.xx/v1/audio/voices/clone" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "audio_url": "https://example.com/audio/noisy-reference.wav", "text": "这是一个用于声音克隆的参考音频，请尽量保持音色自然稳定。", "display_name": "cleaned-brand-speaker", "language": "Chinese (Mandarin)", "description": "品牌讲解类克隆音色", "noise_reduction": true, "need_volume_normalization": true }' ``` ### 6.5 英文主播声音克隆 ```bash curl -X POST "https://api.xxx.xx/v1/audio/voices/clone" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "audio_url": "https://example.com/audio/english-host.mp3", "text": "Welcome back to the show. Today we are going to explore a simple but powerful idea.", "display_name": "english-podcast-host", "language": "English", "description": "Warm English podcast host voice" }' ``` ### 6.6 响应示例 ```json { "object": "audio.voice", "model": "minimax-voice-clone", "task_id": "task_abc123", "voice_id": "VoiceClone123456", "preview_audio_url": "https://api.xxx.xx/media/voice-clone-preview.mp3", "voice": { "voice_id": "VoiceClone123456", "display_name": "course-teacher-voice", "language": "Chinese (Mandarin)", "description": "品牌讲解类克隆音色", "source_type": "voice_clone", "visibility": "private", "status": "active", "compatible_models": [ "minimax-speech-2.8-hd", "minimax-speech-02-hd" ], "preview_audio_url": "https://api.xxx.xx/media/voice-clone-preview.mp3", "created_at": "2026-06-24T08:42:23Z" }, "billing_contract": { "billing_version": "media-v1", "public_model": "minimax-voice-clone", "operation": "audio.voice_clone", "settlement_policy": "fixed_at_estimate", "billing_stage": "final", "facts": { "voice_clones": 1, "preview_characters": 36 } }, "outputs": [ { "url": "https://api.xxx.xx/media/voice-clone-preview.mp3", "type": "audio" } ] } ``` ## 7. 声音设计 声音设计用于通过文字描述生成一个新的私有 `voice_id`，不需要上传参考音频。 适合场景： - 为短视频账号设计固定口播音色 - 为数字人设计声音人设 - 为游戏角色、剧情角色、广播主持人设计声音 - 快速生成客服、课程、广告、旁白音色 - 没有参考音频，但有明确声音描述的场景 ### 7.1 请求 ```http POST /v1/audio/voices/design ``` 请求体为 JSON。 | 参数 | 类型 | 是否必填 | 说明 | |---|---|---:|---| | `prompt` | string | 是 | 声音设计描述，描述音色、性别、年龄感、语言、情绪、场景等 | | `preview_text` | string | 是 | 用于生成预览音频的文本 | | `text` | string | 否 | `preview_text` 的兼容字段 | | `display_name` | string | 否 | 音色名称，便于列表展示 | | `name` | string | 否 | `display_name` 的兼容字段 | | `language` | string | 否 | 音色语言，例如 `Chinese (Mandarin)`、`English` | | `description` | string | 否 | 音色描述 | ### 7.2 Prompt 写法建议 建议在 `prompt` 中描述这些信息： | 维度 | 示例 | |---|---| | 语言 | Chinese Mandarin、English、Cantonese | | 性别 | male、female | | 年龄感 | young adult、middle-aged、elder | | 声音质感 | warm、clear、soft、energetic、calm | | 场景 | product demo、customer service、audiobook、game character | | 情绪 | friendly、confident、gentle、dramatic | | 节奏 | slow、medium pace、lively | ### 7.3 中文温柔旁白 ```bash curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A warm, calm Chinese Mandarin female narrator voice for short product demos, clear diction, gentle confidence, studio quality.", "preview_text": "你好，这是一段声音设计预览。欢迎体验全新的语音能力。", "display_name": "warm-product-narrator", "language": "Chinese (Mandarin)", "description": "适合产品讲解和短视频口播的温柔女声" }' ``` ### 7.4 数字人口播音色 ```bash curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A confident Chinese Mandarin female digital human presenter voice, natural conversational tone, bright but not exaggerated, suitable for business explanation videos.", "preview_text": "大家好，我是你的智能讲解员。今天我们用一分钟了解这个功能。", "display_name": "digital-human-presenter", "language": "Chinese (Mandarin)", "description": "数字人讲解员音色" }' ``` ### 7.5 客服播报音色 ```bash curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A polite Chinese Mandarin customer service voice, patient, clear, stable, friendly, suitable for service notifications and call center messages.", "preview_text": "您好，您的订单已经处理完成。如有疑问，请随时联系我们的客服团队。", "display_name": "customer-service-clear", "language": "Chinese (Mandarin)", "description": "客服通知和电话播报音色" }' ``` ### 7.6 游戏角色音色 ```bash curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A young Chinese Mandarin fantasy game character voice, playful, lively, slightly mysterious, expressive but clear.", "preview_text": "终于等到你了。前面的路可不简单，跟紧我，我们马上出发。", "display_name": "fantasy-guide-character", "language": "Chinese (Mandarin)", "description": "游戏引导角色音色" }' ``` ### 7.7 英文广告音色 ```bash curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A modern English commercial voice, energetic, premium, confident, suitable for product launch ads and social media videos.", "preview_text": "Meet the new way to create, edit, and publish your ideas in minutes.", "display_name": "english-commercial-premium", "language": "English", "description": "English commercial voice for product ads" }' ``` ### 7.8 有声书旁白音色 ```bash curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A mature Chinese Mandarin audiobook narrator voice, calm, steady, immersive, with clear pronunciation and comfortable pacing.", "preview_text": "夜色慢慢落下，远处的灯光一盏接一盏亮起，故事也从这里开始。", "display_name": "audiobook-calm-narrator", "language": "Chinese (Mandarin)", "description": "有声书长篇旁白音色" }' ``` ### 7.9 响应示例 ```json { "object": "audio.voice", "model": "minimax-voice-design", "task_id": "task_437fb17536aa4ff7830ffb7a39f43a99", "voice_id": "ttv-voice-2026062416421526-E4jmMP8B", "preview_audio_url": "https://api.xxx.xx/media/design-preview.mp3", "voice": { "voice_id": "ttv-voice-2026062416421526-E4jmMP8B", "display_name": "warm-product-narrator", "language": "Chinese (Mandarin)", "description": "适合产品讲解和短视频口播的温柔女声", "source_type": "voice_design", "visibility": "private", "status": "active", "compatible_models": [ "minimax-speech-2.8-hd", "minimax-speech-02-hd" ], "preview_audio_url": "https://api.xxx.xx/media/design-preview.mp3", "created_at": "2026-06-24T08:42:23Z" }, "billing_contract": { "billing_version": "media-v1", "public_model": "minimax-voice-design", "operation": "audio.voice_design", "settlement_policy": "fixed_at_estimate", "billing_stage": "final", "facts": { "voice_designs": 1, "preview_characters": 12 } }, "outputs": [ { "url": "https://api.xxx.xx/media/design-preview.mp3", "type": "audio" } ] } ``` ## 8. 将 voice_id 用于语音生成 声音克隆或声音设计成功后，把返回的 `voice_id` 放到 `/v1/audio/tasks` 中即可生成语音。 ### 8.1 使用声音设计音色生成中文口播 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-2.8-hd", "text": "欢迎来到今天的产品演示。接下来，我们会快速了解三个核心功能。", "voice_id": "ttv-voice-2026062416421526-E4jmMP8B", "speed": 1.0, "response_format": "url" }' ``` ### 8.2 使用声音克隆音色生成课程讲解 ```bash curl -X POST "https://api.xxx.xx/v1/audio/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-speech-02-hd", "text": "本节课我们来学习一个非常重要的概念。请先观察这个例子，再思考它背后的规律。", "voice_id": "VoiceClone123456", "speed": 0.95, "response_format": "url" }' ``` ### 8.3 查询语音生成任务 ```bash curl "https://api.xxx.xx/v1/audio/tasks/task_abc123" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### 8.4 语音生成任务完成响应示例 ```json { "object": "audio.generation.job", "task_id": "task_abc123", "model": "minimax-speech-2.8-hd", "status": "completed", "audio_url": "https://api.xxx.xx/media/output.mp3", "result": { "audio_url": "https://api.xxx.xx/media/output.mp3", "outputs": [ "https://api.xxx.xx/media/output.mp3" ], "audios": [ { "url": "https://api.xxx.xx/media/output.mp3" } ] } } ``` ## 9. 计费说明 实际扣费以 aijisu 控制台展示和账户配置为准。以下为当前接口的基础计费口径。 | 能力 | 计费项 | 基础计费公式 | |---|---|---| | 查询音色列表 | 免费 | 不扣费 | | 声音克隆 | 克隆次数 + 预览字符 | `voice_clones * 1.5 + preview_characters * 0.0003` | | 声音设计 | 设计次数 + 预览字符 | `voice_designs * 3 + preview_characters * 0.00003` | | 语音生成 | 输入字符数 | 按 TTS 模型的字符计费规则 | 说明： - `preview_characters` 是预览文本的 Unicode 字符数。 - 中文、英文、空格、标点、换行、emoji 都会计入字符数。 - 字符数不是 UTF-8 字节数，也不是 token 数。 - 声音克隆和声音设计采用提交时确认计费策略。 - 如果请求失败，按平台失败退款规则处理。 ## 10. Node.js 示例 ### 10.1 声音设计 ```javascript const response = await fetch("https://api.xxx.xx/v1/audio/voices/design", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" }, body: JSON.stringify({ prompt: "A warm Chinese Mandarin female narrator voice, clear and calm.", preview_text: "你好，这是声音设计预览。", display_name: "node-design-voice", language: "Chinese (Mandarin)" }) }); const data = await response.json(); console.log(data.voice_id); console.log(data.preview_audio_url); ``` ### 10.2 用生成的 voice_id 创建语音任务 ```javascript const voiceId = "ttv-voice-2026062416421526-E4jmMP8B"; const response = await fetch("https://api.xxx.xx/v1/audio/tasks", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" }, body: JSON.stringify({ model: "minimax-speech-2.8-hd", text: "这是一段使用自定义音色生成的语音。", voice_id: voiceId, response_format: "url" }) }); const task = await response.json(); console.log(task.task_id); ``` ## 11. Python 示例 ### 11.1 声音克隆 ```python import requests api_key = "YOUR_API_KEY" response = requests.post( "https://api.xxx.xx/v1/audio/voices/clone", headers={ "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", }, json={ "audio_url": "https://example.com/audio/reference-speaker.mp3", "text": "大家好，欢迎来到今天的课程。", "display_name": "python-clone-voice", "language": "Chinese (Mandarin)", "noise_reduction": True, "need_volume_normalization": True, }, timeout=180, ) data = response.json() print(data["voice_id"]) print(data.get("preview_audio_url")) ``` ### 11.2 查询音色列表 ```python import requests api_key = "YOUR_API_KEY" response = requests.get( "https://api.xxx.xx/v1/audio/voices", headers={"Authorization": f"Bearer {api_key}"}, params={"model": "minimax-speech-2.8-hd"}, timeout=30, ) voices = response.json()["data"] for voice in voices: print(voice["voice_id"], voice.get("display_name")) ``` ## 12. 常见错误 ### 12.1 缺少鉴权 ```json { "error": { "message": "API key required.", "type": "invalid_request_error", "code": "api_key_required" } } ``` 解决方法：检查请求头是否包含 `Authorization: Bearer YOUR_API_KEY`。 ### 12.2 声音克隆缺少 audio_url ```json { "error": { "message": "`audio_url` is required.", "type": "invalid_request_error", "code": "invalid_request_parameter" } } ``` 解决方法：传入可公网访问的参考音频 URL。 ### 12.3 声音设计缺少 prompt ```json { "error": { "message": "`prompt` is required.", "type": "invalid_request_error", "code": "invalid_request_parameter" } } ``` 解决方法：补充声音描述，例如性别、语言、场景、情绪、语速和质感。 ### 12.4 声音设计缺少 preview_text ```json { "error": { "message": "`preview_text` is required.", "type": "invalid_request_error", "code": "invalid_request_parameter" } } ``` 解决方法：传入用于生成预览音频的文本。 ### 12.5 voice_id 不可用 ```json { "error": { "message": "`voice_id` is not visible for the current client or is not compatible with this model", "type": "invalid_request_error", "code": "invalid_request_parameter" } } ``` 可能原因： - `voice_id` 拼写错误。 - 当前账号无权使用该私有音色。 - 该音色不兼容当前 TTS 模型。 - 音色已被禁用或不可用。 解决方法： 1. 先调用 `GET /v1/audio/voices?model=...` 查询可用音色。 2. 从返回结果中复制 `voice_id`。 3. 再将该 `voice_id` 用到 `/v1/audio/tasks`。 ## 13. 最佳实践 ### 13.1 什么时候用声音克隆 当你已经有参考音频，并且需要复刻某个真实声音时，使用声音克隆。 典型场景： - 已有主播录音。 - 已有讲师试听音频。 - 已有品牌代言人授权音频。 - 想让后续 TTS 尽量接近参考声音。 ### 13.2 什么时候用声音设计 当你没有参考音频，但能描述想要的声音时，使用声音设计。 典型场景： - 设计一个数字人声音。 - 为短视频账号生成品牌音色。 - 为游戏角色生成声音。 - 快速试出多种广告或客服音色。 ### 13.3 音色命名建议 建议给 `display_name` 使用稳定、可读、可搜索的名称。 示例： ```markdown brand-female-presenter course-teacher-male customer-service-clear game-guide-young english-commercial-premium ``` ### 13.4 保存 voice_id 创建成功后，请保存： - `voice_id` - `display_name` - `source_type` - `preview_audio_url` - `compatible_models` - `created_at` 其中最重要的是 `voice_id`。后续 TTS 调用只需要传 `voice_id`。 ### 13.5 生产环境调用建议 - 声音克隆和声音设计通常比普通 TTS 更慢，建议客户端设置较长超时时间。 - 不要在前端暴露 API Key。 - 建议由服务端调用 aijisu API。 - 对 `voice_id` 做业务侧保存，避免重复创建相同音色。 - 创建前确认音频和声音授权，避免克隆无授权声音。 --- # 数字人口播 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/avatar/digital-human Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/avatar/digital-human.md Description: 使用一张图片和音频或 UniAll 音色 ID 创建 Kling V3 数字人视频。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 ## 概览 可灵数字人统一使用稳定模型 `kling-v3`，并传入 `operation: avatar`。请求需要一张公开图片，以及音频 URL 或 UniAll `voice_id` 二选一；不要再使用历史 Kling Avatar 档位模型名。 UniAll 当前没有开放可灵主体库的创建和查询接口，因此普通公开请求不要传 `subject_ids`。 ## 适用场景 - 已有口播音频时使用 `audio_url`。 - 需要使用 UniAll 音色列表或克隆接口返回的音色时使用 `voice_id`。 - 标准清晰度使用 `resolution: std`，更高清晰度使用 `resolution: pro`。 ## 接口 | 操作 | 方法 | 路径 | | --- | --- | --- | | 创建数字人视频任务 | `POST` | `/v1/videos` | | 查询视频任务 | `GET` | `/v1/videos/{task_id}` | | 下载已完成的视频 | `GET` | `/v1/videos/{task_id}/content` | | 查询可灵音色 | `GET` | `/v1/audio/voices?model=kling-v3` | | 克隆可灵音色 | `POST` | `/v1/audio/voices/clone` | ## 鉴权 ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## 请求参数 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | 使用 `kling-v3`。 | | `operation` | string | 是 | 使用 `avatar`。 | | `prompt` | string | 是 | UniAll 视频接口要求提供的讲解、表情和镜头提示词。 | | `image` | string | 是 | 数字人图片的公开 HTTP(S) URL。 | | `audio_url` | string | 条件必填 | 公开口播音频 URL，与 `voice_id` 二选一。 | | `voice_id` | string | 条件必填 | UniAll 音色 ID，与 `audio_url` 二选一。 | | `resolution` | string | 否 | `std` 或 `pro`，默认 `std`。 | | `watermark` | boolean | 否 | 是否添加 AIGC 水印。 | 不要传 `sound` 开关。`audio_url` 和 `voice_id` 是口型驱动输入，展示风格由提示词描述；同一个请求不要同时传入两个音色输入。 ## 查询可用音色 ```bash curl "{BASE_URL}/v1/audio/voices?model=kling-v3" \ -H "Authorization: Bearer sk-***" ``` 使用音色列表响应中的 UniAll `voice_id`，不要传入上游音色 ID。 ## 克隆音色 ```bash curl -X POST "{BASE_URL}/v1/audio/voices/clone" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3", "voice_name": "产品旁白", "audio_url": "https://example.com/voice-sample.mp3", "text": "这是克隆音色的试听文本。" }' ``` 克隆成功后保存响应中的 UniAll `voice_id`，再用于数字人任务。 ## 请求示例 ### 使用音频 URL ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3", "operation": "avatar", "prompt": "自然讲解产品，表情友好，正面稳定镜头。", "image": "https://example.com/presenter.png", "audio_url": "https://example.com/speech.mp3", "resolution": "pro", "watermark": false }' ``` ### 使用 UniAll 音色 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3", "operation": "avatar", "prompt": "专业讲解口吻，表情自然，正面稳定镜头。", "image": "https://example.com/presenter.png", "voice_id": "voice_xxxxxxxxxxxxx", "resolution": "std" }' ``` ## 响应示例 ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "kling-v3", "status": "queued", "progress": 0 } ``` ## 任务状态与结果 保存 `id` 或 `task_id`，然后按照[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)中的公共规则，每 3 到 10 秒轮询一次，并处理终态、结果字段、错误和带鉴权下载。 ## 计费说明 数字人视频通常结合 `kling-v3`、`operation: avatar`、`resolution` 和输出时长计费。音色克隆可能按照模型广场当前规则单独计费。任务提交时可能预扣，最终以任务结算和消费记录为准。 ## 常见错误 - 使用历史数字人档位模型名，而不是 `kling-v3`。 - 缺少 `operation: avatar` 或必填的 `prompt`。 - 同时传入 `audio_url` 和 `voice_id`，或两者都没有传。 - 传入上游音色 ID，而不是 UniAll `voice_id`。 - 在公开主体库接口尚未开放时传入 `subject_ids`。 - 传入 `sound`、`duration`，或媒体 URL 无法由服务端公开访问。 - 一次轮询超时后重新提交付费任务，而不是继续查询原 `task_id`。 公共响应不会返回供应商名称、上游任务 ID、路由、凭证或上游原始请求。 ## 相关页面 - [Kling 视频](/zh-CN/models/video/kling) - [Kling 图片](/zh-CN/models/image/kling) - [视频生成概览](/zh-CN/models/video/overview) --- # 数字人概览 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/avatar/overview Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/avatar/overview.md Description: UniAll 数字人口播文档入口。 本分类整理来源菜单中的数字人口播流程，以及用户提供的 Kling V3 调用口径。 ## 包含页面 - [数字人口播](/zh-CN/models/avatar/digital-human) ## 接入建议 数字人口播使用 `kling-v3` 和 `operation: avatar`。提交一张数字人图片，并在音频 URL 和 UniAll `voice_id` 中二选一，随后轮询返回的 `task_id`，直到输出视频可用。 如果流程需要 `voice_id`，使用[数字人口播](/zh-CN/models/avatar/digital-human)页面中的可灵音色列表或克隆接口。 --- # 通用异步图像生成 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/image/async-image-generation Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/async-image-generation.md Description: 通用异步图像生成来源文档。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 更新时间：2026-04-29 本文说明如何使用图片异步任务接口调用 NanoBanana 系列模型和 `gpt-image-2`，包括请求方式、参数、响应、计费规则和两类模型的差异。 ## 1. 接口概览 ### 1.1 提交异步图片任务 ```http POST /v1/images/tasks ``` 支持： - 文生图：`task_type = text2image` - 图生图：`task_type = image2image` ### 1.2 查询异步图片任务 ```http GET /v1/images/tasks/{task_id} ``` ### 1.3 认证方式 ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## 2. 可用模型 ### 2.1 NanoBanana 系列 上游 Nano 系列模型包括： | 模型名 | 说明 | | --- | --- | | `NanoBanana` | NanoBanana 基础模型 | | `NanoBanana2-0.5K` | NanoBanana2，0.5K 档 | | `NanoBanana2-1K` | NanoBanana2，1K 档 | | `NanoBanana2-2K` | NanoBanana2，2K 档 | | `NanoBanana2-4K` | NanoBanana2，4K 档 | | `NanoBananaPro-1K` | NanoBanana Pro，1K 档 | | `NanoBananaPro-2K` | NanoBanana Pro，2K 档 | | `NanoBananaPro-4K` | NanoBanana Pro，4K 档 | | `NanoBananaPro-8K` | NanoBanana Pro，8K 档 | 注意：最终用户是否能调用某个模型，取决于平台后台是否已在通道和计费中启用该模型。 ### 2.2 gpt-image-2 | 模型名 | 说明 | | --- | --- | | `gpt-image-2` | 图片生成与编辑模型 | ## 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-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) | | `background` | string | 否 | 仅适用于 `gpt-image-2`；待上线。`auto`（模型根据提示词决定背景）、`opaque`（不透明背景）或 `transparent`（透明背景）。省略或传 `null` 时默认 `auto`。 | ### 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` 控制图片格式。 背景参数待上线。`background` 放在请求体顶层。 - `auto`：模型根据提示词决定背景；省略或传 `null` 时使用此默认值。 - `opaque`：指定不透明背景。 - `transparent`：指定透明背景；`output_format` 必须为 `png` 或 `webp`，未传时默认 `png`。 非法 `background` 值，或 `transparent` 与 `jpeg` 的组合，会在请求校验阶段返回 HTTP 400，不会开始生成。 ### 5.1 文生图 JSON 请求 ```json { "model": "gpt-image-2", "task_type": "text2image", "prompt": "An orange cat sticker, full subject visible, transparent background", "size": "1024x768", "quality": "low", "background": "transparent", "output_format": "webp", "n": 1, "response_format": "url" } ``` ### 5.2 图生图 JSON 请求 ```json { "model": "gpt-image-2", "task_type": "image2image", "prompt": "Keep the product shape and remove the background to make it transparent", "image": "https://example.com/input.png", "size": "1024x1024", "quality": "medium", "background": "transparent", "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 product shape and remove the background to make it transparent" \ -F "size=1024x1024" \ -F "quality=medium" \ -F "background=transparent" \ -F "output_format=png" \ -F "n=1" \ -F "response_format=url" \ -F "image=@/path/to/input.png" ``` ### 5.4 参数约束 | 参数 | 规则 | | --- | --- | | `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 `gpt-image-2` 使用 `size` 指定输出宽高，例如 `1024x1024`；无需传入 `aspect_ratio`。`quality` 控制质量，`n` 控制生成数量。 ## 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. 请求示例 ### 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": "An orange cat sticker, full subject visible, transparent background", "size": "1024x768", "quality": "low", "background": "transparent", "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` 已实测可用 | | 比例控制 | 支持 `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-options) | | `quality` | 不作为平台计费维度；通常由模型档位决定 | 可选，默认 `medium`，参与计费 | | `n` | 可选，默认 `1`，最大值以上游限制为准 | 可选，默认 `1`，范围 `1-8` | | `response_format` | 推荐 `url` | 推荐 `url` | | 图生图 | 单图用 `image`，多图用 `images`，传参考图即走图生图/编辑路径 | 单图用 `image`，多图用 `images`，传参考图即走图生图/编辑路径 | ## 10. 最小接入流程 1. 使用 `POST /v1/images/tasks` 提交任务。 2. 保存返回的 `task_id`。 3. 使用 `GET /v1/images/tasks/{task_id}` 轮询任务。 4. 当 `status = succeeded` 时读取 `result_url`。 --- # GPT-Image-2 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/image/gpt-image-2 Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/gpt-image-2.md Description: 通过 UniAll 图像 API 调用 gpt-image-2 生成或编辑图片。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 `gpt-image-2` 可通过 OpenAI 兼容图像接口进行文生图和图像编辑。该模型使用 `size` 同时控制尺寸和画幅比例，不支持 `aspect_ratio`。 ## Endpoint ```http POST /v1/images/generations POST /v1/images/edits ``` 文生图使用 `/v1/images/generations`。包含参考图的编辑请求使用 `/v1/images/edits`。 ## Authentication ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## 请求参数 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | 固定使用 `gpt-image-2`。 | | `prompt` | string | 是 | 图片生成或编辑提示词。 | | `image` | string/object | 条件必填 | 编辑图片时的参考图。 | | `images` | array | 条件必填 | 支持多图时使用的参考图数组。 | | `size` | string | 是 | 输出尺寸，例如 `1024x1024`。 | | `quality` | string | 否 | `low`、`medium` 或 `high`。默认 `medium`。 | | `output_format` | string | 否 | `png`、`jpeg` 或 `webp`。 | | `background` | string | 否 | `auto`（模型根据提示词决定背景）、`opaque`（不透明背景）或 `transparent`（透明背景）。省略或传 `null` 时默认 `auto`。 | | `n` | integer | 否 | 输出图片数量，默认 `1`，范围为 `1` 到 `8`。 | | `response_format` | string | 否 | 生成资产建议使用 `url`。 | ## 背景设置 背景参数待上线。`background` 放在请求体顶层。 - `auto`：模型根据提示词决定背景；省略或传 `null` 时使用此默认值。 - `opaque`：指定不透明背景。 - `transparent`：指定透明背景；`output_format` 必须为 `png` 或 `webp`，未传时默认 `png`。 非法 `background` 值，或 `transparent` 与 `jpeg` 的组合，会在请求校验阶段返回 HTTP 400，不会开始生成。 适用于本页的同步生成和编辑接口。 既有 GPT Image 2 异步图片任务和图片聊天兼容请求也使用同一顶层参数。图片结果仍返回 URL。 ## 文生图示例 ```bash curl -X POST "{BASE_URL}/v1/images/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "prompt": "An orange cat sticker, full subject visible, transparent background", "size": "1024x768", "quality": "low", "background": "transparent", "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 and remove the background to make it transparent", "image": "https://example.com/input.png", "size": "1024x1024", "quality": "medium", "background": "transparent", "output_format": "png", "n": 1, "response_format": "url" }' ``` ## 响应示例 ```json { "created": 1778688000, "data": [ { "url": "https://example.com/generated.png" } ] } ``` ## 常见错误 - 缺少 `size`。 - 传入 `aspect_ratio`；该模型应使用 `size`。 - `quality` 不在 `low`、`medium`、`high` 范围内。 - `n` 不在 `1` 到 `8` 范围内。 - 使用了当前账号不支持的尺寸。 ## 相关页面 - [图像生成概览](/zh-CN/models/image/overview) - [通用异步图像生成](/zh-CN/models/image/async-image-generation) - [Seedream 图像生成](/zh-CN/models/image/seedream) --- # GPT-Image-2.5 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/image/gpt-image-2-5 Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/gpt-image-2-5.md Description: 通过 UniAI 同步图像接口调用 GPT Image 2.5 生成和编辑图片。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 GPT Image 2.5 提供两个公开模型 ID： - `gpt-image-2.5-flare` - `gpt-image-2.5-sunburst` 两个模型使用相同的 OpenAI 兼容同步图像契约。文生图使用 `/v1/images/generations`；请求包含参考图时，使用 `/v1/images/edits`。 当前 API Key 可用的模型，以 `GET /v1/models` 返回的模型列表为准。 ## 适用场景 GPT Image 2.5 适合： - 同步文生图； - 使用一张或多张参考图进行图片编辑； - 调整输出尺寸、质量和格式； - 获取 URL 或 Base64 图片响应。 ## 接口 ```http GET /v1/models POST /v1/images/generations POST /v1/images/edits ``` 图片接口会等待上游结果，并在同一个响应中返回生成图片，不会创建需要轮询的任务。 ## 鉴权 ```http Authorization: Bearer sk-*** Content-Type: application/json ``` 也可以使用以下兼容 Header： ```http x-api-key: sk-*** ``` ## 模型可用性 ```bash curl "{BASE_URL}/v1/models" \ -H "Authorization: Bearer sk-***" ``` 成功响应会列出当前 API Key 可见的模型 ID： ```json { "object": "list", "data": [ { "id": "gpt-image-2.5-flare", "object": "model", "created": 0, "owned_by": "uniall" }, { "id": "gpt-image-2.5-sunburst", "object": "model", "created": 0, "owned_by": "uniall" } ] } ``` ## 请求参数 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | `gpt-image-2.5-flare` 或 `gpt-image-2.5-sunburst`。 | | `prompt` | string | 是 | 生成或编辑指令，最长 32,000 个字符。 | | `size` | string | 否 | `auto` 或 `WIDTHxHEIGHT`，默认 `auto`。 | | `quality` | string | 否 | `auto`、`low`、`medium`、`high`、`xhigh` 或 `max`，默认 `auto`。 | | `n` | integer | 否 | 输出图片数量，默认 `1`，范围为 `1` 到 `10`。 | | `output_format` | string | 否 | `png`、`jpeg` 或 `webp`，默认 `png`。 | | `background` | string | 否 | `auto`（模型根据提示词决定背景）、`opaque`（不透明背景）或 `transparent`（透明背景）。省略或传 `null` 时默认 `auto`。 | | `response_format` | string | 否 | `url` 或 `b64_json`，默认 `b64_json`。 | | `images` | array | 条件必填 | `/v1/images/edits` 的 JSON 参考图数组，每项使用 `{"image_url":"..."}`。 | | `mask` | object | 否 | `/v1/images/edits` 的 JSON 蒙版，使用 `{"image_url":"..."}`，作用于第一张参考图。 | ## 背景设置 背景参数待上线。`background` 放在请求体顶层。 - `auto`：模型根据提示词决定背景；省略或传 `null` 时使用此默认值。 - `opaque`：指定不透明背景。 - `transparent`：指定透明背景；`output_format` 必须为 `png` 或 `webp`，未传时默认 `png`。 非法 `background` 值，或 `transparent` 与 `jpeg` 的组合，会在请求校验阶段返回 HTTP 400，不会开始生成。 适用于本页的同步生成和编辑接口。 结果格式仍由 `response_format` 选择 `url` 或 `b64_json`，默认 `b64_json`。 ## 尺寸规则 显式传入 `WIDTHxHEIGHT` 时： - 宽和高必须是正整数，且都是 `16` 的倍数； - 长边不能超过 `3840` 像素； - 宽高比不能超过 `3:1`； - 总像素必须在 `655,360` 到 `8,294,400` 之间。 如果希望根据请求和参考图上下文自动选择尺寸，使用 `auto`。 ## 文生图示例 ```bash curl -X POST "{BASE_URL}/v1/images/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2.5-flare", "prompt": "An orange cat sticker, full subject visible, transparent background", "size": "1024x1024", "quality": "medium", "background": "transparent", "output_format": "png", "n": 1, "response_format": "url" }' ``` ## JSON 图片编辑示例 请求包含一张或多张参考图时，使用 `/v1/images/edits`。 ```bash curl -X POST "{BASE_URL}/v1/images/edits" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2.5-sunburst", "prompt": "Keep the product shape and remove the background to make it transparent", "images": [ {"image_url": "https://example.com/product.png"} ], "size": "auto", "quality": "high", "background": "transparent", "output_format": "png", "response_format": "url" }' ``` 每张 JSON 参考图使用 HTTP(S) 图片 URL，或 PNG、JPEG、WebP Base64 Data URL。单次请求最多可以传入 16 张参考图。 ## Base64 图片编辑示例 使用 JSON 编辑请求时，将参考图作为完整的 Base64 Data URL 传入 `images[].image_url`。 ```bash curl -X POST "{BASE_URL}/v1/images/edits" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2.5-sunburst", "prompt": "Keep the product shape and remove the background to make it transparent", "images": [ { "image_url": "data:image/png;base64,BASE64_IMAGE_DATA" } ], "size": "1024x1024", "quality": "high", "background": "transparent", "output_format": "png", "response_format": "url" }' ``` Data URL 必须包含 MIME 前缀，例如 `data:image/png;base64,...`、`data:image/jpeg;base64,...` 或 `data:image/webp;base64,...`。 ## multipart 图片编辑 本地文件建议使用 multipart。多张参考图可以重复传入 `image[]`。 ```bash curl -X POST "{BASE_URL}/v1/images/edits" \ -H "Authorization: Bearer sk-***" \ -F "model=gpt-image-2.5-sunburst" \ -F "prompt=Keep the product shape and remove the background to make it transparent" \ -F "background=transparent" \ -F "output_format=png" \ -F "image[]=@product.png" \ -F "response_format=url" ``` multipart 蒙版可以使用 `mask=@mask.png`。蒙版必须是带 Alpha 通道的 PNG，小于 4 MB，并且与第一张参考图尺寸一致。 ## 响应示例 ```json { "created": 1789121337, "size": "1024x1024", "output_format": "png", "data": [ { "url": "https://api.uniall.ai/generated-media/example.png" } ], "usage": { "prompt_tokens": 23, "completion_tokens": 425, "total_tokens": 448, "prompt_tokens_details": { "cached_tokens": 0, "text_tokens": 23, "image_tokens": 0 }, "completion_tokens_details": { "text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 0 }, "usage_source": "upstream_response" } } ``` 当 `response_format` 为 `b64_json` 时，每个 `data` 项返回 `b64_json` 而不是 `url`。该值是纯 Base64 内容，不包含 `data:image/...;base64,` 前缀。 ## Base64 响应示例 如果应用需要在 JSON 响应中直接获取图片字节，将 `response_format` 设置为 `b64_json`。 ```bash curl -X POST "{BASE_URL}/v1/images/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2.5-flare", "prompt": "An orange cat sticker, full subject visible, transparent background", "size": "1024x1024", "quality": "medium", "background": "transparent", "output_format": "png", "response_format": "b64_json" }' ``` 响应中的 `b64_json` 是纯 Base64 内容，不包含 `data:image/...;base64,` 前缀： ```json { "data": [ { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." } ] } ``` ## 相关页面 - [图像生成概览](/zh-CN/models/image/overview) - [GPT-Image-2](/zh-CN/models/image/gpt-image-2) - [模型列表](/zh-CN/models) --- # GPT-Image-2.6 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/image/gpt-image-2-6 Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/gpt-image-2-6.md Description: 使用 UniAI 同步 Images API 调用 GPT Image 2.6 Flare 和 Sunburst，完成生图、参考图编辑、蒙版编辑及 GIF 输出。 使用下列任一模型生成或编辑图片。结果在同一次响应中返回，无需轮询任务。 | 模型 ID | 适用场景 | | --- | --- | | `gpt-image-2.6-flare` | 交互创作与快速迭代。 | | `gpt-image-2.6-sunburst` | 精细构图与参考图编辑。 | ## 接口 使用 `https://api.uniall.ai`，通过 `Authorization: Bearer $UNIAI_API_KEY` 鉴权。请将示例中的 Key、参考图 URL 和本地文件路径替换为自己的值。 | 方法 | 路径 | 输入 | | --- | --- | --- | | POST | `/v1/images/generations` | JSON 文生图请求。 | | POST | `/v1/images/edits` | JSON 参考图或 multipart 图片文件。 | ## 参数 两个模型使用相同字段，JSON 参数放在顶层。`complexity` 控制规划计算量，与 `quality` 独立，可用于生图和编辑。 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | 上方两个精确模型 ID 之一。 | | `prompt` | string | 是 | 生图或编辑指令，最多 32,000 个字符。 | | `images` | object array | JSON 编辑时二选一 | 按顺序传入 1–16 个参考图对象，URL 放在 images[].image_url。 | | `image_urls` | string array | JSON 编辑时二选一 | 兼容写法，按顺序传入 1–16 个参考图 URL。 | | `mask` | object | 否 | 仅编辑，URL 放在 mask.image_url，作用于第一张参考图。 | | `markup` | object | 否 | 编辑标注层，URL 放在 markup.image_url；multipart 使用独立 markup 文件。 | | `size` | string | 否 | auto 或 WIDTHxHEIGHT，默认 auto。静态图和 GIF 限制见下方。 | | `quality` | string | 否 | auto、low、medium、high、xhigh、max；省略时使用默认质量。 | | `complexity` | string | 否 | low、medium、high，独立控制规划计算量。控制台默认选 high；API 可显式指定。 | | `n` | integer | 否 | 请求数量 1–10，默认 1。GIF 受总像素预算限制，建议为 1。 | | `output_format` | string | 否 | png（默认）、jpeg、webp、gif。编辑使用 PNG/JPEG/WebP；GIF 限制见下方。 | | `background` | string | 否 | auto、opaque、transparent。透明背景须使用 PNG 或 WebP。 | | `output_compression` | integer | 否 | 0–100，仅用于 JPEG/WebP；显式 0 会保留，省略时不设置默认值。 | | `frame_count` | integer | 否 | 仅 GIF，2–16；省略时按 9 帧计算请求像素预算。 | | `frame_duration_ms` | integer | 否 | 仅 GIF，20–2000 毫秒，默认 200；编码时按 10 毫秒取整。 | | `safety_identifier` | string | 否 | 终端用户标识散列，最多 128 个字符。 | | `prompt_rewriter` | JSON | 否 | 兼容 JSON，保留显式 0/false；结构及可用性依账户权限，未规定公共结构。 | | `response_format` | string | 否 | url 或 b64_json，建议显式指定返回方式。 | | `moderation` | string | 否 | auto 或 low。 | JSON 编辑选择 `images` 对象数组或 `image_urls` 字符串数组。`mask` 和 `markup` 使用包含 `image_url` 的对象，见下方示例。 静态图使用明确宽高时，两边均须为 16 的倍数，最长边不超过 3,840 像素，宽高比在 1:3–3:1 之间，总像素为 655,360–8,294,400。例如 `1024x1024`、`1024x1536`、`1536x1024`、`1536x864` 或 `2048x1152`。 参考图支持 PNG、JPEG、WebP，每张不超过 50 MiB。URL 须保持可访问，不依赖登录、Cookie 或自定义请求头。也可以使用完整图片 Data URL，例如 `data:image/png;base64,...`。 ## 生成图片 ```bash curl "https://api.uniall.ai/v1/images/generations" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2.6-flare", "prompt": "A sculptural burgundy glass perfume bottle on ivory travertine, warm side lighting, no lettering", "size": "1536x864", "quality": "high", "complexity": "high", "n": 1, "output_format": "png", "response_format": "url" }' ``` 需要透明背景时，设置 `background: "transparent"`，并使用 `output_format: "png"` 或 `"webp"`。 ## 参考图与蒙版编辑 JSON 参考图字符串放在 `image_urls`，蒙版 URL 使用 `mask.image_url`： ```bash curl "https://api.uniall.ai/v1/images/edits" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2.6-sunburst", "prompt": "Replace only the masked background with a warm cream studio backdrop; keep the product unchanged", "image_urls": ["https://images.example.com/product.png"], "mask": { "image_url": "https://images.example.com/mask.png" }, "size": "1024x1024", "quality": "high", "complexity": "high", "n": 1, "output_format": "png", "response_format": "url" }' ``` 蒙版为一张带 alpha 通道的 PNG，小于 4 MiB，尺寸须与第一张参考图一致。透明区域表示编辑范围。无需蒙版时省略 `mask`。 ### 编辑本地文件 ```bash curl "https://api.uniall.ai/v1/images/edits" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -F "model=gpt-image-2.6-sunburst" \ -F "prompt=Replace only the masked background with a warm cream studio backdrop; keep the product unchanged" \ -F "image[]=@product.png" \ -F "mask=@mask.png" \ -F "size=1024x1024" \ -F "quality=high" \ -F "complexity=high" \ -F "n=1" \ -F "output_format=png" \ -F "response_format=url" ``` 多图时重复 `image[]`，最多 16 张。让 cURL 自动设置 multipart Content-Type。 ### 标注编辑 将标注层与参考图分开传入： ```bash curl "https://api.uniall.ai/v1/images/edits" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2.6-sunburst", "prompt": "Change only the annotated bottle to blue and remove the annotation strokes", "images": [{"image_url": "https://images.example.com/product.png"}], "markup": {"image_url": "https://images.example.com/overlay.png"}, "complexity": "high", "quality": "high", "size": "1024x1024", "output_format": "png", "response_format": "url" }' ``` 标注层须为小于 50 MiB 的透明 PNG，与方向校正后的第一张参考图同尺寸。首图和标注层各不超过 16,777,216 像素。`markup` 不可与 `mask` 或 `prompt_rewriter` 组合。 本地文件使用： ```bash curl "https://api.uniall.ai/v1/images/edits" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -F "model=gpt-image-2.6-sunburst" \ -F "prompt=Change only the annotated bottle to blue and remove the annotation strokes" \ -F "image[]=@product.png" \ -F "markup=@overlay.png" \ -F "complexity=high" \ -F "quality=high" \ -F "size=1024x1024" \ -F "output_format=png" \ -F "response_format=url" ``` ## 生成 GIF 使用生成接口，设置 `output_format: "gif"`，在 `prompt` 中描述动作和循环效果，并指定帧数和帧时长： ```bash curl "https://api.uniall.ai/v1/images/generations" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2.6-flare", "prompt": "A silver tabby kitten dancing, alternating its front paws in a smooth seamless loop, fixed camera, cream background", "complexity": "medium", "quality": "high", "output_format": "gif", "size": "256x256", "n": 1, "frame_count": 12, "frame_duration_ms": 120, "response_format": "b64_json" }' ``` GIF 宽高须为 16 的倍数，每边不超过 3,840 像素，且 `宽 × 高 × frame_count × n ≤ 8,294,400`。GIF 单帧不受静态图最小像素数限制。GIF 不可搭配蒙版、标注层、压缩或提示词重写。这些参数用于请求控制，实际帧数、时长、尺寸和数量仍可能不同。 当前服务仅支持 GIF 生成，暂不支持 GIF 参考图编辑。响应可能额外包含 PNG 精灵图，请逐项检查 `data[]`。 ## 响应 设置 `response_format: "url"` 时，从 `data[].url` 读取结果。示例： ```json { "data": [ { "url": "https://images.example.com/result.png" } ] } ``` 设置 `response_format: "b64_json"` 时，将每个 `data[].b64_json` 解码为文件字节。该值不带 Data URL 前缀。以下内容已缩短： ```json { "data": [ { "b64_json": "R0lGODlh..." } ] } ``` 实际文件格式、尺寸、动画帧数、帧时长和结果数量可能与请求不同。响应中的可选 `output_format`、`size` 字段描述可识别的实际结果。请检查收到的文件，不要仅根据请求的扩展名或数量判断。结果保留原始 GIF 文件和实际 MIME 类型；不因格式、尺寸、帧数或数量与请求不同而拒绝结果，也不自动转换或追加生成以补齐 `n`。 请求失败或超时后不要自动重复提交；保留错误信息和请求 ID 用于排查。 仅支持同步 Images API，不支持 Responses 会话、File ID 服务或流式输出；`partial_images` 须省略或设为 `0`。 ## 相关页面 - [图像生成概览](/zh-CN/models/image/overview) - [GPT-Image-2.5](/zh-CN/models/image/gpt-image-2-5) - [模型列表](/zh-CN/models) --- # 编辑图像 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/image/gpt-image-2/openai-edit Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/gpt-image-2/openai-edit.md Description: GPT-Image-2 编辑图像接口。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 使用 `gpt-image-2` 编辑参考图片。接口同步返回图片 URL。 ## 接口参数与示例 ### Endpoint ```http POST /v1/images/edits/ ``` ### 请求体参数 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | 使用 `gpt-image-2`。 | | `prompt` | string | 是 | 图片编辑提示词。 | | `image` | string | 是 | 参考图片的 HTTP(S) URL。 | | `size` | string | 是 | 输出尺寸，例如 `1024x1024`。 | | `quality` | string | 否 | `low`、`medium` 或 `high`，默认 `medium`。 | | `output_format` | string | 否 | `png`、`jpeg` 或 `webp`。 | | `background` | string | 否 | 适用于 `gpt-image-2`。`auto`（模型根据提示词决定背景）、`opaque`（不透明背景）或 `transparent`（透明背景）。省略或传 `null` 时默认 `auto`。 | | `n` | integer | 否 | 默认 `1`，范围为 `1` 到 `8`。 | | `response_format` | string | 否 | 使用 `url` 获取图片 URL。 | ### 背景设置 背景参数待上线。`background` 放在请求体顶层。 - `auto`：模型根据提示词决定背景；省略或传 `null` 时使用此默认值。 - `opaque`：指定不透明背景。 - `transparent`：指定透明背景；`output_format` 必须为 `png` 或 `webp`，未传时默认 `png`。 非法 `background` 值，或 `transparent` 与 `jpeg` 的组合，会在请求校验阶段返回 HTTP 400，不会开始生成。 ### 请求示例 #### 透明背景 以下透明背景请求使用 `gpt-image-2`，结果返回图片 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 and remove the background to make it transparent", "image": "https://example.com/input.png", "size": "1024x1024", "quality": "medium", "background": "transparent", "output_format": "png", "n": 1, "response_format": "url" }' ``` ### 响应字段 | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | ### 响应示例 #### 示例 1 ```json { "created": 1777107492, "data": [ { "url": "https://xxxxx.com/xxxx.png" } ] } ``` --- # 生成图像 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/image/gpt-image-2/openai-generate Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/gpt-image-2/openai-generate.md Description: GPT-Image-2 生成图像接口。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 使用 `gpt-image-2` 生成图片。接口同步返回图片 URL。 ## 接口参数与示例 ### Endpoint ```http POST /v1/images/generations/ ``` ### 请求体参数 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | 固定使用 `gpt-image-2`。 | | `prompt` | string | 是 | 图片生成提示词。 | | `size` | string | 否 | 输出尺寸，例如 `1024x1024`；也可使用 `auto`。 | | `quality` | string | 否 | `low`、`medium` 或 `high`。 | | `output_format` | string | 否 | `png`、`jpeg` 或 `webp`，默认 `png`。 | | `background` | string | 否 | 适用于 `gpt-image-2`。`auto`（模型根据提示词决定背景）、`opaque`（不透明背景）或 `transparent`（透明背景）。省略或传 `null` 时默认 `auto`。 | | `n` | integer | 否 | 默认 `1`，范围为 `1` 到 `8`。 | | `response_format` | string | 否 | 使用 `url` 获取图片 URL。 | ### 背景设置 背景参数待上线。`background` 放在请求体顶层。 - `auto`：模型根据提示词决定背景；省略或传 `null` 时使用此默认值。 - `opaque`：指定不透明背景。 - `transparent`：指定透明背景；`output_format` 必须为 `png` 或 `webp`，未传时默认 `png`。 非法 `background` 值，或 `transparent` 与 `jpeg` 的组合，会在请求校验阶段返回 HTTP 400，不会开始生成。 ### 请求示例 #### 示例 ```json { "model": "gpt-image-2", "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", "prompt": "A cute baby sea otter", "size": "1024x1536", "quality": "medium", "output_format": "png" }' ``` #### 透明背景 以下透明背景请求使用 `gpt-image-2`，结果返回图片 URL。 ```bash curl -X POST "{BASE_URL}/v1/images/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "prompt": "An orange cat sticker, full subject visible, transparent background", "size": "1024x1024", "quality": "medium", "background": "transparent", "output_format": "png", "n": 1, "response_format": "url" }' ``` ### 响应字段 | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | | `created` | integer | Yes | | | | `data` | array | Yes | | | | `usage` | object | Yes | | | ### 响应示例 #### 成功示例 ```json { "created": 1777105463, "data": [ { "url": "https://xxxxxx/xxx.jpg" } ] } ``` --- # Kling Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/image/kling Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/kling.md Description: 通过 UniAll 异步图片任务调用可灵 V3、Omni 和 Image O1 生成及编辑图片。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 ## 概览 可灵图片能力统一使用 `POST /v1/images/tasks`。通过 `operation` 选择生成方式，通过请求体顶层的 `resolution` 选择清晰度，通过 `num_images` 选择输出数量。 | 模型 | 图片能力 | 清晰度 | | --- | --- | --- | | `kling-v3` | 文生图、单图编辑、扩图、主体图补全 | `1k`、`2k` | | `kling-v3-omni` | 文生图、单图编辑、多图参考、组图 | `1k`、`2k`、`4k` | | `kling-image-o1` | 文生图、单图编辑、多图参考、组图 | `1k`、`2k`、`4k` | 模型是否可用取决于模型广场、API Key 的模型权限和当前启用的路由。 ## 适用场景 - 文生图、单图编辑、扩图或根据一张正面图补全主体时使用 `kling-v3`。 - 需要最多四张参考图、`4k` 或组图结果时使用 `kling-v3-omni`。 - 需要相同的多图请求结构、且只使用图片模型时使用 `kling-image-o1`。 ## 接口 | 操作 | 方法 | 路径 | | --- | --- | --- | | 创建异步图片任务 | `POST` | `/v1/images/tasks` | | 查询图片任务 | `GET` | `/v1/images/tasks/{task_id}` | ## 鉴权 ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## 清晰度与比例 在请求体顶层传入 `resolution`，不要使用 `size` 代替。默认值为 `1k`；`outpaint` 和 `complete_subject` 不要传 `resolution`。 - V3 支持 `16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`3:2`、`2:3` 和 `21:9`。 - Omni 和 Image O1 除上述比例外还支持 `auto`。 ## 生成方式 | `operation` | 支持模型 | 必要输入 | | --- | --- | --- | | `text_to_image` | V3、Omni、Image O1 | 无输入图 | | `image_edit` | V3、Omni、Image O1 | 一张 `image` | | `reference_to_image` | Omni、Image O1 | `images` 传两到四张参考图 | | `outpaint` | V3 | 一张 `image` 和 `outpaint` | | `complete_subject` | V3 | 一张正面 `image` | `kling-v3` 不接受两张原始图片用于 `reference_to_image`。多图参考应使用 `kling-v3-omni` 或 `kling-image-o1`。 ## 请求参数 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | `kling-v3`、`kling-v3-omni` 或 `kling-image-o1`。 | | `task_type` | string | 是 | 文生图使用 `text2image`；其他图片 operation 使用 `image2image`。 | | `operation` | string | 是 | 上表中的生成方式。 | | `prompt` | string | 是 | UniAll 异步图片接口要求提供的提示词。 | | `image` | string | 条件必填 | 单图 operation 使用的一张公开图片 URL。 | | `images` | string[] | 条件必填 | 多图参考使用的两到四张公开图片 URL。 | | `resolution` | string | 否 | `1k`、`2k` 或模型支持的 `4k`；默认 `1k`。扩图和主体补全不要传。 | | `aspect_ratio` | string | 否 | 输出比例；支持的图片编辑请求可使用 `auto`。 | | `num_images` | integer | 否 | 输出数量，范围为 `1` 到 `9`。 | | `negative_prompt` | string | 否 | V3 文生图的反向提示词。 | | `result_type` | string | 否 | Omni 和 Image O1 可使用 `single` 或 `series`。 | | `outpaint` | object | 条件必填 | `outpaint` 使用的四方向扩展倍率。 | | `watermark` | boolean | 否 | 是否添加 AIGC 水印。 | ## 请求示例 ### V3 文生图 ```bash curl -X POST "{BASE_URL}/v1/images/tasks" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3", "task_type": "text2image", "operation": "text_to_image", "prompt": "电影感产品摄影，一只银色腕表放在黑色石材展台上。", "negative_prompt": "模糊，变形，文字，水印", "resolution": "2k", "aspect_ratio": "16:9", "num_images": 1, "watermark": false }' ``` ### V3 单图编辑 ```bash curl -X POST "{BASE_URL}/v1/images/tasks" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3", "task_type": "image2image", "operation": "image_edit", "prompt": "保持人物身份，把背景替换为干净的摄影棚。", "image": "https://example.com/person.png", "resolution": "2k", "aspect_ratio": "3:4", "num_images": 1 }' ``` ### Omni 多图参考 4K ```bash curl -X POST "{BASE_URL}/v1/images/tasks" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3-omni", "task_type": "image2image", "operation": "reference_to_image", "prompt": "以第一张图为主体，参考第二张图的服装和色彩，生成统一的电影感肖像。", "images": [ "https://example.com/person.png", "https://example.com/style.png" ], "resolution": "4k", "aspect_ratio": "16:9", "num_images": 1, "result_type": "single" }' ``` `kling-image-o1` 使用相同的多图参考结构，只需修改 `model`。 ### V3 扩图 ```bash curl -X POST "{BASE_URL}/v1/images/tasks" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3", "task_type": "image2image", "operation": "outpaint", "prompt": "自然延展海滩和天空，保持原图光线与透视。", "image": "https://example.com/source.png", "outpaint": { "up_expansion_ratio": 0.2, "down_expansion_ratio": 0, "left_expansion_ratio": 0.1, "right_expansion_ratio": 0.1 }, "num_images": 1, "watermark": false }' ``` 每个扩图倍率必须在 `0` 到 `2` 之间，至少一个方向大于 `0`，扩展后的总面积不能超过原图的三倍。扩图不要传 `resolution`。 ### V3 主体图补全 ```bash curl -X POST "{BASE_URL}/v1/images/tasks" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3", "task_type": "image2image", "operation": "complete_subject", "prompt": "补全人物主体图。", "image": "https://example.com/front.png" }' ``` 主体图补全只接受一张正面图，不传 `resolution`、`aspect_ratio` 或 `num_images`。`prompt` 用于满足 UniAll 图片任务的通用请求要求，不会代替图片输入。 ## 响应示例 ```json { "task_id": "task_xxxxxxxxxxxxx", "status": "queued", "progress": "0%", "result_url": "", "metadata": { "task_type": "image2image" }, "error": null } ``` ## 任务状态与结果 每 3 到 10 秒调用 `GET /v1/images/tasks/{task_id}`，直到任务进入 `succeeded` 或 `failed`。查询响应外层为 `code` 和 `data`；成功后读取 `data.result_url`，多图结果同时读取 `data.metadata.result_urls`。 不要因为一次查询超时就重新提交付费任务，应继续查询原 `task_id`。公共异步图片响应流程参见[通用异步图像生成](/zh-CN/models/image/async-image-generation)。 ## 计费说明 图片通常结合公共模型、`operation`、`resolution`、输入图片数和输出图片数计费。任务提交时可能预扣，最终以任务结算记录和模型广场当前价格为准。 ## 常见错误 - 使用 `size` 代替 `resolution`。 - 给 `kling-v3` 传入 `4k`。 - 使用 `kling-v3` 和两张原始图片调用 `reference_to_image`。 - 混用 `image`、`images` 和 `reference_image_urls`，重复提交同一输入。 - 给 `outpaint` 或 `complete_subject` 传入 `resolution`。 - 媒体 URL 无法由服务端公开访问。 - 查询超时后重新提交，而不是继续轮询原任务。 公共响应不会返回供应商名称、上游任务 ID、路由、凭证或上游原始请求。 ## 相关页面 - [Kling 视频](/zh-CN/models/video/kling) - [通用异步图像生成](/zh-CN/models/image/async-image-generation) - [数字人口播](/zh-CN/models/avatar/digital-human) --- # Nano 系列 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/image/nano-series Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/nano-series.md Description: 选择 Nano Banana 模型及 OpenAI 或 Gemini 图片接口，包含独立的 Nano Banana 2.1 使用指引。 Nano 系列支持文生图以及使用一张或多张参考图进行编辑。UniAll 使用同一 API Key 提供两种请求风格，请按现有客户端和结果格式选择其中一种。 ## 选择接口风格 | 使用场景 | 推荐文档 | 结果格式 | | --- | --- | --- | | Nano Banana 2.1，使用 OpenAI Images 字段和参考图 URL | [Nano Banana 2.1 — OpenAI Images](./nano-series/nano-banana-2-1/openai-format) | `data[].url` 中的 URL | | Nano Banana 2.1，使用 Gemini 字段和 Base64 参考图 | [Nano Banana 2.1 — Gemini generateContent](./nano-series/nano-banana-2-1/gemini-format) | `candidates[].content.parts[].inlineData.data` 中的 Base64 | | `nano-banana-2`、`nano-banana-pro` 或 `nano-banana-2-lite`，使用 OpenAI Images 或异步任务 | [OpenAI Images 格式](./nano-series/openai-format) | `data[].url` 中的 URL | | `nano-banana-2`、`nano-banana-pro` 或 `nano-banana-2-lite`，使用 Gemini | [Gemini generateContent 格式](./nano-series/gemini-format) | `candidates[].content.parts[].inlineData.data` 中的 Base64 | 两种方式都使用 `https://api.uniall.ai` 和同一份 UniAll API Key。不要混用两种格式的参数名。 ## 推荐模型 | 模型 | 可用分辨率 | 默认值 | 推荐场景 | | --- | --- | --- | --- | | `nano-banana-2.1` | `1k`、`2k`、`4k` | `1k` | 同步生成和编辑、最多 14 张参考图及思考档位控制。 | | `nano-banana-2` | `0.5k`、`1k`、`2k`、`4k` | `1k` | 通用生成、图片编辑和快速 0.5K 预览。 | | `nano-banana-pro` | `1k`、`2k`、`4k` | `1k` | 更高细节的生成与编辑。 | | `nano-banana-2-lite` | `1k` | `1k` | 轻量 1K 任务。 | 新接入请使用这些统一的小写模型 ID。实际可用范围取决于账号已启用的模型。 Nano Banana 2.1 的 Gemini URL 使用官方 ID `gemini-nano-banana-2.1`，也保留使用 `nano-banana-2.1` 的兼容 Gemini URL。OpenAI Images 示例使用 `model: "nano-banana-2.1"`。 ## Nano Banana 2.1 接入 两份 2.1 指引分别说明独立的请求格式： - OpenAI：文生图使用 `POST /v1/images/generations`，编辑使用 `POST /v1/images/edits`。鉴权为 `Authorization: Bearer `，`resolution`、`aspect_ratio` 和 `thinking_level` 放在顶层。 - Gemini：使用 `POST /v1beta/models/gemini-nano-banana-2.1:generateContent`，鉴权为 `x-goog-api-key: `，图片和思考参数分别放在 `generationConfig.imageConfig` 与 `generationConfig.thinkingConfig` 中。 两种风格均同步返回一张图片。2.1 不支持 `/v1/images/tasks` 或 `/v1/chat/completions`、0.5K/512/8K、搜索、自定义像素尺寸、遮罩、透明背景或流式输出。搜索字段即使为 `false` 也不要传入。 2.1 支持 14 种画幅： ```markdown 1:1 1:4 1:8 2:3 3:2 3:4 4:1 4:3 4:5 5:4 8:1 9:16 16:9 21:9 ``` 分辨率是档位，并非固定的长边像素；非方形 1K 图片可以是 `1376 × 768`。PNG/JPEG/WebP 参考图保留顺序及重复项，重复图计入 14 张限制。 思考档位在 OpenAI 中默认 `medium`，在 Gemini 中默认 `MEDIUM`，仅对 2.1 开放。不要给 `nano-banana-2`、`nano-banana-pro` 或固定分辨率兼容型号添加此参数。 ## 支持的输出比例 其它三个模型（`nano-banana-2`、`nano-banana-pro` 和 `nano-banana-2-lite`）支持： ```markdown 1:1 2:3 3:2 3:4 4:3 4:5 5:4 9:16 16:9 21:9 ``` 两种接口风格的分辨率字段不同： | 输出规格 | OpenAI Images | Gemini generateContent | | --- | --- | --- | | 0.5K | `resolution: "0.5k"` | `imageSize: "512"` | | 1K | `resolution: "1k"` | `imageSize: "1K"` | | 2K | `resolution: "2k"` | `imageSize: "2K"` | | 4K | `resolution: "4k"` | `imageSize: "4K"` | 0.5K 仅适用于 `nano-banana-2`。不要传 `512K`，Gemini 的 `imageSize` 也不要传 `0.5k`。 ## 旧版兼容模型名 `NanoBanana2-1K`、`NanoBananaPro-2K` 等固定分辨率模型名可能仍可兼容使用，但这些属于已弃用的兼容别名，可能随时移除。新接入应使用统一模型 ID，并在请求参数中选择分辨率。 ## 接入检查清单 - `n` 保持为 `1`，当前每次请求只生成一张图片。 - OpenAI 风格的参考图使用服务端可访问的 HTTP(S) URL 或完整 Data URL。 - Gemini 的 `inlineData.data` 只放纯 Base64，不要包含 `data:image/...;base64,` 前缀。 - 同步调用可按需把客户端超时设置到 600 秒。 - 客户端超时后不要立刻重复提交，原任务仍可能完成。 - 如需长期保留结果，请及时把临时结果 URL 转存到自己的存储。 - 日志中不要记录 API Key 或完整图片 Base64。 ## 相关页面 - [Nano Banana 2.1 — OpenAI Images](./nano-series/nano-banana-2-1/openai-format) - [Nano Banana 2.1 — Gemini generateContent](./nano-series/nano-banana-2-1/gemini-format) - [OpenAI Images 格式](./nano-series/openai-format) - [Gemini generateContent 格式](./nano-series/gemini-format) - [通用异步图像生成](/zh-CN/models/image/async-image-generation) --- # Gemini generateContent 格式 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/image/nano-series/gemini-format Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/nano-series/gemini-format.md Description: 使用 Gemini 兼容的 generateContent 接口生成和编辑 Nano 系列图片。 本页适用于 `nano-banana-2`、`nano-banana-pro` 和 `nano-banana-2-lite`。Nano Banana 2.1 请使用[独立的 Gemini generateContent 指引](/zh-CN/models/image/nano-series/nano-banana-2-1/gemini-format)；旧型号及分辨率后缀兼容型号未开放思考档位控制。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 已有 Gemini 风格客户端，或需要 Base64 图片输入与输出时使用此格式。模型名放在 URL 中，图片参数放在 `generationConfig.imageConfig` 中。 ## 接口 ```http POST /v1beta/models/{model}:generateContent ``` 将 `{model}` 替换为 `nano-banana-2`、`nano-banana-pro` 或 `nano-banana-2-lite`。 ## 鉴权 ```http x-api-key: sk-*** Content-Type: application/json ``` OpenAI Images 和 Gemini 两种格式使用同一份 UniAll API Key。 ## 参数说明 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `contents` | array | 是 | 包含一条用户消息的对话内容。 | | `contents[].role` | string | 是 | 使用 `user`。 | | `contents[].parts[].text` | string | 是 | 生成或编辑指令。 | | `contents[].parts[].inlineData` | object | 条件必填 | 编辑使用的参考图；多图时重复此 part。 | | `inlineData.mimeType` | string | 条件必填 | 图片媒体类型，例如 `image/png`。 | | `inlineData.data` | string | 条件必填 | 不带 Data URL 前缀的纯 Base64。 | | `generationConfig.responseModalities` | string[] | 是 | 同时接受文字和图片结果时使用 `["TEXT", "IMAGE"]`。 | | `generationConfig.imageConfig.imageSize` | string | 否 | `512`、`1K`、`2K` 或 `4K`，默认 `1K`；受模型限制。 | | `generationConfig.imageConfig.aspectRatio` | string | 否 | 输出比例，例如 `1:1`、`3:4` 或 `16:9`。 | | 模型 | 支持的 `imageSize` | | --- | --- | | `nano-banana-2` | `512`、`1K`、`2K`、`4K` | | `nano-banana-pro` | `1K`、`2K`、`4K` | | `nano-banana-2-lite` | `1K` | ## 请求示例 ## 文生图示例 ```bash curl -X POST "{BASE_URL}/v1beta/models/nano-banana-2:generateContent" \ -H "x-api-key: sk-***" \ -H "Content-Type: application/json" \ -d '{ "contents": [ { "role": "user", "parts": [ { "text": "电影感产品图：透明香水瓶放在黑色岩石上，蓝色薄雾，无文字" } ] } ], "generationConfig": { "responseModalities": ["TEXT", "IMAGE"], "imageConfig": { "imageSize": "512", "aspectRatio": "1:1" } } }' ``` ## 图片编辑示例 构造 JSON 请求前，先把图片编码为纯 Base64： ```bash IMAGE_BASE64="$(base64 < ./reference.png | tr -d '\n')" ``` ```json { "contents": [ { "role": "user", "parts": [ { "text": "保持人物和构图不变，把背景替换成雨夜霓虹街道" }, { "inlineData": { "mimeType": "image/png", "data": "BASE64_IMAGE_DATA" } } ] } ], "generationConfig": { "responseModalities": [ "TEXT", "IMAGE" ], "imageConfig": { "imageSize": "2K", "aspectRatio": "3:4" } } } ``` 每增加一张参考图，就增加一个 `inlineData` part，并保持图片顺序与提示词描述一致。 ## 响应示例 ```json { "candidates": [ { "content": { "role": "model", "parts": [ { "text": "图片已生成。" }, { "inlineData": { "mimeType": "image/png", "data": "iVBORw0KGgoAAAANSUhEUgAA..." } } ] }, "finishReason": "STOP" } ] } ``` 找到包含 `inlineData` 的 part，对其中的 `data` 进行 Base64 解码，并按返回的 `mimeType` 保存。部分客户端可能把字段名规范化为 `inline_data` 和 `mime_type`。 ## Python 示例 ```python import base64 import requests response = requests.post( "https://api.uniall.ai/v1beta/models/nano-banana-2:generateContent", headers={"x-api-key": "sk-***", "Content-Type": "application/json"}, json={ "contents": [{ "role": "user", "parts": [{"text": "一只戴宇航员头盔的橘猫"}], }], "generationConfig": { "responseModalities": ["TEXT", "IMAGE"], "imageConfig": {"imageSize": "512", "aspectRatio": "1:1"}, }, }, timeout=600, ) response.raise_for_status() for candidate in response.json().get("candidates", []): for part in candidate.get("content", {}).get("parts", []): image = part.get("inlineData") or part.get("inline_data") if image and image.get("data"): with open("generated.png", "wb") as output: output.write(base64.b64decode(image["data"])) raise SystemExit(0) raise RuntimeError("response did not contain an image") ``` ## 旧版兼容模型名 早期把固定分辨率写进模型名的 Gemini preview ID 可能仍可兼容使用，但已经弃用，并可能随时移除。新接入请在 URL 中使用统一 Nano 模型，并通过 `imageSize` 选择分辨率。 ## 计费说明 计费取决于模型和 `imageSize`，请以账号当前可见的模型价格为准。响应包含 Base64 图片数据，体积可能较大。 ## 常见错误 - 把 0.5K 写成 `imageSize: "0.5k"` 或 `"512K"`，正确值是 `"512"`。 - 为 `nano-banana-pro` 或 `nano-banana-2-lite` 请求 `512`。 - 在 `inlineData.data` 中包含 `data:image/png;base64,` 前缀。 - 只读取第一个响应 part，没有查找包含 `inlineData` 的 part。 - 在日志中记录完整 Base64 响应或 API Key。 ## 相关页面 - [Nano 系列](../nano-series) - [OpenAI Images 格式](./openai-format) --- # Nano Banana 2.1 — Gemini generateContent Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/image/nano-series/nano-banana-2-1/gemini-format Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/nano-series/nano-banana-2-1/gemini-format.md Description: 使用 Gemini 官方模型名调用 Nano Banana 2.1，通过内联 Base64 参考图生成或编辑图片并读取图片响应。 ## 概述 使用 `gemini-nano-banana-2.1` 通过 Gemini 请求格式进行文生图，或使用最多 14 张参考图编辑图片。每次同步请求返回一张图片，Base64 数据位于响应的 `inlineData` 部分。 ## 接口 ```http POST /v1beta/models/gemini-nano-banana-2.1:generateContent ``` 基础地址为 `https://api.uniall.ai`。主要示例使用 Google 官方模型 ID `gemini-nano-banana-2.1`；兼容地址 `/v1beta/models/nano-banana-2.1:generateContent` 也保留可用。 ## 鉴权 使用你的 UniAI 用户 API Key： ```http x-goog-api-key: Content-Type: application/json ``` ## 请求参数 `contents` 只传一条 `user` 内容，字段名使用 camelCase。 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `contents` | array | 是 | 只能包含一条 user 内容。 | | `contents[].role` | string | 是 | `user`。 | | `contents[].parts[].text` | string | 是 | 非空生成或编辑指令。 | | `contents[].parts[].inlineData` | object | 条件必填 | 编辑参考图，每张图片添加一个 part，最多 14 张。 | | `contents[].parts[].inlineData.mimeType` | string | 条件必填 | `image/png`、`image/jpeg` 或 `image/webp`。 | | `contents[].parts[].inlineData.data` | string | 条件必填 | 不带 Data URL 前缀的纯 Base64 图片数据。 | | `generationConfig.imageConfig.imageSize` | string | 否 | `1K`、`2K` 或 `4K`，默认 `1K`。 | | `generationConfig.imageConfig.aspectRatio` | string | 否 | 下方 14 种画幅之一；不传时按参考图或生成内容决定。 | | `generationConfig.thinkingConfig.thinkingLevel` | string | 否 | `MINIMAL`、`MEDIUM` 或 `HIGH`，默认 `MEDIUM`。 | | `generationConfig.responseModalities` | string[] | 否 | 默认 `["IMAGE"]`，也接受 `["TEXT", "IMAGE"]`。只有实际生成最终文字时才返回文字，不支持仅 `["TEXT"]`。 | | `generationConfig.candidateCount` | integer | 否 | 只能为 `1`，每次请求返回一张图片。 | ### 分辨率与参考图 支持的画幅： ```markdown 1:1 1:4 1:8 2:3 3:2 3:4 4:1 4:3 4:5 5:4 8:1 9:16 16:9 21:9 ``` 分辨率是档位，并非固定的长边像素。例如非方形 `1K` 结果可以是 `1376 × 768`。不支持 `0.5K`、`512` 和 `8K`。 编辑需要 1 至 14 张 PNG、JPEG 或 WebP 参考图，按指令描述的顺序放入 `parts`。保留输入顺序及重复项，重复图计入张数限制。`mimeType` 必须与图片实际格式一致，`data` 只放纯 Base64。 ## 请求示例 ### 文生图 ```bash curl -X POST "https://api.uniall.ai/v1beta/models/gemini-nano-banana-2.1:generateContent" \ -H "x-goog-api-key: " \ -H "Content-Type: application/json" \ -d '{ "contents": [ { "role": "user", "parts": [ {"text": "Create a spring latte poster with a cream background and clear typography"} ] } ], "generationConfig": { "responseModalities": ["IMAGE"], "imageConfig": {"imageSize": "2K", "aspectRatio": "16:9"}, "thinkingConfig": {"thinkingLevel": "HIGH"}, "candidateCount": 1 } }' ``` ### 图片编辑 发送前，将 `` 替换为参考图的纯 Base64 数据。 ```bash curl -X POST "https://api.uniall.ai/v1beta/models/gemini-nano-banana-2.1:generateContent" \ -H "x-goog-api-key: " \ -H "Content-Type: application/json" \ -d '{ "contents": [ { "role": "user", "parts": [ {"text": "Keep the cup shape and color; replace the background with a bright cafe"}, { "inlineData": { "mimeType": "image/png", "data": "" } } ] } ], "generationConfig": { "responseModalities": ["IMAGE"], "imageConfig": {"imageSize": "2K", "aspectRatio": "4:5"}, "thinkingConfig": {"thinkingLevel": "MEDIUM"}, "candidateCount": 1 } }' ``` 每增加一张参考图，添加一个 `inlineData` part。继续编辑时，可将上一次输出图片作为下一次独立请求的参考图。 ## 响应示例 ```json { "candidates": [ { "content": { "role": "model", "parts": [ { "inlineData": { "mimeType": "image/png", "data": "" } } ] }, "finishReason": "STOP" } ] } ``` | 响应字段 | 说明 | | --- | --- | | `candidates[].content.parts[].inlineData` | 最终图片。对 `data` 进行 Base64 解码，并按返回的 `mimeType` 保存。 | | `candidates[].content.parts[].text` | 请求 `["TEXT", "IMAGE"]` 且实际生成最终文字时，可能返回最终文字；不保证必有文字。 | | `usageMetadata` | 有真实用量元数据时可能返回；读取图片不应依赖此字段。 | 遍历响应部分并查找 `inlineData`，不要假定第一个 part 就是图片。此接口同步返回结果，没有任务 ID 或轮询步骤。客户端超时不能确认生成已停止，应避免自动重新提交请求。 ## 能力限制与常见错误 - 搜索尚未开放。不要传入 `tools`、`enable_web_search` 或 `enable_image_search`；即使搜索开关为 `false` 也会拒绝。 - 当前图片接入仅支持单条 user 内容及文字、图片参考，不开放多轮历史、思考签名或摘要、视频/PDF 输入、Files、Interactions 和 Batch API。 - 不支持 `quality`、自定义像素 `size` 或 `custom_size`、遮罩、透明背景、`seed` 或流式输出。 - Nano Banana 2.1 不支持 `/v1/chat/completions` 或 `/v1/images/tasks`。 - 编辑缺少参考图、参考图超过 14 张、在 `inlineData.data` 中包含 Data URL 前缀、不支持的分辨率、仅文字输出或 `candidateCount` 不为 `1`，均属于无效请求。 - 思考档位控制只对新接入的 2.1 开放；`nano-banana-2`、`nano-banana-pro` 和固定分辨率兼容型号未开放此能力。 ## 相关页面 - [Nano 系列](/zh-CN/models/image/nano-series) - [Nano Banana 2.1 — OpenAI Images](./openai-format) - [其它 Nano 型号的 Gemini generateContent 格式](/zh-CN/models/image/nano-series/gemini-format) --- # Nano Banana 2.1 — OpenAI Images Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/image/nano-series/nano-banana-2-1/openai-format Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/nano-series/nano-banana-2-1/openai-format.md Description: 使用 OpenAI 风格 JSON 请求调用 Nano Banana 2.1，控制分辨率和思考档位，生成或编辑图片并获取 URL。 ## 概述 使用 `nano-banana-2.1` 根据文字生成图片，或使用最多 14 张参考图进行编辑。每次同步请求返回一张图片 URL，适合 OpenAI Images 客户端以及通过 URL 提供参考图的集成。 ## 接口 | 流程 | 方法与路径 | 输入 | | --- | --- | --- | | 文生图 | `POST /v1/images/generations` | 非空 `prompt`。 | | 图片编辑 | `POST /v1/images/edits` | 非空 `prompt` 和至少一张参考图。 | 基础地址为 `https://api.uniall.ai`。Nano Banana 2.1 不支持 `/v1/chat/completions` 或 `/v1/images/tasks`。 ## 鉴权 使用你的 UniAI 用户 API Key： ```http Authorization: Bearer Content-Type: application/json ``` ## 请求参数 主要参数放在 JSON 请求体顶层。 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | `nano-banana-2.1`。 | | `prompt` | string | 是 | 非空生成或编辑指令。 | | `resolution` | string | 否 | `1k`、`2k` 或 `4k`，默认 `1k`；也接受大写值。 | | `aspect_ratio` | string | 否 | 下方 14 种画幅之一；不传时按参考图或生成内容决定。 | | `thinking_level` | string | 否 | `minimal`、`medium` 或 `high`，默认 `medium`。 | | `images` | string[] | 条件必填 | 编辑时推荐使用的参考图字段，接受 HTTP(S) URL 或完整图片 Data URL。 | | `image` / `image_url` | string | 条件必填 | 兼容参考图字段，接受 HTTP(S) URL 或完整图片 Data URL。 | | `image_urls` | string[] | 条件必填 | 兼容参考图数组，接受 HTTP(S) URL 或完整图片 Data URL。 | | `n` | integer | 否 | 只能为 `1`，每次请求返回一张图片。 | | `num_images` | integer | 否 | 兼容图片数量字段，只能为 `1`。 | | `response_format` | string | 否 | 兼容接受 `url` 或 `b64_json`；此入口统一返回 URL。 | | `output_format` | string | 否 | 兼容接受 `png` 或 `jpeg`；实际格式由结果决定，不保证转码。 | ### 分辨率与画幅 支持的画幅： ```markdown 1:1 1:4 1:8 2:3 3:2 3:4 4:1 4:3 4:5 5:4 8:1 9:16 16:9 21:9 ``` 分辨率是档位，并非固定的长边像素。例如非方形 `1k` 结果可以是 `1376 × 768`。不支持 `0.5K`、`512` 和 `8K`。 ### 参考图与兼容参数 编辑请求需要 1 至 14 张参考图，所有参考图字段合计最多 14 张。支持 PNG、JPEG 和 WebP，保留输入顺序及重复项，重复图也计入 14 张限制。参考图 URL 必须可由服务端直接访问。Data URL 需要完整的图片 MIME 类型和 Base64 前缀，例如 `data:image/png;base64,...`。 编辑使用 JSON 引用图片，不支持 multipart 文件上传。 `resolution`、`thinking_level`、`num_images`、`output_format` 和 `response_format` 也兼容放在 `extra_body` 中。顶层和 `extra_body` 同时出现同名字段时，值必须一致。下方示例使用顶层参数。 ## 请求示例 ### 文生图 ```bash curl -X POST "https://api.uniall.ai/v1/images/generations" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-2.1", "prompt": "Create a spring latte poster with a cream background and clear typography", "resolution": "2k", "aspect_ratio": "16:9", "thinking_level": "high", "n": 1 }' ``` ### 图片编辑 ```bash curl -X POST "https://api.uniall.ai/v1/images/edits" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-2.1", "prompt": "Keep the cup shape and color; replace the background with a bright cafe", "images": ["https://example.com/reference.png"], "resolution": "2k", "aspect_ratio": "4:5", "thinking_level": "medium", "n": 1 }' ``` 将示例 URL 替换为你的参考图地址，按指令描述的顺序向 `images` 添加参考图。 ## 响应示例 ```json { "created": 1791676800, "data": [ { "url": "https://example.com/generated.png" } ] } ``` 从完整响应中读取 `data[0].url`。即使传入 `response_format: "b64_json"`，此入口也返回 URL。下载后按文件实际内容判断图片格式。 此接口同步返回结果，没有任务 ID 或轮询步骤。客户端超时不能确认生成已停止，应避免自动重新提交请求。 ## 能力限制与常见错误 - 搜索尚未开放。不要传入 `tools`、`enable_web_search` 或 `enable_image_search`；即使搜索开关为 `false` 也会拒绝。 - 不支持 `quality`、通过 `size` 或 `custom_size` 自定义像素尺寸、遮罩、透明背景、`seed` 或流式输出。 - 编辑时缺少参考图、参考图超过 14 张、不支持的分辨率或画幅、图片数量不为 `1`，均属于无效请求。 - 此请求使用 OpenAI 参数名。Gemini 的 `contents` 和 `generationConfig` 请参阅 [Gemini 页面](./gemini-format)。 - `thinking_level` 只对新接入的 2.1 开放；`nano-banana-2`、`nano-banana-pro` 和固定分辨率兼容型号未开放此参数。 ## 相关页面 - [Nano 系列](/zh-CN/models/image/nano-series) - [Nano Banana 2.1 — Gemini generateContent](./gemini-format) - [其它 Nano 型号的 OpenAI Images 格式](/zh-CN/models/image/nano-series/openai-format) --- # OpenAI Images 格式 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/image/nano-series/openai-format Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/nano-series/openai-format.md Description: 使用同步 OpenAI Images 接口或 UniAll 异步任务生成和编辑 Nano 系列图片。 本页适用于 `nano-banana-2`、`nano-banana-pro` 和 `nano-banana-2-lite`。Nano Banana 2.1 请使用[独立的 OpenAI Images 指引](/zh-CN/models/image/nano-series/nano-banana-2-1/openai-format)；旧型号及分辨率后缀兼容型号未开放思考档位控制。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 已有 OpenAI Images 客户端或需要图片 URL 时使用此格式。文生图和图片编辑均提供同步接口；不适合保持长连接的客户端可使用 UniAll 异步任务。 ## 接口 | 流程 | 方法与路径 | 行为 | | --- | --- | --- | | 文生图 | `POST /v1/images/generations` | 等待生成并返回图片 URL。 | | 图片编辑 | `POST /v1/images/edits` | 等待生成并返回图片 URL。 | | 异步生成或编辑 | `POST /v1/images/tasks` | 立即返回任务 ID。 | | 查询异步任务 | `GET /v1/images/tasks/{task_id}` | 返回任务状态和结果。 | ## 鉴权 ```http Authorization: Bearer sk-*** Content-Type: application/json ``` 也支持 `x-api-key: sk-***`，但 OpenAI 风格客户端推荐使用 Bearer 鉴权。 ## 参数说明 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | `nano-banana-2`、`nano-banana-pro` 或 `nano-banana-2-lite`。 | | `prompt` | string | 是 | 生成或编辑指令。 | | `resolution` | string | 否 | `0.5k`、`1k`、`2k` 或 `4k`，默认 `1k`；受模型限制。 | | `aspect_ratio` | string | 否 | 输出比例，例如 `1:1`、`3:4` 或 `16:9`。 | | `images` | string[] | 条件必填 | 编辑使用的参考图 URL 或完整 Data URL。 | | `n` | integer | 否 | 保持为 `1`，当前每次请求生成一张图片。 | | `output_format` | string | 否 | 输出格式，例如 `png`。 | | `request_id` | string | 否 | 异步任务使用的非敏感业务关联 ID。 | 0.5K 仅适用于 `nano-banana-2`，必须写成 `resolution: "0.5k"`。 ## 请求示例 ## 同步文生图 ```bash curl -X POST "{BASE_URL}/v1/images/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-2", "prompt": "电影感产品图：透明香水瓶放在黑色岩石上，蓝色薄雾，无文字", "resolution": "0.5k", "aspect_ratio": "1:1", "n": 1, "output_format": "png" }' ``` ## 同步图片编辑 ```bash curl -X POST "{BASE_URL}/v1/images/edits" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-2", "prompt": "保持人物和构图不变，把背景替换成雨夜霓虹街道", "images": ["https://example.com/reference/person.png"], "resolution": "2k", "aspect_ratio": "3:4", "n": 1, "output_format": "png" }' ``` 参考图 URL 必须能被服务端直接访问。多张参考图按提示词描述顺序放入 `images`。 ## 响应示例 ```json { "created": 1787366400, "data": [ { "url": "https://media.example.com/generated/image.png", "width": 512, "height": 512 } ] } ``` 从 `data[0].url` 读取结果；如需长期保留，请及时转存。 ## 异步任务 生成和编辑共用 `POST /v1/images/tasks`。请求包含 `images` 时按编辑任务处理。 ```bash curl -X POST "{BASE_URL}/v1/images/tasks" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-2", "prompt": "电影感产品图：透明香水瓶放在黑色岩石上", "resolution": "0.5k", "aspect_ratio": "1:1", "n": 1, "output_format": "png", "request_id": "image-20260822-0001" }' ``` ```json { "id": "task_xxx", "task_id": "task_xxx", "object": "image.generation.job", "model": "nano-banana-2", "status": "PENDING", "progress": 0, "image_url": null } ``` 保存 `task_id`；不要因为任务仍为 `PENDING` 就重新创建。 ## 任务状态与结果 ```bash curl "{BASE_URL}/v1/images/tasks/task_xxx" \ -H "Authorization: Bearer sk-***" ``` 开始时每 2～3 秒查询一次，等待时间变长后降到每 5～10 秒一次。`?refresh=true` 仅用于确实需要立即刷新上游状态的场景，不要每次轮询都添加。 | 状态 | 含义 | 处理方式 | | --- | --- | --- | | `PENDING` | 等待处理 | 继续轮询。 | | `IN_PROGRESS` | 正在生成 | 继续轮询。 | | `COMPLETED` | 已完成 | 优先读取 `data[0].url`，再回退到 `image_url`。 | | `FAILED` | 生成失败 | 读取公开错误并停止。 | | `CANCELLED` | 已取消 | 停止轮询。 | ```json { "id": "task_xxx", "task_id": "task_xxx", "model": "nano-banana-2", "status": "COMPLETED", "progress": 100, "image_url": "https://media.example.com/generated/image.png", "data": [ { "url": "https://media.example.com/generated/image.png", "width": 512, "height": 512 } ], "error": null } ``` ## 旧版兼容模型名 `NanoBanana2-0.5K`、`NanoBananaPro-4K` 等固定分辨率别名可能仍可兼容使用，但已经弃用，并可能随时移除。新代码请使用统一模型 ID 加 `resolution`。 ## 计费说明 计费取决于所选模型和分辨率，请以账号当前可见价格为准。同步请求断开或客户端超时，不代表生成已经停止。 ## 常见错误 - 把 0.5K 写成 `resolution: "512"` 或 `"512K"`，正确值是 `"0.5k"`。 - 为 `nano-banana-pro` 或 `nano-banana-2-lite` 请求 0.5K。 - 参考图 URL 需要登录或临时 Cookie，导致服务端无法访问。 - 客户端超时后立即重试，产生重复生成。 - 根据错误消息文本分支，而不是 HTTP 状态码和结构化错误字段。 ## 相关页面 - [Nano 系列](../nano-series) - [Gemini generateContent 格式](./gemini-format) - [通用异步图像生成](/zh-CN/models/image/async-image-generation) --- # 图像生成概览 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/image/overview Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/overview.md Description: UniAll 图像生成 API 分类入口。 按模型选择生图和图片编辑接口。 ## 包含页面 - [通用异步图像生成](/zh-CN/models/image/async-image-generation) - [Seedream 图像生成](/zh-CN/models/image/seedream) - [Seedream 5.0 Pro 图像生成](/zh-CN/models/image/seedream-5-0-pro) - [GPT-Image-2 图像生成](/zh-CN/models/image/gpt-image-2) - [GPT-Image-2.5](/zh-CN/models/image/gpt-image-2-5) - [GPT-Image-2.6](/zh-CN/models/image/gpt-image-2-6) - [Qwen Image](/zh-CN/models/image/qwen-image) - [Nano 系列图像生成](/zh-CN/models/image/nano-series) - [Nano Banana 2.1 — OpenAI Images](/zh-CN/models/image/nano-series/nano-banana-2-1/openai-format) - [Nano Banana 2.1 — Gemini generateContent](/zh-CN/models/image/nano-series/nano-banana-2-1/gemini-format) - [Kling](/zh-CN/models/image/kling) ## 接入建议 如果所选模型使用轮询流程，先阅读通用异步图像生成页面。Kling 使用 `/v1/images/tasks`，通过 `operation` 选择文生图、编辑、多图参考、扩图或主体补全。调用 `seedream-5.0-pro` 时，文生图使用 `/v1/images/generations`，参考图请求使用 `/v1/images/edits`。 Nano Banana 2.1 使用同步接口，不使用异步任务：OpenAI 风格使用生成或编辑接口；Gemini 风格使用 `/v1beta/models/gemini-nano-banana-2.1:generateContent`。请按上方分页选择一种请求格式。 GPT Image 2.6 使用同步 Images API：文生图和 GIF 使用 `/v1/images/generations`，参考图编辑使用 `/v1/images/edits`。Flare 和 Sunburst 使用各自精确模型 ID，共用同一参数契约。 --- # Qwen Image Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/image/qwen-image Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/qwen-image.md Description: Qwen Image 3.0、2.1、2.0 的 OpenAI Images 和百炼原生同步生图、编辑调用文档。 支持 OpenAI Images 和百炼原生接口，均同步返回图片 URL，无需轮询任务。 ## 模型 | 模型 ID | 参考图上限 | | --- | --- | | `qwen-image-3.0-pro` | 3 张 | | `qwen-image-3.0` | 3 张 | | `qwen-image-2.1-pro` | 10 张 | | `qwen-image-2.1-turbo` | 10 张 | | `qwen-image-2.0-pro` | 3 张 | | `qwen-image-2.0` | 3 张 | ## 接口 服务地址为 `https://api.uniall.ai`，使用 `Authorization: Bearer $UNIAI_API_KEY` 认证。示例中的 Key 和参考图地址请替换为自己的值。 | 格式 | 方法 | 路径 | | --- | --- | --- | | OpenAI 生图 | POST | `/v1/images/generations` | | OpenAI 编辑（JSON 或 multipart） | POST | `/v1/images/edits` | | 百炼原生生图与编辑 | POST | `/api/v1/services/aigc/multimodal-generation/generation` | ## 参数 OpenAI JSON 将下列字段放在顶层。百炼原生格式中，`model` 放顶层，提示词和图片放在 `input.messages`，生成选项放在 `parameters`。 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | 上述六个模型 ID 之一。 | | `prompt` | string | 是 | 生图或编辑指令。原生格式使用 `input.messages[0].content` 中的一条 `text`。 | | `image` | string 或 array | 编辑时必填 | 按顺序传入参考图 URL 或图片 data URL。原生格式每张图使用一条 `image` 内容项。 | | `n` | integer | 否 | 输出图片数，1–6，默认 `1`。 | | `size` | string | 否 | `WIDTHxHEIGHT`、`WIDTH*HEIGHT` 或 `auto`，范围见下方限制。 | | `seed` | integer | 否 | 0–2147483647。 | | `negative_prompt` | string | 否 | 仅 3.0 和 2.0 系列支持。 | | `prompt_extend` | boolean | 否 | 是否扩写提示词。 | | `prompt_extend_mode` | string | 否 | `direct` 或 `agent`，仅 3.0 和 2.1 支持；`agent` 仅用于文生图。 | | `enable_thinking` | boolean | 否 | 仅 3.0 和 2.1 系列支持。 | | `watermark` | boolean | 否 | 是否添加水印。 | | `response_format` | string | 否 | 仅 OpenAI 格式使用，只支持 `url`。 | OpenAI 还支持 `n` 的别名 `num_images`，以及参考图字段 `image_url`、`image_urls`、`images`。参考图字段选用一种；同时传入 `n` 和 `num_images` 时必须一致。生成选项也可放在 `extra_body`，与顶层重复时值必须一致。 ## OpenAI Images {/* #openai-images */} ### 文生图 ```bash curl "https://api.uniall.ai/v1/images/generations" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen-image-3.0", "prompt": "A blue ceramic cup on a wooden table", "n": 1, "size": "1024x1024", "seed": 0, "prompt_extend": false, "enable_thinking": false, "watermark": false }' ``` ### 使用参考图 URL 编辑 ```bash curl "https://api.uniall.ai/v1/images/edits" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen-image-2.1-pro", "prompt": "Turn the cup blue and keep the rest unchanged", "image": ["https://images.example.com/reference.png"], "n": 1, "size": "1024x1024" }' ``` 同一 JSON 请求也可发送至 `/v1/images/generations`，包含 `image` 时执行编辑。参考图数组顺序保持不变。 ### 上传本地图片编辑 ```bash curl "https://api.uniall.ai/v1/images/edits" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -F "model=qwen-image-2.1-pro" \ -F "prompt=Turn the cup blue and keep the rest unchanged" \ -F "image[]=@reference.png" \ -F "n=1" \ -F "size=1024x1024" \ -F "seed=0" \ -F "enable_thinking=false" ``` 多张参考图可重复添加 `-F "image[]=@another.png"`。表单中的整数使用数字字符串，布尔值使用 `true` / `false`；multipart 的 Content-Type 由 cURL 自动设置。 ### 响应 生图和编辑返回相同结构，从 `data[].url` 获取图片地址。 ```json { "created": 1792627200, "data": [ { "url": "https://images.example.com/result.png" } ] } ``` ## 百炼原生接口 {/* #bailian-native */} 只传一条 `user` 消息，其中必须包含一条 `text`。编辑时添加 `image` 内容项，文生图时省略图片。 ### 文生图 ```bash curl "https://api.uniall.ai/api/v1/services/aigc/multimodal-generation/generation" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen-image-3.0", "input": { "messages": [{ "role": "user", "content": [{"text": "A blue ceramic cup on a wooden table"}] }] }, "parameters": { "n": 1, "size": "1024*1024", "seed": 0, "prompt_extend": false, "enable_thinking": false, "watermark": false } }' ``` ### 图片编辑 ```bash curl "https://api.uniall.ai/api/v1/services/aigc/multimodal-generation/generation" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen-image-2.1-pro", "input": { "messages": [{ "role": "user", "content": [ {"image": "https://images.example.com/reference.png"}, {"text": "Turn the cup blue and keep the rest unchanged"} ] }] }, "parameters": {"n": 1, "size": "1024*1024"} }' ``` ### 响应 从 `output.choices[].message.content[].image` 获取图片地址。 ```json { "output": { "choices": [ { "finish_reason": "stop", "message": { "role": "assistant", "content": [ { "image": "https://images.example.com/result.png" } ] } } ] }, "request_id": "req_example" } ``` ## 限制 - 输出总像素为 262,144–4,194,304（512²–2048²），宽高比为 1:8–8:1。这是面积限制，不是单边最多 2048 像素；`3840x2160` 等标准 4K 尺寸超出范围。 - 参考图每张不超过 10 MB，数量上限见模型表。 - 输出格式为 PNG。2.1 系列需要透明背景时，在提示词中描述。 - 不支持流式、蒙版编辑或 Base64 输出；不要传 `quality`、`output_format`、`operation`。 请求可能耗时数十秒。超时后先检查请求记录，再决定是否重发。图片 URL 可能过期，请及时保存结果。 ## 请求错误 HTTP 400 时检查必填字段、模型支持的选项、参考图数量和尺寸范围；HTTP 401 时检查 Bearer Key。`/v1/images/edits` 至少需要一张参考图。 --- # Seedream Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/image/seedream Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/seedream.md Description: Seedream 图像生成来源文档。 本文档面向 Seedream 系列图片生成模型，覆盖三个图片模型的接口、参数、限制、响应和示例。 ## 基本信息 ### 鉴权 所有 `/v1/*` 接口都需要 API Key： ```http Authorization: Bearer ``` ### 支持的模型 | Public model | 能力 | 计费口径 | |---|---|---:| | `seedream-4.0` | 文生图、图片编辑 | 按输出图片张数 | | `seedream-4.5` | 文生图、图片编辑 | 按输出图片张数 | | `seedream-5.0-lite` | 文生图、图片编辑 | 按输出图片张数 | 同一个模型名称同时支持文生图和图片编辑： | 请求形态 | 操作类型 | |---|---| | 不传参考图 | 文生图 | | 传 `image` / `image_url` / `image_urls` / `images` | 图片编辑 | > 计费建议：按实际输出图片张数计费。`custom_size`、横图、竖图、比例本身不改变计费。 ## 推荐入口 | 场景 | Endpoint | 等待结果 | 返回形态 | |---|---|---:|---| | 文生图，同步拿图 | `POST /v1/images/generations` | 是 | `data[].url` | | 图片编辑，同步拿图 | `POST /v1/images/edits` | 是 | `data[].url` | ## 参数总表 ### 支持参数 | 参数 | 类型 | 位置 | 必填 | 说明 | |---|---|---|---:|---| | `model` | string | body | 是 | `seedream-4.0`、`seedream-4.5`、`seedream-5.0-lite` | | `prompt` | string | body | 是 | 文生图或编辑提示词 | | `n` | integer | body | 否 | 输出图片数，`1` 到 `6`。OpenAI 兼容字段 | | `custom_size` | object | body | 否 | 自定义输出尺寸，例如 `{"width": 2048, "height": 2048}` | | `image` | string / array | body / form | 编辑必填之一 | 参考图 URL，可传单张或多张 | | `image_url` | string / object / array | body / form | 编辑必填之一 | 参考图 URL，兼容 `{ "url": "..." }` 写法 | | `image_urls` | array | body / form | 编辑必填之一 | 多参考图 URL | | `images` | array | body | 编辑必填之一 | 多参考图 URL，支持字符串或对象 | | `timeout_seconds` | integer | body | 否 | 同步接口等待超时时间 | ### `n` - 默认值：`1` - 最小值：`1` - 最大值：`6` 示例： ```json { "num_images": 3 } ``` 或： ```json { "n": 3 } ``` ## `custom_size` 尺寸规则 格式： ```json { "custom_size": { "width": 2048, "height": 2048 } } ``` 尺寸约束： | 模型 | 最小总像素 | 最大总像素 | 最大边长 | 是否要求 16 倍数 | |---|---:|---:|---:|---:| | `seedream-4.0` | `921600` | `16777216` | `4096` | 否 | | `seedream-4.5` | `3686400` | `16777216` | `4096` | 否 | | `seedream-5.0-lite` | `3686400` | `16777216` | `4096` | 否 | 常用安全尺寸： | 尺寸 | 比例 | `seedream-4.0` | `seedream-4.5` | `seedream-5.0-lite` | |---|---|---:|---:|---:| | `960x960` | `1:1` | 可用 | 不可用，低于最小像素 | 不可用，低于最小像素 | | `1280x720` | `16:9` | 可用 | 不可用，低于最小像素 | 不可用，低于最小像素 | | `720x1280` | `9:16` | 可用 | 不可用，低于最小像素 | 不可用，低于最小像素 | | `2048x2048` | `1:1` | 可用 | 可用 | 可用 | | `2560x1440` | `16:9` | 可用 | 可用 | 可用 | | `1440x2560` | `9:16` | 可用 | 可用 | 可用 | | `2304x1728` | `4:3` | 可用 | 可用 | 可用 | | `1728x2304` | `3:4` | 可用 | 可用 | 可用 | | `4096x4096` | `1:1` | 可用，最大像素 | 可用，最大像素 | 可用，最大像素 | ## 参考图输入 图片编辑模式只支持 URL 参考图。不支持上传本地文件。 可用写法： ```json { "image": "https://example.com/a.png" } ``` ```json { "image_url": "https://example.com/a.png" } ``` ```json { "image_url": { "url": "https://example.com/a.png" } } ``` ```json { "image_urls": [ "https://example.com/a.png", "https://example.com/b.png" ] } ``` ```json { "images": [ "https://example.com/a.png", { "url": "https://example.com/b.png" }, { "image_url": "https://example.com/c.png" } ] } ``` 编辑限制： | 限制 | 值 | |---|---:| | 单次输入参考图最多 | `10` 张 | | 单次输出图最多 | `6` 张 | | 输入图数 + 输出图数最多 | `15` 张 | 示例： | 输入参考图数量 | 最大 `num_images` | |---:|---:| | `1` | `6` | | `5` | `6` | | `9` | `6` | | `10` | `5` | ## 同步文生图 ### 最小请求 ```bash curl -X POST "$BASE_URL/v1/images/generations" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "seedream-4.0", "prompt": "一张干净的高端耳机产品图，白色摄影棚背景，柔和阴影" }' ``` 响应： ```json { "created": 1778688000, "data": [ { "url": "https://example.com/generated-1.png" } ] } ``` ### 一次生成 6 张 ```bash curl -X POST "$BASE_URL/v1/images/generations" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "seedream-4.5", "prompt": "高端护肤品广告图，玻璃瓶，水滴质感，真实商业摄影", "num_images": 6, "custom_size": { "width": 2048, "height": 2048 } }' ``` ### 16:9 横图 `seedream-4.5` 和 `seedream-5.0-lite` 的最小像素更高，建议用 `2560x1440` 起步： ```bash curl -X POST "$BASE_URL/v1/images/generations" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "seedream-5.0-lite", "prompt": "16:9 电影感城市夜景，霓虹灯，雨后街道，超写实", "n": 2, "custom_size": { "width": 2560, "height": 1440 } }' ``` ### 9:16 竖图 ```bash curl -X POST "$BASE_URL/v1/images/generations" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "seedream-4.5", "prompt": "竖版手机壁纸，未来主义跑车，夜晚街景，强烈光影", "num_images": 1, "custom_size": { "width": 1440, "height": 2560 } }' ``` ### `seedream-4.0` 小尺寸示例 `1280x720` 只适合 `seedream-4.0`，不适合 `seedream-4.5` 和 `seedream-5.0-lite`。 ```bash curl -X POST "$BASE_URL/v1/images/generations" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "seedream-4.0", "prompt": "横版社交媒体封面，蓝天草地，清爽插画风", "custom_size": { "width": 1280, "height": 720 } }' ``` ## 同步图片编辑 ### JSON 单参考图 ```bash curl -X POST "$BASE_URL/v1/images/edits" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "seedream-4.0", "prompt": "把图片改成电影海报风格，增强光影，保留主体人物", "image": "https://example.com/source.png", "num_images": 1, "custom_size": { "width": 2048, "height": 2048 } }' ``` ### JSON 多参考图 ```bash curl -X POST "$BASE_URL/v1/images/edits" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "seedream-4.5", "prompt": "将两张参考图融合成同一套品牌广告视觉，保持产品一致性", "image_urls": [ "https://example.com/product.png", "https://example.com/background.png" ], "n": 3, "custom_size": { "width": 2560, "height": 1440 } }' ``` ### `images` 数组对象写法 ```bash curl -X POST "$BASE_URL/v1/images/edits" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "seedream-5.0-lite", "prompt": "参考第一张的人物和第二张的服装，生成一张统一风格的商业大片", "images": [ { "url": "https://example.com/person.png" }, { "image_url": "https://example.com/outfit.png" } ], "num_images": 2, "custom_size": { "width": 2048, "height": 2048 } }' ``` --- # Seedream 5.0 Pro Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/image/seedream-5-0-pro Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/image/seedream-5-0-pro.md Description: 通过 UniAll.ai 同步图片接口调用 seedream-5.0-pro 生成或编辑图片。 使用 `seedream-5.0-pro` 时，文生图和图片编辑分别调用对应的同步接口。文生图使用 `/v1/images/generations` 且不传 `image`；图生图或图片编辑使用 `/v1/images/edits`，并传入 1 至 10 张参考图。 本文档对应 2026 年 7 月 25 日更新的公开调用契约。 ## 概览 - 两个接口都在同一个 HTTP 响应中返回最终图片，不需要创建或轮询异步任务。 - 每次请求固定生成一张图片。 - 可以使用 `1K` 或 `2K` 分辨率档位并指定画幅比例，也可以直接传入精确尺寸。 - 参考图支持公网 URL 和 Base64 Data URL。 - 响应可以返回临时图片 URL 或纯 Base64 数据。 ## 接口与鉴权 ```http POST https://api.uniall.ai/v1/images/generations POST https://api.uniall.ai/v1/images/edits Authorization: Bearer sk-*** Content-Type: application/json ``` - 文生图：调用 `/v1/images/generations`，不传 `image`。 - 图生图或图片编辑：调用 `/v1/images/edits`，并传入 `image`。 Base URL 为： ```uri https://api.uniall.ai ``` 如果 UniAll.ai 控制台为当前账号提供了专属 API 地址，请以控制台显示的地址为准。 ## 快速开始 ### 文生图 ```bash curl -X POST "https://api.uniall.ai/v1/images/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedream-5.0-pro", "prompt": "高端护肤品广告图，玻璃瓶放在浅色石材台面上，柔和自然光，中文品牌文字清晰", "size": "2K", "aspect_ratio": "16:9", "output_format": "jpeg", "response_format": "url" }' ``` ### 图生图 ```bash curl -X POST "https://api.uniall.ai/v1/images/edits" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedream-5.0-pro", "prompt": "保留产品外形和标签文字，把背景替换成明亮的摄影棚场景", "image": "https://example.com/source-product.png", "size": "1K", "aspect_ratio": "1:1", "output_format": "png", "response_format": "url" }' ``` ### 精确尺寸 需要固定宽高时，直接把精确尺寸传给 `size`。同一个请求中不要再传 `aspect_ratio`。 ```bash curl -X POST "https://api.uniall.ai/v1/images/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedream-5.0-pro", "prompt": "宽幅科技产品发布会主视觉，主体位于画面中央，背景简洁", "size": "2048x1024", "output_format": "jpeg", "response_format": "url" }' ``` ## 请求参数 | 参数 | 类型 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | `model` | string | 是 | 无 | 固定为 `seedream-5.0-pro`。 | | `prompt` | string | 是 | 无 | 图片生成或编辑提示词。 | | `image` | string / string[] | 图生图必填 | 无 | `/v1/images/edits` 的参考图，支持公网 URL 或 Base64 Data URL，最多 10 张。 | | `size` | string | 否 | `2K` | `1K`、`2K` 或精确尺寸 `WIDTHxHEIGHT`。 | | `aspect_ratio` | string | 否 | 由模型判断 | 使用 `1K`、`2K` 时可指定画幅比例；精确尺寸模式不能传。 | | `output_format` | string | 否 | `jpeg` | `jpeg` 或 `png`。 | | `response_format` | string | 否 | `url` | `url` 或 `b64_json`。 | | `watermark` | boolean | 否 | `true` | 是否添加“AI 生成”水印。 | 该模型每次固定生成一张图片。 ## 尺寸与画幅比例 尺寸有以下两种用法，选择其中一种。 ### 分辨率档位与画幅比例 ```json { "size": "2K", "aspect_ratio": "16:9" } ``` `size` 支持 `1K` 和 `2K`。`aspect_ratio` 支持 `1:1`、`4:3`、`3:4`、`16:9`、`9:16`、`3:2`、`2:3` 和 `21:9`。 常见输出尺寸如下。最终尺寸以响应中的 `data[0].size` 为准。 | 分辨率 | `1:1` | `4:3` | `3:4` | `16:9` | `9:16` | `3:2` | `2:3` | `21:9` | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `1K` | `1024x1024` | `1152x864` | `864x1152` | `1424x800` | `800x1424` | `1248x832` | `832x1248` | `1568x672` | | `2K` | `2048x2048` | `2368x1776` | `1776x2368` | `2816x1584` | `1584x2816` | `2496x1664` | `1664x2496` | `3136x1344` | 不传 `aspect_ratio` 时，模型会根据提示词和参考图判断画幅。 ### 精确尺寸 ```json { "size": "2048x1024" } ``` 精确尺寸必须同时满足以下条件： - `width * height` 必须在 `921600` 到 `4624220` 之间，包含边界值。 - 宽高比必须在 `1/16` 到 `16` 之间，包含边界值。 - 没有单独的 4096 最大边限制，例如 `4200x1000` 是合法尺寸。 - 不能同时传 `aspect_ratio`，因为精确尺寸已经确定画幅。 ## 参考图输入 图生图和图片编辑统一调用 `/v1/images/edits`。 单张参考图传字符串，多张参考图传数组： ```json { "image": [ "https://example.com/product.png", "data:image/png;base64,..." ] } ``` 同一个请求中可以混合使用公网 URL 和 Base64 Data URL。 ### 公网 URL - 图片必须能被公网直接访问。 - 访问图片不能依赖 Cookie、登录状态或额外请求头。 ### Base64 Data URL 必须使用完整的 Data URL 格式： ```uri data:image/png;base64,... ``` - 图片格式名必须小写，但不要求 Base64 内容本身小写。 - 支持 JPEG、PNG、WEBP、BMP、TIFF、GIF、HEIC 和 HEIF。 - 每张 Data URL 图片最大 `30 MB`。 - 单次请求的参考图总数不能超过 10 张。 ## 响应格式 输入形式和输出形式相互独立。URL 输入可以返回 Base64，Base64 输入也可以返回 URL。 ### URL 响应 请求参数： ```json { "response_format": "url" } ``` 响应示例： ```json { "created": 1784900000, "data": [ { "url": "https://example.com/generated.jpeg", "size": "2816x1584", "output_format": "jpeg" } ], "usage": { "generated_images": 1, "input_images": 0, "output_tokens": 17424, "total_tokens": 17424 } } ``` 返回的 URL 可能在生成后 24 小时失效，请及时下载并保存图片。 ### Base64 响应 请求参数： ```json { "response_format": "b64_json" } ``` 图片项会返回 `b64_json`，不再返回 `url`： ```json { "data": [ { "b64_json": "...", "size": "2048x1024", "output_format": "png" } ] } ``` `b64_json` 是纯 Base64 内容，不包含 Data URL 前缀。 ### 响应字段 | 字段 | 类型 | 说明 | | --- | --- | --- | | `created` | integer | 响应的 Unix 时间戳。 | | `data` | array | 生成结果数组，固定包含一个图片项。 | | `data[].url` | string | `response_format` 为 `url` 时返回的临时图片地址。 | | `data[].b64_json` | string | `response_format` 为 `b64_json` 时返回的纯 Base64 图片数据。 | | `data[].size` | string | 最终输出尺寸，格式为 `WIDTHxHEIGHT`。 | | `data[].output_format` | string | 最终图片格式。 | | `usage.generated_images` | integer | 生成图片数量。 | | `usage.input_images` | integer | 输入参考图数量。 | | `usage.output_tokens` | integer | API 返回的输出用量。 | | `usage.total_tokens` | integer | API 返回的总用量。 | ## 提示词定位与标注 点位、区域、文字替换、箭头、涂鸦和标注框都通过输入图与 `prompt` 表达，不需要增加请求参数。 ```markdown 把 100 200 800 900 内的招牌替换为“新品上市” 在 520 380 附近增加一个小型台灯 ``` 坐标范围为 `0..999`。也可以直接在输入图中绘制箭头、标注框或其他标记，再通过提示词说明编辑意图。 ## 计费说明 - 每次请求固定输出一张图片。 - 输入图片张数可能参与计费，具体以当前 UniAll.ai 模型页为准。 - 输出图片按实际像素分档：不超过 `2360000` 像素，或超过 `2360000` 像素。 - `1K`、`2K` 不是直接计费条件，最终根据生成图片的 `width * height` 判断档位。 - 具体单价、分组倍率和最终扣费以 UniAll.ai 模型页及消费日志为准。 ## 常见问题 | 问题 | 常见原因 | 处理方式 | | --- | --- | --- | | 传入参考图后没有按编辑请求处理 | 请求发送到了 `/v1/images/generations`。 | 所有包含 `image` 的请求都改用 `/v1/images/edits`。 | | 精确尺寸被拒绝 | 同时传了 `aspect_ratio`，或像素数、宽高比超出限制。 | 删除 `aspect_ratio`，并重新检查精确尺寸约束。 | | 参考图被拒绝 | 超过 10 张、URL 无法公网直连，或 Data URL 格式不完整。 | 减少图片数量，并检查公网访问或完整 Data URL 格式。 | | 图片格式被拒绝 | 使用了不支持的格式，或 Data URL 中的图片格式名不是小写。 | 改用支持的格式，并使用 `image/png` 等小写格式名。 | | 响应中找不到预期字段 | 请求 `b64_json` 后仍读取 `url`，或反之。 | 根据 `response_format` 读取对应字段。 | | 客户端在返回图片前超时 | 同步生成所需时间超过客户端 HTTP 超时。 | 增加客户端超时时间，继续等待原请求，不要轮询异步任务接口。 | ## 相关页面 - [Seedream 图像生成](/zh-CN/models/image/seedream) - [图像生成概览](/zh-CN/models/image/overview) - [模型列表](/zh-CN/models) --- # Gemini Omni Flash Preview Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/gemini-omni-flash-preview Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/gemini-omni-flash-preview.md Description: 通过 UniAll.ai Gemini Interactions API 调用 gemini-omni-flash-preview 生成视频。 本文档介绍如何通过 UniAll.ai API 调用 `gemini-omni-flash-preview` 生成视频。 示例使用以下地址： ```uri https://api.uniall.ai ``` 如果 UniAll.ai 控制台提供了专属 API 地址，请使用控制台显示的地址。 ## 1. 快速开始 生成接口： ```http POST /v1beta/interactions ``` 鉴权方式： ```http Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` 最小文生视频请求： ```bash curl -X POST "https://api.uniall.ai/v1beta/interactions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-omni-flash-preview", "input": "A cinematic robot walking through rain at night.", "response_format": { "type": "video", "aspect_ratio": "16:9" }, "generation_config": { "video_config": { "task": "text_to_video", "resolution": "720p", "duration_seconds": 4 } } }' ``` ## 2. 支持能力 | 能力 | `task` | 输入要求 | |---|---|---| | 文生视频 | `text_to_video` | 提示词，不携带图片或视频 | | 图生视频 | `image_to_video` | 提示词 + 1 张图片 | | 多参考生成 | `reference_to_video` | 提示词 + 图片、视频，或图片与视频的组合 | 当前不支持： - 音频参考素材； - 首帧与尾帧插值； - 基于历史 `interaction_id` 的续作或编辑； - 视频延长； - Base64、`inline_data` 或 multipart 文件上传； - 自定义分辨率、宽度或高度。 ## 3. 请求参数 ### 3.1 顶层参数 | 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | `model` | string | 是 | 固定为 `gemini-omni-flash-preview` | | `input` | string / object / array | 是 | 提示词及可选的图片、视频 URL | | `response_format` | object | 是 | 输出类型和画面比例 | | `generation_config` | object | 建议 | 视频生成参数；建议始终显式传入 | | `timeout_seconds` | integer | 否 | 服务端等待结果的最长秒数，默认 `300`；它不是视频时长 | `POST /v1beta/interactions` 会等待视频生成完成后返回结果。调用方的 HTTP 客户端超时时间应大于 `timeout_seconds`，视频参考任务建议设置为 `600` 秒或更长。 ### 3.2 `response_format` | 参数 | 类型 | 必填 | 支持值 | 默认值 | |---|---|---|---|---| | `type` | string | 是 | `video` | 无 | | `aspect_ratio` | string | 否 | `16:9`、`9:16` | `16:9` | - `16:9`：横屏视频； - `9:16`：竖屏视频。 ### 3.3 `generation_config.video_config` | 参数 | 类型 | 必填 | 支持值 | 说明 | |---|---|---|---|---| | `task` | string | 建议 | `text_to_video`、`image_to_video`、`reference_to_video` | 建议显式填写，避免输入意图不明确 | | `resolution` | string | 否 | `720p` | 当前唯一支持的分辨率，默认 `720p` | | `duration_seconds` | integer | 否 | `4`、`6`、`8`、`10` | 期望视频时长，默认 `4` | 当请求包含视频参考时，模型会结合参考视频自行决定最终输出时长， `duration_seconds` 不保证与成品视频时长完全一致。需要精确时长时， 请以返回视频文件的实际时长为准。 ### 3.4 `task` 与素材组合 | `task` | 图片 | 视频 | 允许的组合 | |---|---:|---:|---| | `text_to_video` | 0 | 0 | 仅提示词 | | `image_to_video` | 1 | 0 | 恰好 1 张图片 | | `reference_to_video` | 0–7 | 0–1 | 图片、多图、单视频或图片 + 单视频；至少包含一种素材 | 如果省略 `task`，系统会根据素材自动判断： - 没有图片和视频：`text_to_video`； - 恰好 1 张图片：`image_to_video`； - 多张图片或包含视频：`reference_to_video`。 为保证调用结果稳定，生产环境建议始终显式传入 `task`。 ## 4. `input` 写法 ### 4.1 纯文本 文生视频可以直接传入字符串： ```json { "input": "A paper boat sailing through a neon city during heavy rain." } ``` ### 4.2 数组写法 数组写法表达最清晰，推荐用于所有带素材的请求： ```json { "input": [ { "type": "text", "text": "Animate the subject with a slow cinematic camera push-in." }, { "type": "image", "url": "https://example.com/subject.webp" }, { "type": "video", "url": "https://example.com/motion-reference.mp4" } ] } ``` 数组元素： | `type` | 参数 | 说明 | |---|---|---| | `text` | `text` | 文本提示词 | | `image` | `url` | 可公开访问的图片 URL | | `video` | `url` | 可公开访问的视频 URL | ### 4.3 对象简写 也可以使用对象及 URL 数组： ```json { "input": { "text": "Use the references to create one cohesive cinematic shot.", "image_urls": [ "https://example.com/character.png", "https://example.com/environment.jpg" ], "video_urls": [ "https://example.com/camera-motion.mp4" ] } } ``` 支持的对象字段： | 参数 | 类型 | 说明 | |---|---|---| | `text` | string | 提示词 | | `image_url` | string | 单张图片 URL | | `image_urls` | string[] | 多张图片 URL | | `video_url` | string | 单个视频 URL | | `video_urls` | string[] | 视频 URL 数组；当前最多 1 个 | ## 5. 提示词与素材限制 ### 5.1 提示词 - 所有任务都应提供非空提示词； - 最大长度为 `20000` 个字符； - 多段文本会按顺序合并； - 建议描述主体、动作、镜头运动、场景、光线、节奏和风格； - 如果使用参考素材，建议在提示词中明确每个素材的用途。 提示词示例： ```markdown Use the first image for the character appearance, the second image for the environment, and the video for camera motion. Create one continuous cinematic shot with natural movement and consistent lighting. ``` ### 5.2 图片 - 支持 JPEG、PNG、WEBP； - 每张图片最大 `20 MB`； - URL 必须能由公网直接访问； - 不应依赖 Cookie、登录状态或自定义请求头； - 无视频时最多传入 7 张图片； - 图生视频必须恰好传入 1 张图片。 ### 5.3 视频 - 每次请求最多 1 个参考视频； - 视频文件最大 `100 MB`； - 输入视频最长 `30` 秒； - 推荐使用兼容性较好的 MP4 文件； - 参考素材使用视频开头最多 10 秒的内容； - 视频 URL 必须能由公网直接访问。 ### 5.4 参考素材配额 每张图片占 1 个素材单位，每个视频占 2 个素材单位，总计不能超过 7 个单位： ```markdown 图片数量 + 视频数量 × 2 <= 7 ``` | 图片数 | 视频数 | 是否允许 | |---:|---:|---| | 7 | 0 | 是 | | 5 | 1 | 是 | | 6 | 1 | 否 | | 0 | 1 | 是 | | 0 | 2 | 否 | ## 6. 请求示例 以下示例均使用推荐的显式参数写法。 ### 6.1 横屏文生视频 ```bash curl -X POST "https://api.uniall.ai/v1beta/interactions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-omni-flash-preview", "input": "A wide cinematic shot of an astronaut walking through a field of glowing flowers at dusk, gentle wind, slow dolly-in camera movement.", "response_format": { "type": "video", "aspect_ratio": "16:9" }, "generation_config": { "video_config": { "task": "text_to_video", "resolution": "720p", "duration_seconds": 6 } }, "timeout_seconds": 600 }' ``` ### 6.2 竖屏文生视频 ```bash curl -X POST "https://api.uniall.ai/v1beta/interactions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-omni-flash-preview", "input": [ { "type": "text", "text": "Vertical fashion film, a model walking through a minimalist white gallery, soft shadows, smooth handheld camera, premium editorial style." } ], "response_format": { "type": "video", "aspect_ratio": "9:16" }, "generation_config": { "video_config": { "task": "text_to_video", "resolution": "720p", "duration_seconds": 10 } }, "timeout_seconds": 600 }' ``` ### 6.3 单图生成视频 ```bash curl -X POST "https://api.uniall.ai/v1beta/interactions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-omni-flash-preview", "input": [ { "type": "image", "url": "https://example.com/portrait.webp" }, { "type": "text", "text": "Keep the character appearance consistent. Add subtle breathing and blinking, hair moving gently in the wind, and a slow camera push-in." } ], "response_format": { "type": "video", "aspect_ratio": "9:16" }, "generation_config": { "video_config": { "task": "image_to_video", "resolution": "720p", "duration_seconds": 4 } }, "timeout_seconds": 600 }' ``` ### 6.4 多图角色与场景参考 ```bash curl -X POST "https://api.uniall.ai/v1beta/interactions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-omni-flash-preview", "input": { "text": "Use the first image for the character, the second for clothing, and the third for the environment. Create one continuous shot of the character entering the cafe and looking toward the camera.", "image_urls": [ "https://example.com/character.png", "https://example.com/outfit.jpg", "https://example.com/cafe.webp" ] }, "response_format": { "type": "video", "aspect_ratio": "16:9" }, "generation_config": { "video_config": { "task": "reference_to_video", "resolution": "720p", "duration_seconds": 8 } }, "timeout_seconds": 600 }' ``` ### 6.5 单视频动作参考 ```bash curl -X POST "https://api.uniall.ai/v1beta/interactions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-omni-flash-preview", "input": [ { "type": "video", "url": "https://example.com/dance-motion.mp4" }, { "type": "text", "text": "Create a cinematic dancer performance using the reference for body movement and rhythm. Use dramatic blue stage lighting and a slowly orbiting camera." } ], "response_format": { "type": "video", "aspect_ratio": "16:9" }, "generation_config": { "video_config": { "task": "reference_to_video", "resolution": "720p", "duration_seconds": 8 } }, "timeout_seconds": 600 }' ``` ### 6.6 图片与视频混合参考 ```bash curl -X POST "https://api.uniall.ai/v1beta/interactions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-omni-flash-preview", "input": { "text": "Use the character image for appearance, the city image for the environment, and the video for camera motion. Keep the character identity and clothing consistent throughout the shot.", "image_urls": [ "https://example.com/character.png", "https://example.com/night-city.jpg" ], "video_urls": [ "https://example.com/camera-reference.mp4" ] }, "response_format": { "type": "video", "aspect_ratio": "16:9" }, "generation_config": { "video_config": { "task": "reference_to_video", "resolution": "720p", "duration_seconds": 10 } }, "timeout_seconds": 600 }' ``` ### 6.7 Python 调用 ```python import requests api_url = "https://api.uniall.ai/v1beta/interactions" headers = { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", } payload = { "model": "gemini-omni-flash-preview", "input": [ { "type": "image", "url": "https://example.com/product.png", }, { "type": "text", "text": ( "Create a premium product film with a slow 360-degree camera " "move, soft studio reflections, and a dark background." ), }, ], "response_format": { "type": "video", "aspect_ratio": "16:9", }, "generation_config": { "video_config": { "task": "image_to_video", "resolution": "720p", "duration_seconds": 6, } }, "timeout_seconds": 600, } response = requests.post( api_url, headers=headers, json=payload, timeout=660, ) response.raise_for_status() result = response.json() print(result["interaction_id"]) print(result["response"]["video"]["uri"]) ``` ### 6.8 JavaScript 调用 ```javascript const response = await fetch("https://api.uniall.ai/v1beta/interactions", { method: "POST", headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ model: "gemini-omni-flash-preview", input: "A tiny red train crossing a snowy mountain bridge at sunrise.", response_format: { type: "video", aspect_ratio: "16:9", }, generation_config: { video_config: { task: "text_to_video", resolution: "720p", duration_seconds: 4, }, }, timeout_seconds: 600, }), }); const result = await response.json(); if (!response.ok) { throw new Error(result.error?.message ?? "Video generation failed"); } console.log(result.interaction_id); console.log(result.response.video.uri); ``` ## 7. 成功响应 成功时返回一个 Gemini Interactions 风格的结果： ```json { "interaction_id": "task_xxx", "model": "gemini-omni-flash-preview", "response": { "video": { "uri": "https://api.uniall.ai/media/generated-video.mp4" } } } ``` | 字段 | 说明 | |---|---| | `interaction_id` | 本次生成的唯一标识，可用于查询 | | `model` | 实际调用的公共模型名称 | | `response.video.uri` | 生成视频的访问地址 | 建议及时下载并保存生成结果，不要假设视频 URL 永久有效。 ## 8. 任务状态与结果 `POST /v1beta/interactions` 通常会等待交互结果。需要后续查询时，保存 `interaction_id` 并调用 `GET /v1/videos/generations/{interaction_id}`，不要使用默认任务路径。公共终态、错误结构和结果字段见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。 ## 9. 错误响应 错误响应采用统一结构： ```json { "error": { "code": 400, "message": "`duration_seconds` must be one of 4, 6, 8, or 10", "status": "INVALID_ARGUMENT" } } ``` 常见错误： | HTTP 状态码 | `error.status` | 说明 | |---:|---|---| | `400` | `INVALID_ARGUMENT` | 参数、素材数量或任务类型不符合要求 | | `400` | `FAILED_PRECONDITION` | 请求内容未通过安全检查 | | `401` | `UNAUTHENTICATED` | API Key 缺失或无效 | | `404` | `NOT_FOUND` | 模型或查询标识不存在 | | `429` | `RESOURCE_EXHAUSTED` | 请求频率过高 | | `503` | `UNAVAILABLE` | 服务暂时不可用 | | `504` | `DEADLINE_EXCEEDED` | 在 `timeout_seconds` 内未获得生成结果 | ## 10. 计费说明 价格与计费规则可能调整，请以 UniAll.ai 控制台当前显示的模型价格和用量记录为准。对账或联系支持时，请保留本次请求的 `interaction_id`。 ## 11. 调用建议 - 显式传入 `task`、`resolution`、`duration_seconds` 和 `aspect_ratio`； - 素材 URL 使用 HTTPS，并确认在无登录状态下可以直接下载； - 客户端 HTTP 超时应比 `timeout_seconds` 多预留 30–60 秒； - 视频参考任务的最终时长以成品文件为准； - 多参考任务中，应在提示词里说明每个素材的用途； - 收到 `429`、`503` 时使用指数退避重试，不要高频立即重试； - 不要在日志、前端代码或公开仓库中暴露 API Key。 --- # Grok Imagine Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/grok-imagine Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/grok-imagine.md Description: Grok Imagine 视频来源文档。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 更新时间：2026-06-03 本文说明如何在本站调用 Grok Imagine 视频模型。用户只需要使用本站稳定模型名和 OpenAI 兼容视频任务接口。 ## 1. 可用模型 | 模型 | 适用场景 | 计费口径 | | --- | --- | --- | | `grok-imagine` | 文生视频、图生视频、多参考图生视频、视频编辑、视频续写 | 按能力类型、清晰度、输入/输出视频秒数等组件计费；图生视频输入图片不单独加价 | 新接入统一使用 `grok-imagine`，用输入形态和 `extra_body.operation` 表达具体能力。未在本站模型列表中展示的旧模型名不要直接调用。 ## 2. 接口概览 ### 2.1 推荐：OpenAI 兼容视频任务接口 ```http POST /v1/videos GET /v1/videos/{task_id} GET /v1/videos/{task_id}/content ``` `POST /v1/videos` 提交任务，返回视频任务 ID。客户端轮询 `GET /v1/videos/{task_id}` 获取状态。任务完成后，可以读取响应里的 URL，也可以通过 `/v1/videos/{task_id}/content` 代理获取视频文件流。 ### 2.2 兼容：旧视频任务接口 ```http POST /v1/videos/generations GET /v1/videos/generations/{task_id} POST /v1/video/generations GET /v1/video/generations/{task_id} ``` 旧接口仍可用，但新接入推荐 `/v1/videos`。 ### 2.3 认证 ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## 3. 快速选型 | 你想做什么 | 推荐模型 | 关键输入 | 能力标识 | | --- | --- | --- | --- | | 根据提示词生成视频 | `grok-imagine` | `prompt` + `duration` | 自动推断 | | 让一张图片动起来 | `grok-imagine` | `prompt` + `image` + `duration` | 自动推断 | | 多张参考图生成视频 | `grok-imagine` | `prompt` + `images` + `duration` | 自动推断 | | 编辑已有视频 | `grok-imagine` | `prompt` + `video` + `extra_body.operation=edit_video`，建议带 `extra_body.input_video_seconds` | `edit_video` | | 续写已有视频 | `grok-imagine` | `prompt` + `video` + `duration` + `extra_body.operation=video_extend`，建议带 `extra_body.input_video_seconds` | `video_extend` | 说明：`extra_body.operation` 是本站稳定能力提示。输入形态明确时平台会自动推断；视频编辑和续写都传 `video`，建议显式传 `extra_body.operation` 消歧。 ## 4. 参数说明 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | 固定传 `grok-imagine` | | `prompt` | string | 是 | 视频生成、编辑或续写提示词 | | `image` | string/object | 图生视频必填 | 单张图片 URL；也支持 `{ "url": "..." }` | | `images` | string[] | 多参考图必填 | 多张参考图片 URL | | `image_url` / `image_urls` | string/string[] | 否 | 图片输入兼容字段 | | `video` | string/object | 编辑/续写必填 | 源视频 URL；也支持 `{ "url": "..." }` | | `videos` | string[] | 否 | 参考视频 URL 数组，适合参考视频类能力 | | `size` | string | 否 | 清晰度，常用 `480p`、`720p`；视频续写可能不支持该参数 | | `aspect_ratio` | string | 否 | 输出比例；文生视频常用 `16:9`、`1:1`、`9:16`，单图生视频可用 `auto` | | `duration` | integer/string | 条件必填 | 输出秒数。文生、图生、多参考图和续写使用；视频编辑不要传该字段 | | `seconds` | string | 条件必填 | OpenAI 兼容秒数字段；未传 `duration` 时可传 `seconds`，不要和 `duration` 同时传 | | `extra_body.operation` | string | 否 | 稳定能力提示：`text_to_video`、`image_to_video`、`reference_to_video`、`edit_video`、`video_extend` | | `extra_body.input_video_seconds` | integer | 编辑/续写建议传 | 源视频可计费秒数提示，传正整数秒。知道源视频秒数时建议传；未传时平台会探测或使用兜底值 | ## 5. 秒数规则 文生、图生、多参考图和续写都要传输出秒数。视频编辑不要传输出秒数。 | 场景 | 输出秒数字段 | 支持取值 | 输入视频秒数 | | --- | --- | --- | --- | | 文生视频 | `duration` 或 `seconds` | `1-15` 的整数秒 | 不需要 | | 单图生视频 | `duration` 或 `seconds` | `1-15` 的整数秒 | 不需要 | | 多参考图生视频 | `duration` 或 `seconds` | `1-10` 的整数秒 | 不需要 | | 视频编辑 | 不传 `duration` / `seconds` | 不适用 | 建议传 `extra_body.input_video_seconds` | | 视频续写 | `duration` 或 `seconds` | `2-10` 的整数秒 | 建议传 `extra_body.input_video_seconds` | 说明： - 推荐使用 `duration`，例如 `"duration": 6`。 - 如果客户端只能使用 OpenAI 兼容字段，可以传 `seconds`，例如 `"seconds": "6"`。 - `duration` 和 `seconds` 二选一，不要同时传。 - 视频编辑和续写的 `extra_body.input_video_seconds` 是源视频秒数提示，不是输出秒数。 - 如果不确定源视频秒数，可以不传 `extra_body.input_video_seconds`；平台会探测输入视频时长，并在计费记录里展示秒数来源。 - 计费最终不会只信任用户传参，而是按任务结算记录中的输入/输出秒数来源结算。 ## 6. 能力标识选择规则 大多数情况下不需要手动传 `extra_body.operation`： - 没有图片和视频：文生视频。 - 有一张 `image`：图生视频。 - 有多张 `images`：参考图生视频。 - 有 `video`：建议显式传 `edit_video` 或 `video_extend`。 当你要编辑已有视频： ```json { "extra_body": { "operation": "edit_video", "input_video_seconds": 8 } } ``` 当你要续写已有视频： ```json { "duration": 6, "extra_body": { "operation": "video_extend", "input_video_seconds": 8 } } ``` ## 7. 完整请求示例 ### 7.1 文生视频 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-imagine", "prompt": "电影感手持镜头，一名记者站在暴雪中的时代广场，路人撑伞快速走过，雪花不断打在镜头前，皮肤纹理真实，整体色调克制。", "size": "720p", "aspect_ratio": "16:9", "duration": 6 }' ``` 典型提交响应： ```json { "id": "task_xxx", "task_id": "task_xxx", "object": "video", "model": "grok-imagine", "status": "queued", "progress": 0, "created_at": 1773980459, "seconds": "6" } ``` ### 7.2 单图生视频 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-imagine", "prompt": "人物缓慢转头看向镜头，头发随风轻微摆动，电影级布光，镜头有细微推进。", "image": "https://example.com/portrait.png", "size": "480p", "aspect_ratio": "auto", "duration": 10 }' ``` ### 7.3 多参考图生视频 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-imagine", "prompt": "让 @Image1 中的人物走进 @Image2 的霓虹街景，保持人物身份一致，镜头缓慢推进。", "images": [ "https://example.com/person.png", "https://example.com/street.png" ], "size": "720p", "aspect_ratio": "4:3", "duration": 10 }' ``` ### 7.4 视频编辑 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-imagine", "prompt": "把这段视频改成电影感动漫风，同时保留原本动作节奏和构图。", "video": "https://example.com/source.mp4", "size": "720p", "extra_body": { "operation": "edit_video", "input_video_seconds": 8 } }' ``` 视频编辑不要传 `duration` / `seconds`。如果知道源视频秒数，建议传 `extra_body.input_video_seconds`，这样预估和日志更清楚；未传时平台会探测或使用兜底值。 ### 7.5 视频续写 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-imagine", "prompt": "延续镜头运动，逐渐露出远处城市天际线，保持原视频色调和运动方向。", "video": "https://example.com/source.mp4", "duration": 6, "extra_body": { "operation": "video_extend", "input_video_seconds": 8 } }' ``` 视频续写的 `duration` 表示输出续写秒数，支持 `2-10` 秒。如果知道源视频秒数，建议同时传 `extra_body.input_video_seconds`。 ## 8. 任务状态与结果 创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。 ## 9. 计费说明 Grok 视频在本站使用组件式计费，公开价格以模型广场展示为准。 | 场景 | 主要计费项 | | --- | --- | | 文生视频 | 清晰度档、输出视频秒数 | | 单图生视频 | 清晰度档、输出视频秒数 | | 多参考图生视频 | 清晰度档、输出视频秒数 | | 视频编辑 | 清晰度档、输入视频秒数、输出视频秒数 | | 视频续写 | 输入视频秒数、输出视频秒数 | 公开展示会显示“按实际参数计算”和组件单价，例如： - 输入视频：按秒 - 输出视频 480P：按秒 - 输出视频 720P：按秒 图生视频和多参考图生视频中的输入图片数量可能出现在结算 facts 里，但第一版 Grok 视频规则不应把它配置成单独收费组件。 提交时可能有预扣。预扣用于任务提交阶段的余额锁定，不是把某个最大值当成单次公开售价。 ## 10. 常见错误 ### 把视频模型发到图片接口 `grok-imagine` 应调用 `/v1/videos`，不要发到 `/v1/images/generations`。 ### 编辑和续写都只传了 `video` 这会产生歧义。编辑传： --- # Grok Imagine Image Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/grok/grok-imagine-image Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/grok/grok-imagine-image.md Description: Grok Imagine 图片来源文档。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 更新时间：2026-05-29 本文说明如何在本站调用 Grok Imagine 图片模型。用户只需要使用本站稳定模型名和 OpenAI 兼容图片接口。 ## 1. 可用模型 | 模型 | 适用场景 | 计费口径 | | --- | --- | --- | | `grok-imagine-image` | 标准文生图、图片编辑 | 按输出图片、输入图片等组件计费 | | `grok-imagine-image-quality` | 更高质量的文生图、图片编辑 | 按质量档、清晰度、图片数量等组件计费 | 推荐普通生成和编辑先使用 `grok-imagine-image`。需要更高质量或更高分辨率时使用 `grok-imagine-image-quality`。 ## 2. 接口概览 ### 2.1 推荐：异步图片任务 ```http POST /v1/images/tasks GET /v1/images/tasks/{task_id} ``` 异步任务适合 Grok 这类可能耗时较长的媒体生成。它支持文生图、图生图，且能透传本站支持的媒体参数，例如 `resolution`、`aspect_ratio`、`output_format`、`num_images`。 ### 2.2 兼容：OpenAI 图片接口 ```http POST /v1/images/generations POST /v1/images/edits ``` 这两个接口适合已经按 OpenAI 图片格式接入的客户端。`/v1/images/edits` 支持 JSON 图片 URL，也支持 `multipart/form-data` 上传图片文件。 ### 2.3 认证 所有接口都使用 Bearer Token： ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## 3. 快速开始 ### 3.1 异步文生图 ```bash curl -X POST "{BASE_URL}/v1/images/tasks" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-imagine-image", "task_type": "text2image", "prompt": "高端腕表广告图，黑色背景，金属反光克制，产品细节清晰，商业摄影，柔和轮廓光", "aspect_ratio": "1:1", "resolution": "1k", "output_format": "jpeg", "num_images": 1, "response_format": "url" }' ``` 提交成功后会返回任务 ID： ```json { "task_id": "task_xxx", "status": "queued", "progress": "0%", "result_url": "", "metadata": { "task_type": "text2image" }, "error": null } ``` 查询任务： ```bash curl "{BASE_URL}/v1/images/tasks/task_xxx" \ -H "Authorization: Bearer sk-***" ``` 完成后的典型响应： ```json { "code": "success", "message": "", "data": { "task_id": "task_xxx", "status": "succeeded", "progress": "100%", "result_url": "https://example.com/result-1.jpeg", "metadata": { "task_type": "text2image", "result_count": 1, "result_urls": [ "https://example.com/result-1.jpeg" ] }, "error": null } } ``` ### 3.2 异步图片编辑 ```bash curl -X POST "{BASE_URL}/v1/images/tasks" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-imagine-image-quality", "task_type": "image2image", "prompt": "保持主体结构不变，把画面改成奢侈品广告摄影风格，黑金色调，背景干净，产品边缘清晰", "image": "https://example.com/source-watch.png", "aspect_ratio": "auto", "resolution": "2k", "output_format": "webp", "num_images": 2, "response_format": "url" }' ``` ### 3.3 多参考图编辑 ```bash curl -X POST "{BASE_URL}/v1/images/tasks" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-imagine-image-quality", "task_type": "image2image", "prompt": "把第一张图的产品放到第二张图的展台环境里，保持产品比例和材质一致，输出商业海报风格", "images": [ "https://example.com/product.png", "https://example.com/stage.png" ], "aspect_ratio": "16:9", "resolution": "2k", "output_format": "png", "num_images": 1, "response_format": "url" }' ``` ### 3.4 同步文生图兼容调用 ```bash curl -X POST "{BASE_URL}/v1/images/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-imagine-image", "prompt": "一张科技产品发布会主视觉，银色设备悬浮在深色舞台中央，灯光克制，高级感", "n": 1, "response_format": "url" }' ``` 典型响应： ```json { "created": 1773980459, "data": [ { "url": "https://example.com/image.png", "revised_prompt": "" } ] } ``` ### 3.5 同步图片编辑兼容调用 JSON 图片 URL： ```bash curl -X POST "{BASE_URL}/v1/images/edits" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-imagine-image", "prompt": "保留人物身份，把背景替换成夜晚城市街头，电影感，浅景深", "image": "https://example.com/person.png", "n": 1, "response_format": "url" }' ``` multipart 文件上传： ```bash curl -X POST "{BASE_URL}/v1/images/edits" \ -H "Authorization: Bearer sk-***" \ -F "model=grok-imagine-image" \ -F "prompt=保留主体，改成高级棚拍产品图" \ -F "n=1" \ -F "response_format=url" \ -F "image=@/path/to/source.png" ``` ## 4. 参数说明 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | `grok-imagine-image` 或 `grok-imagine-image-quality` | | `prompt` | string | 是 | 生成或编辑提示词 | | `task_type` | string | 否 | 异步任务使用，`text2image` 或 `image2image`；不传时平台会按是否有图片输入推断 | | `image` | string | 图生图必填 | 单张输入图片 URL；同步编辑和异步编辑都支持 | | `images` | string[] | 多图编辑必填 | 多张参考图 URL；推荐新接入使用该字段 | | `image_url` | string | 否 | 单图 URL 兼容字段 | | `image_urls` | string[] | 否 | 多图 URL 兼容字段 | | `aspect_ratio` | string | 否 | 输出比例；文生图常用 `1:1`、`16:9`、`9:16`、`4:3`、`3:4`，图片编辑可用 `auto` | | `resolution` | string | 否 | 清晰度档，常用 `1k`、`2k`；推荐在 `/v1/images/tasks` 中使用 | | `output_format` | string | 否 | `jpeg`、`png`、`webp` | | `num_images` | integer | 否 | 生成图片数量，通常 `1-4`；异步任务推荐使用 | | `n` | integer | 否 | OpenAI 兼容数量字段，默认 `1` | | `response_format` | string | 否 | 推荐 `url` | 输入图建议： - 单图用 `image`。 - 多图用 `images`。 - 不要同时混用 `image`、`image_url`、`images`、`image_urls`，避免重复输入。 ## 5. 计费说明 Grok 图片在本站使用组件式计费，公开价格以模型广场展示为准。 | 场景 | 主要计费项 | | --- | --- | | 文生图 | 输出图片数量、清晰度档、质量档 | | 图片编辑 | 输入图片数量、输出图片数量、清晰度档、质量档 | 公开价格以模型广场展示的组件单价为准，例如“输出图片 / 张”“输入图片 / 张”“高清输出图片 / 张”。提交时可能存在预扣，但预扣是任务风控和余额锁定，不等同于最终公开单价。 ## 6. 常见错误 ### 把视频模型发到图片接口 `grok-imagine` 是视频模型，应调用 `/v1/videos` 或兼容视频任务接口。 ### 图片编辑没有传图片 `/v1/images/edits` 和 `task_type=image2image` 都必须传 `image` 或 `images`。 ### 文生图传 `aspect_ratio=auto` `auto` 更适合图片编辑。文生图建议明确传 `1:1`、`16:9`、`9:16` 等比例。 ### 同步接口和异步接口混用字段 如果需要 `resolution`、`num_images` 等 Grok 媒体参数，优先使用 `/v1/images/tasks`。同步兼容接口适合简单 OpenAI 图片客户端。 --- # Grok Video 1.5 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/grok/grok-video-1-5 Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/grok/grok-video-1-5.md Description: 通过 UniAll 异步视频接口使用 Grok Video 1.5 创建文生视频、单图生视频和多参考图视频任务。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 更新时间：2026-08-03 公共模型 `grok-video-1.5` 支持文生视频、单图生视频和多参考图生视频。通过 UniAll 异步视频接口提交任务，然后轮询任务，直到任务完成或失败。 ## 1. 能力范围 | 生成方式 | 图片输入 | `prompt` | 最高分辨率 | | --- | --- | --- | --- | | 文生视频 | 不传图片字段 | 必填 | `1080p` | | 单图生视频 | 一个 `image` 或 `image_url` | 可选 | `1080p` | | 参考图生视频 | 1 到 7 个 `reference_images` 或 `reference_image_urls` | 必填 | `720p` | 本模型还支持： - `1` 到 `15` 秒，默认 `8` 秒； - `480p`、`720p`、`1080p`，默认 `480p`； - `auto`、`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3` 画面比例； - HTTP(S) 图片 URL 和完整的图片 Data URL。 本公共模型不开放参考音频、源视频编辑或视频续写。编辑和续写请继续使用现有 Grok Imagine 视频模型。 ## 2. 适用场景 以下场景适合使用 `grok-video-1.5`： - 只用提示词生成视频； - 让一张图片动起来，可选是否补充提示词； - 使用 1 到 7 张参考图保持人物、商品或视觉风格一致； - 文生视频或单图生视频需要最高 `1080p` 输出。 首尾帧、参考音频、视频编辑和视频续写不属于本模型能力。 ## 3. 接口与鉴权 新接入建议使用以下主要接口： | 用途 | 方法 | 路径 | | --- | --- | --- | | 创建视频任务 | `POST` | `/v1/videos` | | 查询视频任务 | `GET` | `/v1/videos/{task_id}` | 兼容的 `/v1/videos/generations` 创建和查询路径继续可用。 所有请求均需使用 Bearer Token： ```http Authorization: Bearer sk-*** ``` 创建任务时还需携带： ```http Content-Type: application/json ``` ## 4. 请求体参数 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | 固定传 `grok-video-1.5`。 | | `prompt` | string | 条件必填 | 文生视频和参考图生视频必填；单图生视频可选。 | | `duration` | integer 或整数字符串 | 否 | `1` 到 `15`，默认 `8`。 | | `seconds` | integer 或整数字符串 | 否 | `duration` 的兼容别名；同时传入时两者必须一致。 | | `resolution` | string | 否 | `480p`、`720p`、`1080p`，默认 `480p`；参考图生视频最高 `720p`。 | | `size` | string | 否 | `resolution` 的兼容别名；同时传入时两者必须一致。 | | `aspect_ratio` | string | 否 | `auto`、`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`。 | | `image` | object | 否 | 单张结构化图片，固定形式为 `{"url":"..."}`。 | | `image_url` | string | 否 | 单图兼容字段。 | | `reference_images` | object[] | 否 | 1 到 7 张结构化参考图，形式为 `[{"url":"..."}]`。 | | `reference_image_urls` | string[] | 否 | 兼容字段，包含 1 到 7 个图片 URL 或 Data URL。 | 新接入建议优先使用 `duration`、`resolution` 以及结构化的 `image` 或 `reference_images` 字段。 ### 图片字段选择 四个图片字段互斥。图片类请求只能选择其中一个： | 输入形式 | 使用字段 | | --- | --- | | 单张结构化图片 | `image: {"url":"..."}` | | 单张兼容字符串 | `image_url: "..."` | | 多张结构化参考图 | `reference_images: [{"url":"..."}]` | | 多张兼容字符串参考图 | `reference_image_urls: ["..."]` | 不要在同一个请求中混用单图字段和参考图字段。 ### 支持的图片值 每个图片值必须是以下形式之一： - 服务端可访问的 `http://` 或 `https://` URL； - 完整的图片 Data URL，例如 `data:image/png;base64,...`。 裸 Base64、本机路径、依赖浏览器登录态的 URL、`images`、`image_urls` 以及任何形式的 `file_id` 都会被拒绝。 ## 5. 请求示例 ### 5.1 文生视频 下面的请求使用 `1080p` 和默认 8 秒时长： ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-video-1.5", "prompt": "A quiet mountain lake at sunrise, gentle camera movement, realistic reflections.", "resolution": "1080p", "aspect_ratio": "16:9" }' ``` ### 5.2 使用 HTTP URL 的单图生视频 单图生视频可以不传提示词： ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-video-1.5", "image": { "url": "https://example.com/product.jpg" }, "duration": 6, "resolution": "720p" }' ``` ### 5.3 使用 Data URL 的单图生视频 必须传入包含媒体类型和 Base64 前缀的完整 Data URL： ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-video-1.5", "prompt": "Subtle camera push-in and natural fabric movement.", "image_url": "data:image/png;base64,iVBORw0KGgo...", "duration": 5, "size": "480p", "aspect_ratio": "9:16" }' ``` ### 5.4 多参考图生视频 参考图生视频接受 1 到 7 张图片，分辨率只支持 `480p` 或 `720p`： ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-video-1.5", "prompt": "Keep the character identity and clothing consistent while the character turns toward the camera.", "reference_images": [ {"url": "https://example.com/character-front.jpg"}, {"url": "https://example.com/character-side.jpg"} ], "duration": 5, "resolution": "720p", "aspect_ratio": "9:16" }' ``` ## 6. 响应示例 ### 任务创建成功 请保存 `id` 或兼容字段 `task_id`，后续用于查询任务。 ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "grok-video-1.5", "status": "queued", "raw_status": "PENDING", "progress": 0, "created_at": 1785715200, "video_url": null } ``` ## 7. 任务状态与结果 创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。 ## 8. 画面比例行为 - 文生视频未传 `aspect_ratio` 时，实际默认值通常为 `16:9`。 - 单图生视频未传时，输出通常跟随输入图片比例。 - `auto` 作为兼容值继续接受。 - 如需稳定构图，请提前把源图和参考图处理为目标输出方向。 ## 9. 计费说明 本文档不定义精确用户价格。归一后的时长、分辨率和输入图片数量都会影响计费： - 未传时长时，按默认 8 秒计算； - 文生视频没有输入图片计费维度； - 单图生视频计 1 张输入图； - 参考图生视频按实际参考图数量计算； - 更高分辨率通常价格更高。 请在 UniAll 控制台查看当前价格，并在任务创建后核对账户用量。原任务进入终态前，不要重复提交。 ## 10. 常见错误 ### 缺少 `prompt` 文生视频和参考图生视频必须传 `prompt`。只有单图生视频可以省略提示词。 ### 图片字段冲突 不要混用 `image`、`image_url`、`reference_images` 或 `reference_image_urls`，只能选择其中一个。 ### 图片编码不合法 请使用 HTTP(S) URL 或完整 Data URL。`iVBORw0KGgo...` 这样的裸 Base64 字符串无效。 ### 参考图生视频请求 `1080p` 参考图生视频最高支持 `720p`。请改用 `480p` 或 `720p`；如需 `1080p`，应使用文生视频或单图生视频。 ### 参考图数量超限 `reference_images` 和 `reference_image_urls` 只接受 1 到 7 张图片。空数组或超过 7 张都会被拒绝。 ### 传入未开放字段 不要传 `file_id`、`reference_audios`、`reference_audio_urls`、`voice_id`、`output`、`storage_options` 或 `user`，也不要把它们放进 `extra_body`。 ### 请求不支持的视频操作 参考音频、首尾帧、视频编辑和视频续写不属于 `grok-video-1.5`。 ## 11. 从旧契约迁移 | 项目 | 旧契约 | 当前契约 | | --- | --- | --- | | 生成方式 | 仅单图生视频 | 文生、单图、1 到 7 张参考图生视频 | | 图片字段 | 仅 `image_url` | 结构化 `image` / `reference_images`，同时保留兼容 URL 字段 | | 图片值 | 仅 HTTP(S) URL | HTTP(S) URL 或完整图片 Data URL | | 单图提示词 | 必填 | 可选 | | 时长 | 必填整数 `duration` | `duration` 或 `seconds`，`1..15`，默认 `8` | | 分辨率 | `480p` 或 `720p` | 文生和单图新增 `1080p` | | 画面比例 | 六种比例和 `auto` | 新增 `4:3`、`3:4` | 不要迁移到渠道原生模型名或文件 ID。继续使用稳定公共模型 `grok-video-1.5` 和 UniAll 任务接口。 ## 12. 相关页面 - [查询余额](/zh-CN/balance) - [Grok Imagine 视频生成](/zh-CN/models/video/grok-imagine) - [Grok Imagine 图片生成](/zh-CN/models/video/grok/grok-imagine-image) --- # Hailuo Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/hailuo Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/hailuo.md Description: 通过 UniAll 视频任务接口调用 Hailuo 系列，创建文生、单图和首尾帧视频。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 更新时间：2026-08-04 ## 概览 UniAll 通过 OpenAI 兼容的异步视频任务接口提供三个稳定的 Hailuo 公共模型。 | 模型 | 文生视频 | 单图生视频 | 首尾帧生视频 | | --- | --- | --- | --- | | `hailuo-02` | 支持 | 支持 | 支持 | | `hailuo-2.3` | 支持 | 支持 | 不支持 | | `hailuo-2.3-fast` | 不支持 | 支持 | 不支持 | 三个模型统一使用创建、查询和内容下载接口，请求字段组合决定生成模式。 ## 适用场景 Hailuo 系列适合以下任务： - 根据提示词生成 6 秒或 10 秒视频； - 让一张可公开访问的图片动起来； - 使用 `hailuo-02` 生成首尾帧过渡视频； - 选择 `768p` 或 `1080p` 输出。 Hailuo 公共契约不支持音频、多参考图、参考视频、画幅比例控制或视频编辑。 ## 公共限制 - `duration` 必须是 `6` 或 `10` 秒。 - `resolution` 必须是 `768p` 或 `1080p`。 - `1080p` 只支持生成 6 秒视频。 - 输入图片必须是公开可访问的 HTTP(S) URL。 - 提示词最长 2,000 个字符。 ## 接口 | 用途 | 方法 | 路径 | | --- | --- | --- | | 创建视频任务 | `POST` | `/v1/videos` | | 查询视频任务 | `GET` | `/v1/videos/{task_id}` | | 下载视频文件 | `GET` | `/v1/videos/{task_id}/content` | ## 鉴权 所有请求均使用 UniAll Bearer Token： ```http Authorization: Bearer sk-*** ``` 创建任务时还需发送： ```http Content-Type: application/json ``` ## 请求体参数 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | `hailuo-02`、`hailuo-2.3` 或 `hailuo-2.3-fast`。 | | `prompt` | string | 是 | 视频内容描述，最长 2,000 个字符。 | | `image` | string | 条件必填 | 单图生视频的输入图或首尾帧模式的首帧，必须是公开 HTTP(S) URL。 | | `last_image` | string | 条件必填 | 尾帧图片的公开 HTTP(S) URL；仅 `hailuo-02` 支持，且必须与 `image` 一起传入。 | | `duration` | integer | 是 | `6` 或 `10`。 | | `resolution` | string | 是 | `768p` 或 `1080p`；`1080p` 只支持 6 秒。 | | `prompt_optimizer` | boolean | 否 | 是否在生成前优化提示词。 | | `fast_pretreatment` | boolean | 否 | 是否使用快速预处理；首尾帧模式不要传 `true`。 | | `watermark` | boolean | 否 | 是否添加 AIGC 水印。 | 根据生成模式选择输入字段： | 模式 | 模型 | 输入字段 | | --- | --- | --- | | 文生视频 | `hailuo-02` 或 `hailuo-2.3` | `prompt` | | 单图生视频 | 任意 Hailuo 模型 | `prompt` + `image` | | 首尾帧生视频 | `hailuo-02` | `prompt` + `image` + `last_image` | 字段约束： - 文生视频不要传入 `image` 或 `last_image`。 - `hailuo-2.3-fast` 只支持单图生视频，因此必须传入 `image`。 - `last_image` 不能单独使用，必须与 `image` 一起传入。 - `last_image` 只能与 `hailuo-02` 配合使用。 - 所有支持的公共参数都直接放在请求体顶层。 - 不要传入音频、多参考图数组、参考视频、画幅比例或视频编辑字段。 ## 请求示例 ### 文生视频 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "hailuo-2.3", "prompt": "A cinematic train passes through a snowy mountain canyon while morning mist drifts slowly and the camera moves forward.", "duration": 6, "resolution": "1080p", "prompt_optimizer": true, "watermark": false }' ``` ### 单图生视频 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "hailuo-2.3-fast", "prompt": "The person naturally raises their head and looks at the camera while face and clothing remain consistent.", "image": "https://example.com/source.png", "duration": 6, "resolution": "768p", "fast_pretreatment": true, "watermark": false }' ``` ### 首尾帧生视频 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "hailuo-02", "prompt": "Transition naturally from day to night while the building structure remains stable and the motion stays smooth.", "image": "https://example.com/first.png", "last_image": "https://example.com/last.png", "duration": 6, "resolution": "1080p", "prompt_optimizer": true, "watermark": false }' ``` ## 响应示例 ### 任务创建成功 请保存返回的 `id`，用于后续查询： ```json { "id": "task_xxxxxxxxxxxxx", "object": "video", "model": "hailuo-2.3", "status": "queued", "progress": 0, "created_at": 1785772800 } ``` ## 任务状态与结果 创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。 ## 计费说明 所选模型、`duration` 和 `resolution` 会影响计费；`1080p` 不支持 10 秒请求。当前价格和最终扣费以 UniAll 模型页与消费日志为准。 ## 常见错误 以下请求会被拒绝： - 模型不支持当前生成模式； - `duration` 不是 `6` 或 `10`； - `1080p` 请求了 10 秒视频； - `hailuo-2.3-fast` 缺少 `image`； - 单独传入 `last_image`，或对 `hailuo-02` 以外的模型传入 `last_image`； - 图片 URL 无法由服务端公开访问； - 请求音频、参考视频、多参考图、画幅比例控制或视频编辑能力。 传入 `watermark: false` 表示请求关闭 AIGC 水印。最终水印行为还可能受平台可用性与模型策略影响；如果完成结果仍出现非预期水印，请联系 UniAll 支持。 ## 相关页面 - [视频生成概览](/zh-CN/models/video/overview) - [模型列表](/zh-CN/models) --- # Happy Horse Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/happy-horse Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/happy-horse.md Description: 通过 UniAll 使用统一的 Happy Horse 模型创建文生、图生、多参考图和视频编辑任务。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 更新时间：2026-08-10 ## 概览 UniAll 只对外提供一个稳定的 Happy Horse 公共模型：`happy-horse`。当前公共契约开放 Happy Horse 1.0 的能力，生成方式和输出档位都通过请求参数选择，不再拆分成多个模型名。 | 能力 | `operation` | 必需素材 | 分辨率 | | --- | --- | --- | --- | | 文生视频 | `text_to_video` | 无 | `720p`、`1080p` | | 图生视频 | `image_to_video` | 恰好 1 张图片 | `720p`、`1080p` | | 多参考图生视频 | `reference_to_video` | 1 至 9 张图片 | `720p`、`1080p` | | 视频编辑 | `edit_video` | 恰好 1 个视频，可选 0 至 5 张图片 | `720p`、`1080p` | 历史档位模型名不再兼容。所有请求都必须使用 `model: "happy-horse"`，并同时传入 `operation` 和 `resolution`。 公共 HappyHorse 1.0 契约不开放 `480p`，使用该分辨率的请求会在任务创建前被拒绝。 ## 适用场景 使用 `happy-horse` 可以： - 根据文字提示词生成视频； - 让一张源图片动起来并尽量保持原始构图； - 通过多张参考图保持人物、商品或视觉风格一致； - 编辑已有视频，并选择保留原音频或自动处理音频。 ## 接口 新接入统一使用以下接口： | 用途 | 方法 | 路径 | | --- | --- | --- | | 创建视频任务 | `POST` | `/v1/videos` | | 查询视频任务 | `GET` | `/v1/videos/{task_id}` | | 获取完成后的视频 | `GET` | `/v1/videos/{task_id}/content` | 兼容的 `/v1/videos/generations` 和 `/v1/video/generations` 创建、查询路径仍可使用。新客户端建议统一使用 `/v1/videos`。 ## 鉴权 ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## 快速请求示例 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "happy-horse", "operation": "text_to_video", "resolution": "1080p", "prompt": "A white horse runs across a misty grassland at sunrise, cinematic camera movement.", "duration": 7, "aspect_ratio": "16:9", "seed": 12345, "watermark": false }' ``` 创建响应会同时返回 `id` 和兼容字段 `task_id`。保存其中任意一个值，用于后续轮询。 ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "happy-horse", "status": "queued", "progress": 0, "created_at": 1785801600, "video_url": null } ``` ## 任务状态与结果 创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。 ## 计费说明 - 生成任务按操作类型、选择的分辨率档位和生成时长计费。 - 视频编辑根据实际输入和输出视频时长进行最终结算，因此最终费用可能与提交时预估不同。 - `resolution` 选择的是公共服务档位，不保证每种画幅和源图片都对应同一个固定像素尺寸；对像素尺寸有严格要求时应检查成品媒体信息。 - 最终价格以 UniAll 当前价格页和任务结算记录为准。 ## 常见错误 - 使用已删除的旧档位模型名，而不是 `happy-horse`。 - 缺少必填的 `operation` 或 `resolution`。 - 传入 `resolution: "480p"`；应使用 `720p` 或 `1080p`。 - 传入 `size`；Happy Horse 只使用 `resolution`，并会拒绝 `size`。 - `edit_video` 请求传入 `duration` 或 `aspect_ratio`。 - `image_to_video` 请求传入 `aspect_ratio`；图生视频画面比例跟随源图片。 - 媒体 URL 是私有地址、已过期或无法从公网访问。 ## 相关页面 - [创建 Happy Horse 任务](/zh-CN/models/video/happy-horse/create-task) - [视频生成概览](/zh-CN/models/video/overview) --- # 创建 Happy Horse 视频任务 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/happy-horse/create-task Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/happy-horse/create-task.md Description: 使用统一的 happy-horse 模型创建文生、图生、多参考图和视频编辑任务。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 更新时间：2026-08-10 ## 概览 所有能力都使用唯一公共模型 `happy-horse`。通过 `operation` 选择文生、图生、多参考图或视频编辑，通过 `resolution` 选择输出档位。 不要使用已删除的旧档位模型名。旧名字与当前公共契约不兼容。 ## 接口 ```http POST /v1/videos ``` 兼容的创建路径： ```http POST /v1/videos/generations POST /v1/video/generations ``` 新接入建议使用 `/v1/videos`。 ## 鉴权 ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## 能力矩阵 | `operation` | 提示词 | 图片输入 | 视频输入 | 分辨率 | `duration` | `aspect_ratio` | | --- | --- | --- | --- | --- | --- | --- | | `text_to_video` | 必填 | 不接受 | 不接受 | `720p`、`1080p` | 可选，默认 `5` | 可选，默认 `16:9` | | `image_to_video` | 可选 | 恰好 1 张 | 不接受 | `720p`、`1080p` | 可选，默认 `5` | 不支持 | | `reference_to_video` | 必填 | 1 至 9 张 | 不接受 | `720p`、`1080p` | 可选，默认 `5` | 可选，默认 `16:9` | | `edit_video` | 必填 | 0 至 5 张 | 恰好 1 个 | `720p`、`1080p` | 不支持 | 不支持 | ## 请求体参数 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | 固定为 `happy-horse`。 | | `operation` | string | 是 | `text_to_video`、`image_to_video`、`reference_to_video` 或 `edit_video`。 | | `resolution` | string | 是 | 所有操作均支持 `720p` 或 `1080p`。 | | `prompt` | string | 条件必填 | 除 `image_to_video` 外均必填，最长 `2500` 字符。 | | `duration` | integer | 否 | 仅生成使用，范围 `3` 至 `15`，默认 `5`；编辑请求不能传。 | | `aspect_ratio` | string | 否 | 仅文生和多参考图生视频使用；图生和编辑请求不能传。 | | `image` | string | 条件必填 | `image_to_video` 推荐使用的单张 HTTP(S) 图片字段。 | | `images` | string[] | 条件必填 | `reference_to_video` 使用的 1 至 9 张 HTTP(S) 图片。 | | `reference_image_urls` | string[] | 否 | 多参考图的别名；视频编辑也可使用，最多 5 张。 | | `video` | string | 条件必填 | `edit_video` 使用的单个 HTTP(S) 源视频。 | | `seed` | integer | 否 | 随机种子，范围 `0` 至 `2147483647`。 | | `watermark` | boolean | 否 | 是否添加水印，默认 `false`。 | | `audio_setting` | string | 否 | 仅编辑使用：`auto` 或 `origin`，默认 `auto`。 | 文生和多参考图生视频支持以下 `aspect_ratio`： - `16:9` - `9:16` - `1:1` - `4:3` - `3:4` - `4:5` - `5:4` - `9:21` - `21:9` `size` 和 `enable_safety_checker` 不属于 Happy Horse 公共参数，传入会被拒绝。 公共 HappyHorse 1.0 契约不开放 `480p`。把 `resolution` 设为 `480p` 的请求会在 任务创建前被拒绝。 ## 输入规则 | 模式 | 可用素材字段 | | --- | --- | | 文生视频 | 不传图片或视频字段 | | 图生视频 | 使用 `image`，或通过受支持的图片别名传入恰好 1 张图片 | | 多参考图生视频 | 使用 `images` 或 `reference_image_urls`，传入 1 至 9 个 URL | | 视频编辑 | 使用 `video`，并可选传入最多 5 个 `reference_image_urls` | 所有媒体输入都必须是完整、可公开访问的 HTTP 或 HTTPS URL。当前模型契约不接受文件上传、裸 Base64 或 Data URL。 ## 请求示例 ### 文生视频 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "happy-horse", "operation": "text_to_video", "resolution": "1080p", "prompt": "A white horse runs across a misty grassland at sunrise, realistic movement and soft rim light.", "duration": 7, "aspect_ratio": "21:9", "seed": 12345, "watermark": false }' ``` ### 图生视频 输出构图跟随源图片，因此不要传 `aspect_ratio`。 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "happy-horse", "operation": "image_to_video", "resolution": "720p", "image": "https://example.com/source-frame.png", "prompt": "The subject walks forward naturally while the camera slowly pushes in.", "duration": 5, "seed": 67890, "watermark": false }' ``` `image_to_video` 可以省略提示词。 ### 多参考图生视频 提示词可以使用 `character1` 至 `character9`，按数组顺序指代参考图。 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "happy-horse", "operation": "reference_to_video", "resolution": "720p", "prompt": "character1 drives character2 across the lunar surface while both identities remain consistent.", "reference_image_urls": [ "https://example.com/character.png", "https://example.com/vehicle.png" ], "duration": 8, "aspect_ratio": "16:9", "seed": 24680, "watermark": false }' ``` ### 视频编辑 编辑时长跟随源视频，不能传 `duration` 或 `aspect_ratio`。 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "happy-horse", "operation": "edit_video", "resolution": "1080p", "prompt": "Replace the jacket with the referenced red jacket while preserving identity, motion, camera movement, and background.", "video": "https://example.com/source-video.mp4", "reference_image_urls": [ "https://example.com/red-jacket.png" ], "audio_setting": "origin", "seed": 13579, "watermark": false }' ``` 使用 `audio_setting: "origin"` 保留原音频；使用 `auto` 让服务自动决定音频处理方式。 ## `extra_body` 兼容 推荐把公共参数直接放在请求体顶层。兼容客户端也可以把 `operation`、`resolution`、`seed`、`watermark` 和 `audio_setting` 放入 `extra_body`。不要在顶层和 `extra_body` 中传入互相冲突的值。 ```json { "model": "happy-horse", "prompt": "Turn the room into a warm wooden studio.", "video": "https://example.com/source-video.mp4", "extra_body": { "operation": "edit_video", "resolution": "720p", "audio_setting": "auto", "watermark": false } } ``` ## 响应示例 ### 任务已受理 ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "happy-horse", "status": "queued", "progress": 0, "created_at": 1785801600, "video_url": null } ``` ## 任务状态与结果 创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。 视频编辑等最终结算操作应在任务完成后再次读取 `billing_contract`。 ## 素材限制 ### 图生视频源图片 - 格式：JPEG、JPG、PNG、BMP 或 WebP。 - 最小尺寸：`300px`。 - 画面比例：`1:2.5` 至 `2.5:1`。 - 最大文件：`10MB`。 ### 多参考图 - 格式：JPEG、JPG、PNG 或 WebP。 - 数量：1 至 9 张。 - 最短边至少 `400px`，建议 720p 以上。 - 每张最大 `10MB`。 ### 视频编辑源素材 - 格式：MP4 或 MOV，推荐 H.264。 - 输入时长：3 至 60 秒；编辑服务最多处理 15 秒。 - 尺寸：长边不超过 `2160px`，短边不小于 `320px`。 - 画面比例：`1:2.5` 至 `2.5:1`。 - 帧率：大于 `8fps`。 - 最大文件：`100MB`。 编辑参考图支持 JPEG、JPG、PNG 或 WebP，尺寸至少 `300px`，每张最大 `10MB`。 ## 计费说明 - 文生、图生和多参考图生成按请求的输出时长与分辨率档位结算。 - 视频编辑根据实际输入和输出视频时长进行最终结算，最终费用可能与提交时预估不同。 - `resolution` 是服务档位，不保证每种画幅或源图片都对应一个固定像素尺寸。 - 最终金额以 UniAll 当前价格页和任务结算记录为准。 ## 常见错误 | 错误 | 原因 | 处理方式 | | --- | --- | --- | | 模型名无效 | 使用了已删除的旧档位模型名 | 把 `model` 改为 `happy-horse` | | 缺少参数 | 未传 `operation` 或 `resolution` | 显式传入两个参数 | | 参数不支持 | 传入了 `size` 或 `enable_safety_checker` | 删除不支持的字段 | | 素材数量不正确 | 当前操作收到错误数量的图片或视频 | 按能力矩阵调整素材 | | 分辨率不正确 | `resolution` 为 `480p` 或其他不支持的值 | 使用 `720p` 或 `1080p` | | 编辑参数不正确 | 编辑请求包含 `duration` 或 `aspect_ratio` | 删除不支持字段 | | 素材下载失败 | URL 私有、过期、重定向异常或无法访问 | 使用稳定的公开 HTTPS URL | ## 相关页面 - [Happy Horse 视频生成](/zh-CN/models/video/happy-horse) - [视频生成概览](/zh-CN/models/video/overview) --- # Kling Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/kling Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/kling.md Description: 通过 UniAll 创建可灵文生、图生、参考、动作控制和视频编辑任务。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 ## 概览 可灵视频能力统一使用稳定的版本级模型名。通过请求体顶层的 `resolution` 选择清晰度，通过 `operation` 选择生成方式；不要把清晰度、声音或上游路由写进模型名。 | 模型 | 视频能力 | 清晰度 | | --- | --- | --- | | `kling-v3-turbo` | 文生视频、单首帧图生视频 | `720p`、`1080p` | | `kling-v3` | 文生视频、图生视频、首尾帧、动作控制、数字人 | `std`、`pro` | | `kling-v3-omni` | 文生视频、图生视频、首尾帧、多模态参考、视频编辑 | `std`、`pro` | | `kling-o1` | 文生视频、图生视频、首尾帧、多模态参考、视频编辑 | `std`、`pro` | 模型是否可用取决于模型广场、API Key 的模型权限和当前启用的路由。历史清晰度、声音、静音和数字人档位模型名不再接受，也不会自动转换。 ## 适用场景 - 需要 `720p` 或 `1080p` 的快速文生、单图视频时使用 `kling-v3-turbo`。 - 需要首尾帧、动作控制或数字人时使用 `kling-v3`。 - 需要最多四张参考图的多模态参考或视频编辑时使用 `kling-v3-omni`。 - 需要相同的参考和编辑请求结构、且生成时长为 `3` 到 `10` 秒时使用 `kling-o1`。 ## 接口 | 操作 | 方法 | 路径 | | --- | --- | --- | | 创建视频任务 | `POST` | `/v1/videos` | | 查询视频任务 | `GET` | `/v1/videos/{task_id}` | | 下载已完成的视频 | `GET` | `/v1/videos/{task_id}/content` | `POST /v1/videos/generations` 和 `POST /v1/video/generations` 仍是兼容创建路径。新接入统一使用 `POST /v1/videos`。 ## 鉴权 ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## 清晰度与声音 在请求体顶层传入 `resolution`，不要使用 `size` 代替。未传时，Turbo 默认 `720p`，其他可灵视频模型默认 `std`。需要明确输出和计费记录时，建议显式传入。 可灵视频请求不接受 `sound` 开关。需要对白、音乐、环境声或静音效果时，直接写入 `prompt`。数字人任务使用的 `audio_url` 和 `voice_id` 是口型驱动输入，不属于声音开关。 ## 生成方式 | `operation` | 支持模型 | 必要输入 | | --- | --- | --- | | `text_to_video` | Turbo、V3、Omni、O1 | `prompt` | | `image_to_video` | Turbo、V3、Omni、O1 | `prompt` 和 `image` | | `first_last_frame` | V3、Omni、O1 | `prompt`、`image` 和 `last_image` | | `reference_to_video` | Omni、O1 | `prompt` 和图片或视频参考 | | `edit_video` | Omni、O1 | `prompt` 和 `video_url`；参考图可选 | | `motion_control` | V3 | `prompt`、`image`、`video` 和 `character_orientation` | | `avatar` | V3 | 参见[数字人口播](/zh-CN/models/avatar/digital-human) | 时长规则： - Turbo 和 V3 的生成 operation 支持 `3` 到 `15` 秒。 - Omni 的文生、图生和首尾帧支持 `3` 到 `15` 秒；`reference_to_video` 支持 `3` 到 `10` 秒。 - O1 的生成 operation 支持 `3` 到 `10` 秒。 - 动作控制、数字人和视频编辑按对应 operation 的结果时长规则处理；除非该 operation 明确支持，否则不要传 `duration`。 - Turbo 文生视频接受 `aspect_ratio`；Turbo 图生视频不接受。 ## 请求参数 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | 稳定的可灵视频模型 ID。 | | `prompt` | string | 是 | UniAll 视频任务接口要求提供的提示词。 | | `operation` | string | 建议显式传入 | 上表中的生成方式。 | | `resolution` | string | 否 | 模型对应的清晰度；默认值见上文。 | | `duration` | integer | 条件必填 | 支持时长的 operation 的输出秒数。 | | `aspect_ratio` | string | 条件必填 | `16:9`、`9:16` 或 `1:1`。 | | `image` | string | 条件必填 | 图生视频图片或首帧的公开 HTTP(S) URL。 | | `last_image` | string | 条件必填 | 尾帧图片 URL，需与 `image` 同时使用。 | | `reference_image_urls` | string[] | 否 | 多模态参考或编辑使用的参考图 URL，最多四张。 | | `video_url` | string | 条件必填 | 多模态参考或编辑使用的基础视频 URL。 | | `video` | string | 条件必填 | `motion_control` 使用的动作参考视频 URL。 | | `keep_original_sound` | string | 否 | 多模态参考和视频编辑可使用 `yes` 或 `no`。 | | `character_orientation` | string | 条件必填 | `motion_control` 使用 `image` 或 `video`。 | | `watermark` | boolean | 否 | 是否添加 AIGC 水印。 | ## 请求示例 ### Turbo 文生视频 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3-turbo", "operation": "text_to_video", "prompt": "一架纸飞机穿过清晨的城市街道，电影感运镜，轻柔环境声。", "duration": 3, "resolution": "720p", "aspect_ratio": "16:9", "watermark": false }' ``` ### Turbo 图生视频 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3-turbo", "operation": "image_to_video", "prompt": "纸飞机平稳向前滑翔，镜头缓慢跟随。", "image": "https://example.com/plane.png", "duration": 5, "resolution": "1080p" }' ``` Turbo 图生视频不要传 `aspect_ratio`。 ### V3 首尾帧 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3", "operation": "first_last_frame", "prompt": "人物自然转身并看向镜头，过渡连续平滑。", "image": "https://example.com/first.png", "last_image": "https://example.com/last.png", "duration": 5, "resolution": "pro" }' ``` ### V3 动作控制 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3", "operation": "motion_control", "prompt": "保持人物身份和服装，复现参考视频中的动作。", "image": "https://example.com/person.png", "video": "https://example.com/motion.mp4", "resolution": "pro", "character_orientation": "image" }' ``` ### Omni 多模态参考 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3-omni", "operation": "reference_to_video", "prompt": "保持人物身份和服装，把参考动作应用到基础视频。", "reference_image_urls": [ "https://example.com/person.png", "https://example.com/clothes.png" ], "video_url": "https://example.com/base.mp4", "duration": 8, "resolution": "pro", "keep_original_sound": "yes" }' ``` ### Omni 视频编辑 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "kling-v3-omni", "operation": "edit_video", "prompt": "保持人物动作不变，把背景替换为夜晚城市街道。", "video_url": "https://example.com/source.mp4", "reference_image_urls": [ "https://example.com/city-style.png" ], "resolution": "pro", "keep_original_sound": "yes" }' ``` `kling-o1` 使用相同的文生、图生、首尾帧、参考和编辑请求结构，其生成时长范围为 `3` 到 `10` 秒。 ## 响应示例 ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "kling-v3", "status": "queued", "progress": 0 } ``` ## 任务状态与结果 保存 `id` 或 `task_id`，然后按照[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)中的公共规则，每 3 到 10 秒轮询一次，并处理终态、结果字段、错误和带鉴权下载。 ## 计费说明 视频通常结合公共模型、`operation`、`resolution` 和实际输出秒数计费。任务提交时可能预扣，最终以任务结算记录和模型广场当前价格为准。 ## 常见错误 - 使用历史清晰度、声音、静音或数字人档位模型名，而不是上面的版本级模型。 - 使用 `size` 代替 `resolution`，或给视频请求传入 `sound`。 - Turbo 图生视频传入 `aspect_ratio`。 - 请求时长超出所选模型和 operation 的范围。 - 混用 `image`、`reference_image_urls` 和视频输入，重复提交同一个参考素材。 - 图片或视频 URL 无法由服务端公开访问。 - 一次轮询超时后重新提交付费任务，而不是继续查询原 `task_id`。 公共响应不会返回供应商名称、上游任务 ID、路由、凭证或上游原始请求。 ## 相关页面 - [Kling 图片](/zh-CN/models/image/kling) - [数字人口播](/zh-CN/models/avatar/digital-human) - [视频生成概览](/zh-CN/models/video/overview) --- # MiniMax H3 / H3 Max Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/minimax-h3 Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/minimax-h3.md Description: 使用 MiniMax 原生 JSON 接口创建 H3 与 H3 Max 视频任务，并查询任务、输入素材、处理 Context、再生成和管理任务。 使用 MiniMax 原生视频接口和 UniAI API Key 调用。 - 服务地址：`https://api.uniall.ai` - 模型：`MiniMax-H3`、`MiniMax-H3-Max` - Content-Type：`application/json` ## 接口 | 方法 | 路径 | 用途 | | --- | --- | --- | | POST | `/v2/video_generation` | 创建视频 | | POST | `/v2/h3_context_ir` | 创建 Context 提示词 | | POST | `/v2/video_regeneration` | 将 H3 视频再生成至 2K | | GET | `/v2/query/video_generation/{task_id}` | 查询任务 | | GET | `/v2/query/video_generation` | 查询任务列表 | | DELETE | `/v2/video_generation/{task_id}` | 取消或删除任务 | ## 创建视频 帧输入、素材参考、H3 Max、Context 和再生成请求见[调用示例](/zh-CN/models/video/minimax-h3/examples)。 ```bash curl -X POST "https://api.uniall.ai/v2/video_generation" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniMax-H3", "content": [ { "type": "text", "text": "A paper boat crosses a quiet pond in warm morning light." } ], "duration": 5, "resolution": "768P", "ratio": "16:9" }' ``` 响应： ```json { "task_id": "task_YOUR_VIDEO" } ``` ## 参数 | 字段 | 必填 | 可用值 | | --- | --- | --- | | `model` | 是 | `MiniMax-H3` 或 `MiniMax-H3-Max` | | `content` | 是 | 一条 `text`，可附加媒体项 | | `duration` | 是 | H3：整数 4–15；H3 Max：整数 5–15 | | `resolution` | 否 | H3：`768P` 或 `2K`；H3 Max：`480P` 或 `768P`。默认 `768P` | | `ratio` | 仅文生必填 | 纯文本请求必须使用具体比例；首尾帧使用 `adaptive`；参考素材默认为 `adaptive`。可选：`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`adaptive`。 | | `aigc_watermark` | 否 | 布尔值，默认 `false` | | `extra.prompt_expansion_mode` | 仅 H3 Max | `disabled`、`balanced`（默认）或 `quality` | | `callback_url` | 否 | 公网 HTTP(S) 地址。收到验证请求后 3 秒内原样返回 `challenge`；也可使用查询接口轮询。 | ## 输入图片、视频和音频 媒体放在 `content` 中。每次请求必须有一条 text，最多 7000 个字符。 | 类型 | role | | --- | --- | | `image_url` | `first_frame`、`last_frame` 或 `reference_image` | | `video_url` | `reference_video`；仅再生成时使用 `base_video` | | `audio_url` | `reference_audio` | 媒体字段使用 `{"url":"https://..."}`。图片未填写 role 时默认为 `first_frame`。首尾帧模式不能与参考素材混用。 首帧示例： ```json { "model": "MiniMax-H3", "content": [ { "type": "text", "text": "A paper boat crosses a quiet pond in warm morning light." }, { "type": "image_url", "image_url": { "url": "https://YOUR_PUBLIC_URL/first.png" }, "role": "first_frame" } ], "duration": 5, "resolution": "768P" } ``` 限制：最多 9 张图片、3 段视频、3 段音频，总计 12 个媒体项。图片支持 JPEG、PNG、WEBP、HEIC、HEIF；每张不超过 30 MB，宽高为 256–5,760 px。视频使用 MP4 或 MOV，每段不超过 50 MB，帧率为 23.976–60 fps；每段 2–15 秒，总长不超过 15 秒。音频使用 WAV 或 MP3，每段不超过 15 MB；每段 2–15 秒，总长不超过 15 秒。使用可公开访问的 URL 或对应 MIME 类型的 data URI。此接口不提供素材上传。 ## 查询任务 使用创建响应中的 task ID 轮询： ```bash curl "https://api.uniall.ai/v2/query/video_generation/task_YOUR_VIDEO" \ -H "Authorization: Bearer $UNIAI_API_KEY" ``` 视频任务响应： ```json { "task": { "id": "task_YOUR_VIDEO", "model": "MiniMax-H3", "status": "succeeded", "task_type": "generation", "modality": "video", "content": { "url": "https://YOUR_RESULT_URL/video.mp4" } } } ``` 状态：`queued`、`running`、`succeeded`、`failed`、`cancelled`。完成后从 `task.content.url` 下载视频。 ## Context Context 返回增强后的提示词，不会生成视频。使用 H3，省略 `resolution`。 ```bash curl -X POST "https://api.uniall.ai/v2/h3_context_ir" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniMax-H3", "content": [ { "type": "text", "text": "A paper boat crosses a quiet pond in warm morning light." } ], "duration": 5, "ratio": "16:9" }' ``` 使用相同的任务查询接口；结果提示词位于 `task.content.prompt`。 ## 再生成 2K 视频 仅 H3 支持再生成。使用自己账号在最近七天内创建的已完成 H3 768P 任务： ```bash curl -X POST "https://api.uniall.ai/v2/video_regeneration" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniMax-H3", "source_task_id": "task_YOUR_COMPLETED_H3_768P", "resolution": "2K" }' ``` 也可以在 `content` 中传入唯一 `base_video` 项，并附上原始提示词和全部原始输入。不要传 `duration` 或 `ratio`。 ## 列表、取消和删除 ```bash curl "https://api.uniall.ai/v2/query/video_generation?page_num=1&page_size=10" \ -H "Authorization: Bearer $UNIAI_API_KEY" ``` 列表响应包含 `items` 和 `total`。可用 `page_num`、`page_size`、`filter.model`、`filter.task_type`、`filter.task_ids` 和 `filter.status` 筛选。原生任务保留七天。 ```bash curl -X DELETE "https://api.uniall.ai/v2/video_generation/task_YOUR_VIDEO" \ -H "Authorization: Bearer $UNIAI_API_KEY" ``` DELETE 会取消排队中的任务，或删除成功／失败的任务；不能取消运行中的任务。 ## 错误 HTTP 错误响应格式： ```json { "type": "error", "error": { "type": "bad_request_error", "message": "Invalid request parameters.", "http_code": "400" }, "request_id": "opaque_request_id" } ``` 任务失败时查询仍返回任务对象，`task.status` 为 `failed`，错误信息在 `task.error` 中。创建请求超时后，先查询任务，不要直接重复提交。 --- # MiniMax H3 / H3 Max 调用示例 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/minimax-h3/examples Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/minimax-h3/examples.md Description: MiniMax H3、H3 Max 视频生成、媒体参考、Context 和 2K 再生成的原生 API 请求示例。 将 `$UNIAI_API_KEY` 和素材地址替换为你自己的值。每次发送一个请求。 ## 文生视频 ```bash curl -X POST "https://api.uniall.ai/v2/video_generation" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniMax-H3", "content": [ { "type": "text", "text": "A paper boat crosses a quiet pond in warm morning light." } ], "duration": 5, "resolution": "2K", "ratio": "16:9" }' ``` ## 首尾帧 ```bash curl -X POST "https://api.uniall.ai/v2/video_generation" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniMax-H3", "content": [ { "type": "text", "text": "The camera moves from the first frame to the last." }, { "type": "image_url", "image_url": { "url": "https://YOUR_PUBLIC_URL/first.png" }, "role": "first_frame" }, { "type": "image_url", "image_url": { "url": "https://YOUR_PUBLIC_URL/last.png" }, "role": "last_frame" } ], "duration": 5, "resolution": "768P" }' ``` ## 图片、视频和音频参考 ```bash curl -X POST "https://api.uniall.ai/v2/video_generation" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniMax-H3", "content": [ { "type": "text", "text": "A person speaks while walking through the city." }, { "type": "image_url", "image_url": { "url": "https://YOUR_PUBLIC_URL/person.png" }, "role": "reference_image" }, { "type": "video_url", "video_url": { "url": "https://YOUR_PUBLIC_URL/walking.mp4" }, "role": "reference_video" }, { "type": "audio_url", "audio_url": { "url": "https://YOUR_PUBLIC_URL/voice.mp3" }, "role": "reference_audio" } ], "duration": 5, "resolution": "768P", "ratio": "adaptive" }' ``` ## H3 Max ```bash curl -X POST "https://api.uniall.ai/v2/video_generation" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniMax-H3-Max", "content": [ { "type": "text", "text": "A paper boat crosses a quiet pond in warm morning light." } ], "duration": 5, "resolution": "768P", "ratio": "16:9", "extra": { "prompt_expansion_mode": "balanced" } }' ``` ## Context 返回处理后的提示词，不会创建视频。省略 `resolution`。 ```bash curl -X POST "https://api.uniall.ai/v2/h3_context_ir" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniMax-H3", "content": [ { "type": "text", "text": "A paper boat crosses a quiet pond in warm morning light." } ], "duration": 5, "ratio": "16:9" }' ``` ## 再生成 2K 使用自己账号最近七天内创建的已完成 H3 768P 任务。 ```bash curl -X POST "https://api.uniall.ai/v2/video_regeneration" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniMax-H3", "source_task_id": "task_YOUR_COMPLETED_H3_768P", "resolution": "2K" }' ``` --- # 视频生成概览 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/overview Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/overview.md Description: 使用统一任务生命周期创建、查询并获取 UniAll 视频生成结果。 UniAll 视频模型默认共用一套异步任务生命周期。模型 ID、输入字段和能力限制以各模型页面为准；任务轮询、状态处理、错误和结果获取统一以本页为准。 ## 模型 - [Happy Horse](/zh-CN/models/video/happy-horse) - [Seedance 2.0](/zh-CN/models/video/seedance-2-0) - [Seedance 2.5](/zh-CN/models/video/seedance-2-5)，含 [Draft 转成片流程](/zh-CN/models/video/seedance-2-5#draft-to-final) - [Grok Video 1.5](/zh-CN/models/video/grok/grok-video-1-5) - [Grok Imagine](/zh-CN/models/video/grok-imagine) - [Veo 3.1](/zh-CN/models/video/veo-3-1) - [Gemini Omni Flash Preview](/zh-CN/models/video/gemini-omni-flash-preview) - [Vidu Q3](/zh-CN/models/video/vidu) - [Hailuo](/zh-CN/models/video/hailuo) - [MiniMax H3 / H3 Max 原生 API](/zh-CN/models/video/minimax-h3) - [Kling](/zh-CN/models/video/kling) - [Wan 2.6](/zh-CN/models/video/wan-2-6) - [Sora 2](/zh-CN/models/video/sora-2) ## 默认接口 `{BASE_URL}` 为 `https://api.uniall.ai`。 | 操作 | 方法 | 接口 | | --- | --- | --- | | 创建任务 | `POST` | `/v1/videos` | | 查询状态与结果 | `GET` | `/v1/videos/{task_id}` | | 下载已完成的视频 | `GET` | `/v1/videos/{task_id}/content` | 每次请求都要携带 `Authorization: Bearer sk-***`。部分模型页面会注明兼容创建路径或特定协议例外；模型 ID 和请求体仍以对应模型页面为准。 ## 视频任务生命周期 ### 1. 保存任务 ID 创建成功后会返回公开 `id`。部分响应还会在 `task_id` 中返回同一个值用于兼容。离开创建流程前应保存其中任意一个。 ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "model-name", "status": "queued", "progress": 0, "created_at": 1785801600 } ``` ### 2. 轮询任务 每 3 到 10 秒查询一次任务： ```bash curl "{BASE_URL}/v1/videos/task_xxxxxxxxxxxxx" \ -H "Authorization: Bearer sk-***" ``` 仅当 `status` 变为 `completed` 或 `failed` 时停止轮询。任务仍为 `queued` 或 `in_progress` 时，不要重复创建同一任务。 | 状态 | 终态 | 含义 | | --- | --- | --- | | `queued` | 否 | 任务已受理，正在等待处理。 | | `in_progress` | 否 | 正在生成视频或处理结果。 | | `completed` | 是 | 最终结果已就绪。 | | `failed` | 是 | 任务未生成结果；检查 `error`。 | ### 3. 读取结果 任务完成后，可从 `video_url`、`result.video_url` 或 `result.outputs[0]` 读取公开结果。这几个字段可能指向同一个视频。 ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "model-name", "status": "completed", "progress": 100, "video_url": "https://example.com/generated-video.mp4", "result": { "video_url": "https://example.com/generated-video.mp4", "outputs": [ "https://example.com/generated-video.mp4" ] }, "error": null } ``` 完成后优先使用返回的 `video_url` 下载视频，也可使用带鉴权的内容接口： ```bash curl -L "{BASE_URL}/v1/videos/task_xxxxxxxxxxxxx/content" \ -H "Authorization: Bearer sk-***" \ -o output.mp4 ``` 任务完成前不要调用内容接口。生成媒体应及时下载，不要把结果 URL 当作永久存储地址。 ### 4. 处理失败 ```json { "id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "model-name", "status": "failed", "progress": 100, "result": null, "error": { "code": "task_failed", "message": "Video generation failed" } } ``` 参数错误应先修正输入再创建新任务。临时服务错误可使用退避策略重试，但原任务仍在运行时不要反复提交同一请求。 Seedance 2.5 创建请求失败、客户端超时或结果不确定时，不得自动重试。继续查询已有任务 ID，或先核对原请求结果再重新提交。Draft 转成片也遵守此规则，见[模型专属流程](/zh-CN/models/video/seedance-2-5#draft-to-final)。 ## 公共响应字段 | 字段 | 类型 | 说明 | | --- | --- | --- | | `id` | string | 用于轮询的公开任务 ID。 | | `task_id` | string | 存在时为 `id` 的兼容别名。 | | `object` | string | 任务对象类型，通常为 `video.generation.job`。 | | `model` | string | 创建任务时使用的公开模型 ID。 | | `status` | string | `queued`、`in_progress`、`completed` 或 `failed`。 | | `progress` | integer | 可用时为 `0` 到 `100`；不能代替 `status` 判断终态。 | | `video_url` | string 或 null | 任务完成后的公开结果 URL。 | | `result` | object 或 null | 完成后的输出详情，包括 `video_url` 或 `outputs`。 | | `error` | object 或 null | 失败任务的公开 `code` 和 `message`。 | | `created_at` | integer | 可用时为 Unix 创建时间戳。 | | `completed_at` | integer | 可用时为 Unix 完成时间戳。 | ## 模型例外 MiniMax H3 任务详情使用 `task` 对象，状态为 `queued`、`running`、`succeeded`、`failed` 或 `cancelled`。请求与响应示例见 [H3 原生 API](/zh-CN/models/video/minimax-h3)。 Gemini Omni Flash Preview 通过 `POST /v1beta/interactions` 创建请求。需要后续查询时，使用返回的 `interaction_id` 调用 `GET /v1/videos/generations/{interaction_id}`；终态、错误处理和结果字段仍遵循上面的公共规则。 Sora 2 原生 OpenAI 格式等特定协议页面可能直接流式返回自身格式，而不是标准视频任务。此类场景以对应页面的响应流程为准。 --- # Seedance 2.0 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/seedance-2-0 Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/seedance-2-0.md Description: 通过 UniAll 视频 API 调用 Seedance 2.0 模型生成视频。 Seedance 2.0 支持文生视频、图生视频、首尾帧、多模态参考、视频编辑和视频延长。新接入请从 [Seedance 2.0 系列调用指南](/zh-CN/models/video/seedance-2-0/series-guide) 开始；复用图片、视频或音频的创建与使用方法见 [Seedance 2.0 素材库](/zh-CN/models/video/seedance-2-0/material-library)。 ## 支持模型 | 模型 | 支持分辨率 | 适用场景 | | --- | --- | --- | | `seedance2.0` | `480p`、`720p`、`1080p`、`4k` | 综合质量优先，支持完整能力。 | | `seedance2.0-fast` | `480p`、`720p` | 生成速度优先。 | | `seedance2.0-mini` | `480p`、`720p` | 轻量、速度优先。 | ## Endpoint ```http POST /v1/videos GET /v1/videos/{task_id} GET /v1/videos/{task_id}/content ``` 旧客户端仍可继续使用 `/v1/videos/generations` 和 `/v1/video/generations` 创建接口。 ## Authentication ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## 请求参数 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | `seedance2.0`、`seedance2.0-fast` 或 `seedance2.0-mini`。 | | `resolution` | string | 是 | 所选模型支持的分辨率。 | | `prompt` | string | 条件必填 | 视频提示词；使用 `content[]` 时改为 `type=text` 项。 | | `duration` | integer/string | 是 | 输出时长，支持 `4` 到 `15` 秒。 | | `aspect_ratio` | string | 否 | 输出宽高比；兼容别名为 `ratio`。 | | `content` | object[] | 否 | 带明确角色的文本、图片、视频和音频多模态输入。 | | `operation` | string | 条件必填 | `reference_to_video`、`edit_video` 或 `extend_video`。 | | `generate_audio` | boolean | 否 | 是否生成带音频的视频。 | | `return_last_frame` | boolean | 否 | 是否返回生成视频的尾帧。 | ## 请求示例 ```bash curl -X POST "https://api.uniall.ai/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0", "prompt": "A clean commercial product video with slow camera movement, soft reflections, and realistic lighting.", "resolution": "720p", "duration": 8, "aspect_ratio": "16:9", "generate_audio": false, "seed": 42, "watermark": false }' ``` ## 多参考图示例 ```bash curl -X POST "https://api.uniall.ai/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0-fast", "resolution": "720p", "duration": 6, "aspect_ratio": "9:16", "operation": "reference_to_video", "content": [ { "type": "text", "text": "制作一段快速时尚 Lookbook 视频，并保持产品外观一致。" }, { "type": "image_url", "image_url": {"url": "https://example.com/model.png"}, "role": "reference_image" }, { "type": "image_url", "image_url": {"url": "https://example.com/outfit.png"}, "role": "reference_image" } ], "generate_audio": true }' ``` ## 任务状态与结果 创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。 ## 常见错误 - 新接入仍使用旧创建任务接口。 - 参考图超过 `9` 张。 - 参考视频超过 `3` 个，或总时长超过 `15` 秒。 - `duration` 不在 `4` 到 `15` 范围内。 - 新输入格式和兼容层 `operation` 混用导致路由不明确。 ## 相关页面 - [Seedance 2.0 系列调用指南](/zh-CN/models/video/seedance-2-0/series-guide) - [Seedance 2.0 素材库](/zh-CN/models/video/seedance-2-0/material-library) - [视频生成概览](/zh-CN/models/video/overview) --- # Seedance 2.0 素材库 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/seedance-2-0/material-library Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/seedance-2-0/material-library.md Description: 使用 UniAI API Key 创建素材，等待可用后将返回的 URI 用于 Seedance 视频生成，并查询列表或删除素材。 创建可复用的图片、视频或音频素材，再将返回的 `uri` 用于 Seedance 视频请求。 所有请求使用 `https://api.uniall.ai`，通过 `Authorization: Bearer $UNIAI_API_KEY` 鉴权。 ## 1. 创建素材 `POST /v1/materials` 需携带 `Idempotency-Key` 请求头，正文使用 JSON： | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `url` | string | 是 | 公网可访问的 HTTP(S) 媒体 URL，最长 4,096 个字符。 | | `type` | string | 是 | `image`、`video` 或 `audio`，须与素材类型一致。 | | `name` | string | 否 | 素材名称，最多 64 个字符。 | ```bash curl "https://api.uniall.ai/v1/materials" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: product-reference-001" \ -d '{ "url": "https://cdn.example.com/product.png", "type": "image", "name": "Product reference" }' ``` HTTP `202` 响应： ```json { "id": "mat_EXAMPLE", "object": "material", "name": "Product reference", "type": "image", "status": "processing", "uri": null, "preview_url": null, "created_at": "2026-10-29T10:00:00Z", "available_at": null, "expires_at": null } ``` - 幂等键使用 1–200 个不含空格的可见 ASCII 字符。同一请求使用原键重试会返回同一素材；参数不同则返回 HTTP `409`（`material_idempotency_conflict`）。请求超时后使用原键重试。 - URL 在处理期间须保持公网可访问，不依赖登录、Cookie 或自定义请求头。当前网页“创建素材”填写来源 URL；此 API 接收 JSON URL，不接收 multipart 文件或 Base64。本地文件请先准备为可公开访问的 HTTP(S) URL。

真人图片、视频也使用相同创建请求；如接口返回额外验证提示，以接口提示为准。

## 2. 等待素材可用 使用创建响应中的 `id`，每 3–5 秒查询一次，直到 `status` 为 `available`： ```bash curl "https://api.uniall.ai/v1/materials/mat_EXAMPLE" \ -H "Authorization: Bearer $UNIAI_API_KEY" ``` 响应示例，时间仅作示意： ```json { "id": "mat_EXAMPLE", "object": "material", "name": "Product reference", "type": "image", "status": "available", "uri": "asset://asset-EXAMPLE", "preview_url": "https://cdn.example.com/preview.png", "created_at": "2026-10-29T10:00:00Z", "available_at": "2026-10-29T10:01:00Z", "expires_at": "2026-10-30T12:00:00Z" } ``` 直接使用接口返回的 `uri`。`mat_*` 是查询和删除素材的 ID，不要用它自行拼接 `asset://` URI。素材有效期以 `expires_at` 为准，请在到期前使用。 | 状态 | 处理方式 | | --- | --- | | `creating`、`processing` | 继续查询。 | | `available` | 可以使用返回的 `uri`。 | | `failed` | 查看 `error.code` 和 `error.message`；需要重新创建时使用新的幂等键。 | | `delete_pending`、`deleted` | 停止使用素材。 | ## 3. 使用 URI 生成视频 将下方 `asset://asset-EXAMPLE` 替换为可用图片素材返回的 `uri`： ```bash curl "https://api.uniall.ai/v1/videos" \ -H "Authorization: Bearer $UNIAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0-fast", "resolution": "480p", "duration": 4, "aspect_ratio": "16:9", "generate_audio": false, "content": [ { "type": "text", "text": "Keep the product appearance consistent as the camera slowly moves around it." }, { "type": "image_url", "image_url": {"url": "asset://asset-EXAMPLE"}, "role": "reference_image" } ] }' ``` URI 放在 `image_url.url` 等结构化媒体字段中，不要写进提示词。视频和音频素材分别使用对应的 `video_url`、`audio_url` 字段。素材须属于同一 UniAI 用户，状态可用且未过期。 创建后使用返回的视频任务 ID [查询视频并获取结果](/zh-CN/models/video/overview#视频任务生命周期)。 ## 素材列表 ```bash curl "https://api.uniall.ai/v1/materials?type=image&status=available&limit=20" \ -H "Authorization: Bearer $UNIAI_API_KEY" ``` 响应包含 `data`、`has_more` 和 `next_cursor`。可用 `type`、`status` 筛选；`limit` 为 1–100，默认 `50`。下一页将返回的 `next_cursor` 原样放入 `after`。已过期或已删除素材不出现在列表中。 ## 删除素材 ```bash curl -X DELETE "https://api.uniall.ai/v1/materials/mat_EXAMPLE" \ -H "Authorization: Bearer $UNIAI_API_KEY" ``` HTTP `200` 且 `status: "deleted"` 表示删除完成；HTTP `202` 且 `status: "delete_pending"` 表示仍在处理中。可以重复 DELETE。删除完成后素材从列表消失，详情接口返回 `404 material_not_found`。 ## 请求错误 | 错误码 | 检查方式 | | --- | --- | | `invalid_idempotency_key` | 创建时携带有效的 `Idempotency-Key`。 | | `invalid_material_request` | 检查 URL、素材类型及名称长度。 | | `material_idempotency_conflict` | 使用原请求和原键重试，或为不同素材换用新键。 | | `material_not_found` | 检查 ID 和当前用户；素材可能已删除或过期。 | | `material_not_available` | 等待 `available`，并检查 `expires_at`。 | | `material_not_managed` | 从素材响应复制 `uri`，不要自行拼接。 | 视频生成参数见 [Seedance 2.0 系列指南](/zh-CN/models/video/seedance-2-0/series-guide)。 --- # Seedance 2.0 系列调用指南 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/seedance-2-0/series-guide Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/seedance-2-0/series-guide.md Description: 通过 UniAll 调用 Seedance 2.0、Seedance 2.0 Fast 和 Seedance 2.0 Mini，涵盖多模态输入、视频编辑、延长和任务查询。 更新时间：2026-07-29 本文介绍如何通过 UniAll 调用 Seedance 2.0 系列。新接入推荐使用三个稳定公共模型名，通过请求参数选择分辨率和生成能力。 ## 1. 模型选择 | 公共模型 | 支持分辨率 | 适用场景 | | --- | --- | --- | | `seedance2.0` | `480p`、`720p`、`1080p`、`4k` | 综合质量优先，支持完整能力 | | `seedance2.0-fast` | `480p`、`720p` | 生成速度优先 | | `seedance2.0-mini` | `480p`、`720p` | 轻量任务和速度优先 | 三个模型均支持： - 文生视频； - 单图生视频； - 首尾帧生视频； - 图片、视频和音频多模态参考； - 视频编辑和视频延长； - 有声视频、水印和随机种子； - 纯文本联网搜索； - 返回生成视频的尾帧； - 使用可用素材响应返回的 `uri`。 ## 2. 接口与鉴权 推荐使用 OpenAI 兼容视频任务接口： ```http POST /v1/videos GET /v1/videos/{task_id} GET /v1/videos/{task_id}/content ``` 请求头： ```http Authorization: Bearer sk-*** Content-Type: application/json ``` 以下示例中的 `{BASE_URL}` 使用： ```uri https://api.uniall.ai ``` 同时保留以下兼容接口： ```http POST /v1/videos/generations GET /v1/videos/generations/{task_id} POST /v1/video/generations GET /v1/video/generations/{task_id} ``` 新接入建议统一使用 `/v1/videos`。 ## 3. 公共参数 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | 三个公共模型之一，或兼容期内的固定分辨率模型名 | | `prompt` | string | 条件必填 | 视频提示词；使用 `content[]` 时改为至少一个 `type=text` 项 | | `resolution` | string | 新公共模型必填 | 输出分辨率，取值见模型表 | | `size` | string | 否 | `resolution` 的兼容别名 | | `duration` | integer/string | 是 | 输出时长，支持 `4` 到 `15` 秒；兼容值 `auto`，推荐显式传整数 | | `aspect_ratio` | string | 否 | `auto`、`21:9`、`16:9`、`4:3`、`3:2`、`2:3`、`1:1`、`3:4`、`9:16` | | `ratio` | string | 否 | `aspect_ratio` 的兼容别名；`adaptive` 等价于 `auto` | | `content` | object[] | 否 | 推荐的多模态输入格式，详见下一节 | | `operation` | string | 特定能力必填 | `reference_to_video`、`edit_video` 或 `extend_video` | | `generate_audio` | boolean | 否 | 是否生成有声视频 | | `watermark` | boolean | 否 | 是否添加水印 | | `seed` | integer | 否 | 随机种子 | | `return_last_frame` | boolean | 否 | 是否在完成结果中返回尾帧 URL | | `tools` | object[] | 否 | 当前仅支持 `[{"type":"web_search"}]` | 参数兼容规则： - `resolution` 和 `size` 同时传入时必须相同。 - `aspect_ratio` 和 `ratio` 同时传入时必须表达相同比例。 - `ratio: "adaptive"` 与 `aspect_ratio: "auto"` 视为相同。 - `operation`、`generate_audio`、`watermark`、`seed`、`return_last_frame` 和 `tools` 也兼容放入 `extra_body`；同一参数不要在顶层和 `extra_body` 重复传入。 - `draft`、`frames`、`camera_fixed` 和 `service_tier: "flex"` 不属于当前公共契约。 ## 4. `content[]` 多模态格式 复杂输入推荐统一使用 `content[]`： ```json { "content": [ { "type": "text", "text": "提示词" }, { "type": "image_url", "image_url": { "url": "https://example.com/image.png" }, "role": "reference_image" }, { "type": "video_url", "video_url": { "url": "https://example.com/video.mp4" }, "role": "reference_video" }, { "type": "audio_url", "audio_url": { "url": "https://example.com/audio.mp3" }, "role": "reference_audio" } ] } ``` 支持的类型和角色： | `type` | `role` | 含义 | | --- | --- | --- | | `text` | 无 | 提示词，可传多个文本项 | | `image_url` | `image` | 单图生视频输入图 | | `image_url` | `reference_image` | 参考图片 | | `image_url` | `first_frame` | 首帧图片 | | `image_url` | `last_frame` | 尾帧图片 | | `video_url` | `source_video` | 编辑或延长的源视频 | | `video_url` | `reference_video` | 参考视频 | | `audio_url` | `reference_audio` | 参考音频 | 输入约束： - `content[]` 至少包含一个非空文本项。 - 图片最多 9 张，视频最多 3 段，音频最多 3 段。 - `first_frame` 和 `last_frame` 必须成对出现，且各只能有 1 张。 - 首尾帧模式不能再混入视频、音频或其他图片。 - `image` 和 `reference_image` 不要在同一请求中混用。 - `source_video` 最多 1 段。 - 参考音频必须同时存在至少一张图片或一段视频；不接受纯音频或“文本 + 音频”。 - 使用多份参考素材时，可在提示词中按顺序使用 `@Image1`、`@Video1`、`@Audio1` 指定素材。 简单请求仍兼容 `image`、`images`、`last_image`、`video`、`videos` 和 `audios` 等字段；新功能和多模态组合建议使用 `content[]`，避免输入角色不明确。 ## 5. 请求示例 ### 5.1 文生视频 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0", "prompt": "雨后的未来城市街道，霓虹倒影，电影感镜头缓慢向前推进。", "resolution": "1080p", "duration": 5, "ratio": "16:9", "generate_audio": true }' ``` ### 5.2 单图生视频 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0-fast", "resolution": "720p", "duration": 6, "content": [ { "type": "text", "text": "人物自然转身看向镜头，衣服随风轻微摆动，保持人物身份一致。" }, { "type": "image_url", "image_url": { "url": "https://example.com/person.png" }, "role": "image" } ] }' ``` ### 5.3 首尾帧生视频 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0", "resolution": "720p", "duration": 6, "content": [ { "type": "text", "text": "镜头从白天自然过渡到夜晚，运动连贯，建筑结构保持稳定。" }, { "type": "image_url", "image_url": { "url": "https://example.com/first.png" }, "role": "first_frame" }, { "type": "image_url", "image_url": { "url": "https://example.com/last.png" }, "role": "last_frame" } ] }' ``` ### 5.4 多模态参考生视频 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0-mini", "resolution": "720p", "duration": 8, "operation": "reference_to_video", "content": [ { "type": "text", "text": "让 @Image1 中的产品按照 @Video1 的镜头运动展示，并参考 @Audio1 的节奏。" }, { "type": "image_url", "image_url": { "url": "https://example.com/product.png" }, "role": "reference_image" }, { "type": "video_url", "video_url": { "url": "https://example.com/motion.mp4" }, "role": "reference_video" }, { "type": "audio_url", "audio_url": { "url": "https://example.com/music.mp3" }, "role": "reference_audio" } ] }' ``` ### 5.5 视频编辑 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0", "resolution": "720p", "duration": 6, "operation": "edit_video", "content": [ { "type": "text", "text": "把背景替换为雨夜霓虹街道，保留人物动作和主体身份。" }, { "type": "video_url", "video_url": { "url": "https://example.com/source.mp4" }, "role": "source_video" }, { "type": "image_url", "image_url": { "url": "https://example.com/style.png" }, "role": "reference_image" } ] }' ``` ### 5.6 视频延长 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0-fast", "resolution": "720p", "duration": 5, "operation": "extend_video", "content": [ { "type": "text", "text": "延续原镜头运动，人物继续向前行走，光线和场景保持一致。" }, { "type": "video_url", "video_url": { "url": "https://example.com/source.mp4" }, "role": "source_video" } ] }' ``` ### 5.7 纯文本联网搜索 联网搜索只能用于纯文本请求，不能同时传图片、视频或音频。 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0-mini", "prompt": "根据今天公开的科技新闻制作一段简洁的资讯视频，不要显示品牌商标。", "resolution": "720p", "duration": 5, "tools": [ { "type": "web_search" } ] }' ``` `web_search` 表示允许模型检索公开信息，不保证每次生成都会实际产生搜索调用。 ### 5.8 返回尾帧 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0", "prompt": "一艘纸船缓慢停在石桥旁，最后画面保持稳定。", "resolution": "720p", "duration": 5, "return_last_frame": true }' ``` 任务完成后，尾帧通过 `result.last_frame_url` 返回，不会混入视频 `outputs`。 ### 5.9 使用素材库 URI 通过 [Seedance 2.0 素材库](/zh-CN/models/video/seedance-2-0/material-library) 创建并查询可复用输入。素材达到 `status=available` 后，把普通媒体 URL 替换为接口返回的 `uri`： ```json { "model": "seedance2.0-fast", "resolution": "480p", "duration": 4, "content": [ { "type": "text", "text": "Keep the product appearance consistent as the camera slowly moves around it." }, { "type": "image_url", "image_url": { "url": "asset://asset-EXAMPLE" }, "role": "reference_image" } ] } ``` 复制自己的素材响应中的 `uri`，不要用 `mat_*` 自行拼接。URI 只能放入对应的结构化媒体字段，不要写入提示词，并须在 `expires_at` 前使用。 ## 6. 任务状态与结果 创建成功后返回异步任务： ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "seedance2.0", "status": "queued", "progress": 0, "created_at": 1784640000 } ``` 创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。 Seedance 请求生成尾帧时，完成响应还可能包含 `result.last_frame_url`。 ## 7. 固定分辨率模型兼容 已有客户端可以继续使用固定分辨率模型名： | 模型系列 | 兼容模型名 | | --- | --- | | Standard | `seedance2.0-480p`、`seedance2.0-720p`、`seedance2.0-1080p`、`seedance2.0-4k` | | Fast | `seedance2.0-fast-480p`、`seedance2.0-fast-720p` | | Mini | `seedance2.0-mini-480p`、`seedance2.0-mini-720p` | 更早的以下名称也继续兼容： - `seedance2.0-video-480p` - `seedance2.0-video-720p` - `seedance2.0-fast-video-480p` - `seedance2.0-fast-video-720p` 固定分辨率模型从模型名确定分辨率，不要求额外传 `resolution`。它们与对应的新公共模型使用相同参数和能力；如仍传 `resolution` 或 `size`，值必须与模型名中的分辨率一致。 新项目建议迁移到三个公共模型名，便于只修改请求参数即可切换输出分辨率。 ## 8. 常见错误 | 场景 | 结果 | 修正方式 | | --- | --- | --- | | 新公共模型缺少 `resolution`/`size` | HTTP `400` | 显式传入支持的分辨率 | | `resolution` 与 `size` 不同 | HTTP `400` | 只传一个，或保证值相同 | | `aspect_ratio` 与 `ratio` 冲突 | HTTP `400` | 只传一个，或保证语义相同 | | 缺少 `duration` | HTTP `400` | 传 `4` 到 `15` 的整数 | | `content[]` 没有文本项 | HTTP `400` | 增加非空 `type=text` 项 | | 首帧和尾帧没有成对传入 | HTTP `400` | 同时传 `first_frame` 和 `last_frame` | | 纯音频或“文本 + 音频” | HTTP `400` | 至少增加一张图片或一段视频 | | 联网搜索请求包含媒体 | HTTP `400` | 搜索请求只保留文本输入 | | 图片、视频或音频数量超限 | HTTP `400` | 分别控制在 9、3、3 个以内 | | 使用 `draft`、`frames`、`camera_fixed` 或 `service_tier=flex` | HTTP `400` | 删除这些参数 | 遇到安全审核、素材格式或参数错误时，应修改输入后创建新任务，不要对同一无效请求进行高频重复提交。 ## 9. 相关页面 - [Seedance 2.0](/zh-CN/models/video/seedance-2-0) - [Seedance 2.0 素材库](/zh-CN/models/video/seedance-2-0/material-library) - [视频生成概览](/zh-CN/models/video/overview#视频任务生命周期) --- # Seedance 2.5 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/seedance-2-5 Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/seedance-2-5.md Description: 使用 Seedance 2.5 创建 480p/720p/1080p 视频、音频参考、Draft 样片及 1080p 成片，支持编辑、延长和高级控制。 本页中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 更新时间：2026-10-19 ## 概览 UniAll 对外提供一个稳定的 Seedance 2.5 公共模型：`seedance2.5`。该模型支持文生视频、单首帧和首尾帧生视频、多模态参考生成、视频编辑、视频延长、可复用 `asset://` 素材、可选的联网搜索，以及 480p Draft 样片转 1080p 成片。 | 能力 | 必需输入 | 核心规则 | | --- | --- | --- | | 文生视频 | 提示词 | 默认 `720p`、自动时长，也可显式选择。 | | 单首帧生视频 | 1 张首帧图 | 省略 `aspect_ratio` 或设为 `auto`。 | | 首尾帧生视频 | 1 张首帧图和 1 张尾帧图 | 省略 `aspect_ratio` 或设为 `auto`。 | | 多模态参考生成 | 图片、视频或音频 | 文本可省略，也允许仅音频参考。 | | 视频编辑 | 提示词和 1 个视频 | 显式传 `omni_reference_task_type: "edit"`，使用自动时长。 | | 视频延长 | 提示词和 1 个视频 | 显式传 `omni_reference_task_type: "extend"`。 | | Draft 转成片 | 当前用户已完成的 Draft 任务 ID | 样片为 `480p`，七天内可转为继承原设置的 `1080p` 成片。 | ## 接口与鉴权 | 操作 | 方法 | 路径 | | --- | --- | --- | | 创建任务 | `POST` | `/v1/videos` | | 查询任务 | `GET` | `/v1/videos/{task_id}` | 已有客户端可继续使用以下兼容创建和查询路径： ```http POST /v1/videos/generations POST /v1/video/generations GET /v1/videos/generations/{task_id} GET /v1/video/generations/{task_id} ``` 新接入统一使用 `/v1/videos` 和 `/v1/videos/{task_id}`。 ```http Authorization: Bearer Content-Type: application/json ``` ## 请求参数 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | `seedance2.5`。 | | `prompt` | string | 条件必填 | 文本指令。纯文生、编辑和延长必填；有图片、视频或音频参考时可省略，Draft 转成片时必须省略。 | | `resolution` | string | 否 | `480p`、`720p` 或 `1080p`。普通请求默认 `720p`；Draft 默认且只能为 `480p`；Draft 转成片默认且只能为 `1080p`。 | | `duration` | integer/string | 否 | `"auto"`、`-1` 或 `4` 到 `30` 的整数，默认自动时长。编辑只能使用自动时长；Draft 转成片时省略。 | | `aspect_ratio` | string | 否 | `auto`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4` 或 `9:16`。帧输入、编辑和延长需省略或使用 `auto`；Draft 转成片时省略。 | | `content` | object[] | 否 | 文字、图片、视频或音频内容。文字项使用 `{"type":"text","text":"..."}`，媒体角色见下文。 | | `omni_reference_task_type` | string | 否 | `auto`、`reference`、`edit` 或 `extend`。编辑或延长需显式设置对应值；Draft 转成片时省略。 | | `draft` | boolean | 否 | `true` 创建 480p 样片，默认 `false`；Draft 转成片时不能为 `true`。 | | `draft_task_id` | string | 条件必填 | 同一用户创建、已完成且创建未满七天的 UniAI Draft 任务 ID，用于生成 1080p 成片。 | | `output_format` | string | 否 | `mp4` 或 `mov`，默认 `mp4`。 | | `generate_audio` | boolean | 否 | 是否生成音频，显式 `false` 会保留。Draft 转成片时继承，必须省略。 | | `watermark` | boolean | 否 | 是否添加水印，显式 `false` 会保留。 | | `return_last_frame` | boolean | 否 | 是否在可用时返回生成视频的尾帧，显式 `false` 会保留。 | | `seed` | integer | 否 | `-1` 到 `2147483647`；Draft 转成片时省略。 | | `priority` | integer | 否 | `0` 到 `9`，显式 `0` 会保留。 | | `execution_expires_after` | integer | 否 | 执行过期时间，单位为秒，范围 `3600` 到 `259200`。 | | `safety_identifier` | string | 否 | `1` 到 `64` 个可见 ASCII 字符，不含空格或控制字符；使用非敏感标识。 | | `tools` | object[] | 否 | 联网搜索使用 `[{"type":"web_search"}]`；Draft 转成片时省略。 | | `service_tier` | string | 否 | 仅支持 `default`，不支持 `flex`。 | | `size` | string | 否 | `resolution` 的兼容别名；两者同时存在时必须描述同一分辨率，推荐使用 `resolution`。 | | `seconds` | integer/string | 否 | `duration` 的兼容别名，推荐使用 `duration`；Draft 转成片时省略。 | | `ratio` | string | 否 | `aspect_ratio` 的兼容别名，`adaptive` 归一为 `auto`；Draft 转成片时省略。 | | `operation` | string | 否 | 兼容操作选择：`reference_to_video`、`edit_video` 或 `extend_video`。新示例优先使用 `omni_reference_task_type`，不要传入冲突选择；Draft 转成片时省略。 | 参数放在顶层。兼容客户端也可把控制参数放在 `extra_body` 中；同一字段在两处同时出现时，值必须一致。显式 `false` 和 `0` 是有效值，不等同于省略。 不支持 4K、`frames`、`camera_fixed` 或 `flex` 服务档位。 ## 最小文生请求 ```bash curl -X POST "https://api.uniall.ai/v1/videos" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.5", "prompt": "A mechanical bird unfolds its wings on a wooden table." }' ``` 省略 `resolution` 和 `duration` 时，普通生成使用 `720p` 和自动时长。需要明确规格和高级控制时可使用： ```json { "model": "seedance2.5", "prompt": "A mechanical bird unfolds its wings on a wooden table.", "resolution": "1080p", "duration": 4, "aspect_ratio": "16:9", "output_format": "mp4", "generate_audio": true, "watermark": false, "return_last_frame": true, "seed": 250628, "priority": 0, "execution_expires_after": 86400, "safety_identifier": "video-demo-01" } ``` ## 媒体输入 新接入建议使用 `content[]` 表达多模态输入。每一项包含一个媒体类型和明确角色。 | 项目类型 | URL 字段 | 支持角色 | | --- | --- | --- | | `text` | `text` | 生成或编辑指令 | | `image_url` | `image_url.url` | `first_frame`、`last_frame`、`reference_image` | | `video_url` | `video_url.url` | `reference_video` | | `audio_url` | `audio_url.url` | `reference_audio` | 媒体地址可以是公开 HTTP(S) URL，也可以是有效的 `asset://` 素材地址。HTTP(S) 素材必须能由 UniAll 服务直接访问，不能依赖 Cookie 或自定义请求头。创建可复用 `asset://` 输入的方法见 [Seedance 素材库](/zh-CN/models/video/seedance-2-0/material-library)。素材可用后直接复制响应返回的 `uri`，不要用 `mat_*` 自行拼接，并须在 `expires_at` 前使用。 图片和音频兼容字段 `image`、`images`、`audios` 和 `last_image` 仍可使用。不要同时通过 `content[]` 和兼容字段传入冲突内容。 视频参考请使用 `content[]` 中 `type: "video_url"`、`role: "reference_video"` 的写法。顶层 `video` / `video_url` 字段使用编辑或延长入口的语义，不能直接替代参考视频内容项。编辑或延长时需显式设置 `omni_reference_task_type` 为 `edit` 或 `extend`。 ### 媒体数量限制 - 图片最多 `30` 张。 - 视频最多 `10` 个。 - 音频最多 `10` 个。 - 所有媒体合计最多 `50` 个。 - 多模态请求可以不包含文本。 - 允许仅音频参考请求。 ## 操作规则 | 模式 | `omni_reference_task_type` | `duration` | `aspect_ratio` | | --- | --- | --- | --- | | 文生视频 | 省略或 `auto` | 省略、`"auto"`、`-1` 或整数 `4..30` | 任意支持值 | | 单首帧 / 首尾帧生视频 | 省略或 `auto` | 省略、`"auto"`、`-1` 或整数 `4..30` | 省略或 `auto` | | 多模态参考生成 | 显式指定时使用 `reference` | 省略、`"auto"`、`-1` 或整数 `4..30` | 由媒体模式决定；帧输入需使用 `auto` | | 视频编辑 | 必须为 `edit` | 省略、`"auto"` 或 `-1` | 省略或 `auto` | | 视频延长 | 必须为 `extend` | 省略、`"auto"`、`-1` 或整数 `4..30` | 省略或 `auto` | | Draft 转成片 | 省略，自动继承 | 省略，自动继承 | 省略，自动继承 | 编辑和延长都需要提示词和源视频，不要通过提示词关键词推断操作。原有 `operation` 选择仍兼容，新示例使用 `omni_reference_task_type`。 ## 请求示例 ### 首尾帧生视频 ```json { "model": "seedance2.5", "prompt": "Move naturally from the first composition to the last while preserving the subject.", "resolution": "720p", "duration": 10, "aspect_ratio": "auto", "content": [ { "type": "image_url", "image_url": { "url": "https://example.com/first.png" }, "role": "first_frame" }, { "type": "image_url", "image_url": { "url": "https://example.com/last.png" }, "role": "last_frame" } ] } ``` 单首帧模式只传 `first_frame` 项。两种帧模式都不能使用固定画幅，因为画面构图由源图片决定。 ### 多模态参考生成 ```json { "model": "seedance2.5", "omni_reference_task_type": "reference", "resolution": "720p", "duration": 12, "content": [ { "type": "image_url", "image_url": { "url": "https://example.com/product.png" }, "role": "reference_image" }, { "type": "video_url", "video_url": { "url": "https://example.com/motion.mp4" }, "role": "reference_video" }, { "type": "audio_url", "audio_url": { "url": "https://example.com/music.mp3" }, "role": "reference_audio" } ] } ``` ### 仅音频参考，无提示词 ```json { "model": "seedance2.5", "resolution": "480p", "duration": 4, "content": [ { "type": "audio_url", "audio_url": { "url": "https://example.com/reference.wav" }, "role": "reference_audio" } ] } ``` ### 视频编辑 ```json { "model": "seedance2.5", "prompt": "Replace the sky and preserve the subject", "video": "https://example.com/source.mp4", "omni_reference_task_type": "edit", "resolution": "720p", "duration": "auto", "aspect_ratio": "auto" } ``` ### 视频延长 ```json { "model": "seedance2.5", "prompt": "Continue the camera movement into the illuminated square.", "video": "asset://asset-EXAMPLE", "omni_reference_task_type": "extend", "resolution": "720p", "duration": 8, "aspect_ratio": "auto", "output_format": "mov" } ``` ### 联网搜索 ```json { "model": "seedance2.5", "prompt": "Create a concise visual recap of the latest public spaceflight milestone.", "resolution": "720p", "duration": 8, "tools": [ { "type": "web_search" } ] } ``` 联网搜索可以与媒体输入组合。其他 `tools` 结构不受支持。 ## Draft 样片转 1080p 成片 {/* #draft-to-final */} ### 1. 创建 480p Draft 设置 `draft: true`。省略 `resolution` 时使用 `480p`；显式指定其他档位会拒绝。Draft 也可使用本页的媒体参考输入。 ```bash curl -X POST "https://api.uniall.ai/v1/videos" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.5", "prompt": "A mechanical bird unfolds its wings on a wooden table.", "draft": true, "duration": 4, "aspect_ratio": "16:9", "generate_audio": true, "seed": 250628 }' ``` ### 2. 保存 UniAI 任务 ID 并等待完成 使用创建响应中的 `id` 或 `task_id` 查询，直到 `status` 为 `completed`。下方 `task_YOUR_COMPLETED_DRAFT` 是占位符，必须替换为你实际收到的 UniAI 任务 ID。 ```bash curl "https://api.uniall.ai/v1/videos/task_YOUR_COMPLETED_DRAFT" \ -H "Authorization: Bearer " ``` ### 3. 提交成片请求 父任务必须是同一 UniAI 用户创建、已完成的 Seedance 2.5 Draft，且自创建起未满七天。未完成、失败、过期、非 Draft 或其他用户的任务不能复用。 ```bash curl -X POST "https://api.uniall.ai/v1/videos" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.5", "draft_task_id": "task_YOUR_COMPLETED_DRAFT", "output_format": "mov", "watermark": false, "return_last_frame": true, "priority": 0 }' ``` 成片默认使用 `1080p`，也可显式指定 `resolution: "1080p"`；其他分辨率会拒绝。成功提交后会返回新的成片任务 ID，按同样方式轮询。 成片继承原 Draft 的提示词、所有素材、时长、画幅、`seed`、`generate_audio` 及任务类型。请省略这些继承字段，不要重复发送相同值或尝试覆盖；`tools`、`operation` 和 `omni_reference_task_type` 也必须省略。原始 `content` 不可重复传入，即使 `generate_audio` 为 `false` 也不要重传。 可以单独设置 `output_format`、`watermark`、`return_last_frame`、`priority`、`execution_expires_after` 和 `safety_identifier`，但不能设置 `draft: true`。 也兼容仅包含一条 Draft 引用的 `content` 写法： ```json { "model": "seedance2.5", "content": [ { "type": "draft_task", "draft_task": { "id": "task_YOUR_COMPLETED_DRAFT" } } ] } ``` 该 `id` 同样必须使用 UniAI 返回的公开任务 ID。不要与其他文本或媒体 part 混合；若同时传入 `draft_task_id`，两处 ID 必须一致。 ## 创建响应与任务生命周期 ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "seedance2.5", "status": "queued", "progress": 0, "created_at": 1792368000 } ``` 保存公开 `id` 或 `task_id`，建议每 2 到 5 秒调用 `GET /v1/videos/{task_id}`，直到 `status` 变为 `completed` 或 `failed`。完成后优先使用响应中的 `video_url` 下载视频；兼容响应也可能在 `result.video_url` 或 `result.outputs` 中提供结果。不要把结果 URL 当成永久存储。 普通任务也可按下方方式查询： ```bash curl "https://api.uniall.ai/v1/videos/task_YOUR_VIDEO" \ -H "Authorization: Bearer " ``` 如请求了 `return_last_frame: true`，完成时可读取返回的尾帧结果。1080p 视频使用 HEVC/10bit，需要兼容的播放器；MP4 和 MOV 是输出容器格式。 Seedance 2.5 请求失败、客户端超时或结果不确定时，不得自动重试创建请求。已拿到任务 ID 时继续查询原任务；没有任务 ID 时先核对原请求结果。Draft 转成片也遵守此规则。 公共状态字段、完成/失败响应和错误处理见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。本模型的禁止自动重试规则优先于通用重试建议。 ## 计费说明 以各任务返回的实际 Token 用量和最终结算记录为准，预扣仅为估算。Draft 和成片是两个独立计费的任务，样片不抵扣成片，也不会被重复计为成片的输入视频。当前价格以账号可见的 UniAll 价格为准。 ## 常见错误 | 错误 | 原因 | 处理方式 | | --- | --- | --- | | 缺少输入 | 既没有提示词，也没有媒体或有效 Draft 引用 | 提供对应工作流的必需输入。 | | 分辨率无效 | 4K，或 Draft/成片档位不匹配 | 普通请求使用 `480p`/`720p`/`1080p`，Draft 仅 `480p`，成片仅 `1080p`。 | | 兼容别名冲突 | `resolution` 和 `size` 的值不同 | 删除 `size` 或确保两者完全一致。 | | 编辑时长无效 | 编辑使用整数时长 | 省略 `duration` 或设为 `"auto"`/`-1`。 | | 画幅无效 | 首帧、首尾帧、编辑或延长请求使用固定比例 | 省略 `aspect_ratio` 或设为 `auto`。 | | 媒体数量超限 | 单类型或媒体总数超过限制 | 按文档限制减少媒体数量。 | | 素材不可访问 | URL 私有、过期或无法从公网访问 | 使用稳定公开 URL 或可用的 `asset://` 素材。 | | 联网工具无效 | `tools` 不是唯一支持的联网搜索结构 | 传 `[{"type":"web_search"}]` 或省略 `tools`。 | | 字段不支持 | 传入 `frames`、`camera_fixed` 或 `service_tier: "flex"` | 删除不支持字段。 | | Draft 引用无效 | 不存在、未完成、非 Draft、过期或属于其他用户 | 使用同用户未满七天的已完成 Draft 的 UniAI 任务 ID。 | | 成片继承字段重复 | 成片请求再次传入 prompt、素材、时长、比例、seed、音频或任务类型 | 省略所有继承字段，只发送 Draft ID 和允许的输出控制。 | | 参数类型或范围错误 | 布尔值写成字符串，或 priority、seed、过期时间超出范围 | 使用 JSON 布尔值和参数表规定的整数范围。 | ## 相关页面 - [视频生成概览](/zh-CN/models/video/overview) - [Seedance 2.0](/zh-CN/models/video/seedance-2-0) - [Seedance 素材库](/zh-CN/models/video/seedance-2-0/material-library) - [模型列表](/zh-CN/models) --- # Seedance 海外版 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/seedance-global Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/seedance-global.md Description: 通过 UniAll 视频 API 调用四个 Seedance 海外模型，支持文生视频、首尾帧和多模态参考。 通过 UniAll 视频 API 调用下列完整模型名称。`-global` 是模型名称的一部分。海外版支持文生视频、图生视频、首尾帧生成和多模态参考。 ## 支持模型 | 模型 | 分辨率 | 输出时长 | | --- | --- | --- | | `seedance2.0-global` | 480p、720p、1080p、4k | 4–15 秒 | | `seedance2.0-fast-global` | 480p、720p | 4–15 秒 | | `seedance2.0-mini-global` | 480p、720p | 4–15 秒 | | `seedance2.5-global` | 480p、720p、1080p | 4–30 秒 | ## 接口与鉴权 API 地址为 `https://api.uniall.ai`。 ```http POST /v1/videos GET /v1/videos/{task_id} GET /v1/videos/{task_id}/content ``` 每个请求都使用自己的 UniAll API Key： ```http Authorization: Bearer Content-Type: application/json ``` ## 请求参数 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | 上述四个完整模型名称之一。 | | `prompt` | string | 是 | 视频指令，也可改为在 content 中提供 type=text 项。 | | `resolution` | string | 是 | 所选模型支持的分辨率。 | | `duration` | integer | 是 | 所选模型范围内的输出时长，不支持自动时长。 | | `aspect_ratio` | string | 否 | auto、21:9、16:9、4:3、1:1、3:4 或 9:16。 | | `image` | string | 否 | 首帧图片 URL。单独使用时为图生视频，与 last_image 一起使用时为首尾帧生成。 | | `last_image` | string | 否 | 尾帧图片 URL，需同时提供首帧图片。 | | `images` | string[] | 否 | 多模态生成的参考图片 URL。 | | `videos` | string[] | 否 | 多模态生成的参考视频 URL。 | | `audios` | string[] | 否 | 多模态生成的参考音频 URL。 | | `content` | object[] | 否 | 结构化文本和参考媒体，见下方示例。 | | `generate_audio` | boolean | 否 | 是否生成音频，默认为 true；显式 false 会保留。 | | `seed` | integer | 否 | 随机种子。 | | `return_last_frame` | boolean | 否 | 仅 seedance2.5-global 支持，尽力返回生成视频的尾帧。2.0 系列请省略此字段。 | | `output_format` | string | 否 | 仅支持 mp4，默认为 mp4。 | 参数放在顶层。`size` 是 `resolution` 的兼容别名；`ratio` 是 `aspect_ratio` 的别名，其中 `adaptive` 等价于 `auto`。别名与标准字段同时传入时，值必须一致。 海外版不支持 `watermark`、Draft、视频编辑或延长、联网搜索及国内版的高级控制。不支持的字段即使值为 `false` 也应省略。 ## 文生视频示例 ```bash curl -X POST "https://api.uniall.ai/v1/videos" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "seedance2.0-global", "prompt": "A small sailboat crosses a calm lake at sunrise, with a slow cinematic camera movement.", "resolution": "720p", "duration": 5, "aspect_ratio": "16:9", "generate_audio": true }' ``` ## 图片与多模态参考 使用可公开访问的 HTTP(S) 媒体 URL。首尾帧请求可将以下请求体发送到 `POST /v1/videos`： ```json { "model": "seedance2.0-fast-global", "prompt": "Move smoothly from the first frame to the last frame while preserving the product appearance.", "resolution": "720p", "duration": 5, "image": "https://example.com/first.png", "last_image": "https://example.com/last.png", "generate_audio": false } ``` 多模态参考可使用 `images`、`videos`、`audios`，也可使用带明确媒体角色的结构化 `content`： ```json { "model": "seedance2.5-global", "resolution": "720p", "duration": 6, "content": [ { "type": "text", "text": "Animate the reference product using the camera movement in the reference video." }, { "type": "image_url", "image_url": { "url": "https://example.com/product.png" }, "role": "reference_image" }, { "type": "video_url", "video_url": { "url": "https://example.com/motion.mp4" }, "role": "reference_video" } ], "generate_audio": true } ``` | 模型系列 | 图片上限 | 视频上限 | 音频上限 | | --- | --- | --- | --- | | 2.0 海外版、Fast 海外版、Mini 海外版 | `9` | `3` | `3` | | 2.5 海外版 | `30` | `10` | `10` | 同一请求不能混用首尾帧输入与多模态参考。2.0 系列使用音频参考时，必须同时提供至少一张图片或一个视频。 ## 响应与任务结果 创建成功后返回任务对象，请保存公共任务 ID： ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "seedance2.0-global", "status": "queued", "progress": 0 } ``` 每隔 3–10 秒调用 `GET /v1/videos/{task_id}`，直到状态为 `completed` 或 `failed`。完整状态、结果字段和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。请及时下载返回的 `video_url`，结果链接可能过期。 超时或创建结果不确定时，不要自动重复提交。已返回任务 ID 时继续查询原任务，确认原请求结果后再决定是否重新创建。 ## 海外素材库 独立的海外素材接口尚待上线。开通前请使用普通 HTTP(S) 参考地址；以下为准备好的调用约定。 | 操作 | 方法 | 接口 | | --- | --- | --- | | 创建素材 | `POST` | `/v1/materials/global` | | 按 ID 查询素材 | `GET` | `/v1/materials/global/{id}` | | 删除素材 | `DELETE` | `/v1/materials/global/{id}` | 素材接口不传模型名称，不提供素材列表。创建时传入 URL、类型、可选名称和 `Idempotency-Key` 请求头： ```bash curl -X POST "https://api.uniall.ai/v1/materials/global" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "Idempotency-Key: global-reference-001" \ -d '{ "url": "https://example.com/product.png", "type": "image", "name": "product-reference" }' ``` `type` 支持 `image`、`video`、`audio`，`name` 最多保留 50 个字符。幂等键为 1–191 个不含空格的可见 ASCII 字符。重试保持相同键和请求体；上传结果不确定时不要换新键重新上传。 创建返回 HTTP 202 和 `gmat-*` ID。按 ID 查询，等 `status=available` 后，将返回的 `uri` 放入对应媒体字段： ```json { "id": "gmat-example", "object": "material", "type": "image", "name": "product-reference", "status": "available", "uri": "asset://gmat-example", "created_at": "2026-11-09T03:00:00+00:00" } ``` ```json { "model": "seedance2.0-global", "prompt": "Show the reference product turning slowly under soft studio lighting.", "resolution": "720p", "duration": 5, "image": "asset://gmat-example" } ``` 素材与视频请求使用同一个 UniAll 用户。国内素材 ID 不能用于海外版。四个海外模型间的素材复用以实际可用性为准，跨模型复用尚未验收；不承诺固定有效期。素材被生成任务引用时，需等任务结束后才能删除。 ## 计费说明 以 UniAll 中所选模型的当前价格为准。分辨率、时长和参考视频输入可能影响费用，最终以用量记录为准。 ## 常见错误 - 遗漏 `-global`，或将后缀放在错误位置。 - 缺少 `resolution`、`duration`，或传入 `duration: "auto"`。 - Fast/Mini 使用 `1080p`、`4k`，或 2.5 海外版使用 `4k`。 - 传入不支持的 `watermark`、`draft` 等字段。 - 混用首尾帧与多模态参考，或参考数量超限。 - 使用国内素材、其他用户的素材或尚未就绪的素材。 --- # Sora 2 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/sora-2 Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/sora-2.md Description: 通过 UniAll 视频 API 调用 Sora 2 模型生成视频。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 Sora 2 支持基于提示词的视频生成，并可选择参考图输入。来源范围同时包含 UniAll 视频生成接口和 OpenAI 原生兼容格式页面。 ## 支持模型 | 模型 | 说明 | | --- | --- | | `sora2-landscape-4s` | 横版输出，4 秒。 | | `sora2-landscape-8s` | 横版输出，8 秒。 | | `sora2-landscape-12s` | 横版输出，12 秒。 | | `sora2-portrait-4s` | 竖版输出，4 秒。 | | `sora2-portrait-8s` | 竖版输出，8 秒。 | | `sora2-portrait-12s` | 竖版输出，12 秒。 | | `sora2-pro-720p` | Pro 公共模型，720p。 | | `sora2-pro-1080p` | Pro 公共模型，1080p。 | | `sora2-pro-true-1080p` | 账号启用时可用的 Pro true-1080p 模型。 | ## Endpoint ```http POST /v1/video/generations GET /v1/videos/{task_id} ``` 来源还包含原生 OpenAI 格式页面，供需要 OpenAI 兼容请求格式的客户端使用。 ## Authentication ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## 请求参数 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | Sora 2 模型 ID。 | | `prompt` | string | 是 | 视频提示词。 | | `image_url` | string | 否 | 公开可访问的参考图 URL。 | | `aspect_ratio` | string | 否 | `16:9` 或 `9:16`。 | | `duration` | integer/string | 否 | 来源描述列出 `4`、`8`、`12`、`16`、`20`；模型名本身可能已编码时长。 | ## 请求示例 ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "sora2-portrait-12s", "prompt": "A cat running through grass", "image_url": "https://example.com/image.jpg" }' ``` ## 提交响应 ```json { "id": "gen_xxxxxxxxxxxx", "object": "video.generation.job", "model": "sora2", "status": "queued", "progress": 0, "created_at": 1770405483, "seconds": "12" } ``` ## 任务状态与结果 创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。 ## 计费说明 Sora 2 计费与模型、时长、横竖版、分辨率以及是否使用 Pro 模型有关。当前模型价格和任务结算记录是最终依据。 ## 常见错误 - 传入不支持的 Sora 2 模型 ID。 - `image_url` 私有或已过期。 - `aspect_ratio` 与 landscape 或 portrait 模型名冲突。 - 任务仍在队列中就当作完成处理。 - 在同一请求里混用 UniAll 任务格式和原生 OpenAI 格式。 ## 相关页面 - [视频生成概览](/zh-CN/models/video/overview) - [Wan 2.6 视频生成](/zh-CN/models/video/wan-2-6) - [模型列表](/zh-CN/models) --- # 创建视频生成任务 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/sora-2/create-task Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/sora-2/create-task.md Description: Sora 2 创建视频生成任务接口。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 ## 说明 新增sora2 Pro 公共模型`sora2-pro-720p`,`sora2-pro-1080p`,`sora2-pro-true-1080p` ## Endpoint ```http POST /v1/video/generations ``` ## Header 参数 | Name | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `Authorization` | string | No | | Bearer {your_token} | ## 请求体参数 | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | | `model` | string | Yes | 模型名称 | 可选：sora2-landscape-4s，sora2-landscape-8s，sora2-landscape-12s，sora2-portrait-4s，sora2-portrait-8s，sora2-portrait-12s, sora2-pro-720p, sora2-pro-1080p | | `prompt` | string | Yes | 提示词 | | | `image_url` | string | Yes | 参考图URL | 必须是公开可访问的URL图片链接 | | `aspect_ratio` | string | No | 画幅比例 | “16:9”, "9:16" | | `duration` | string | No | 输出描述 | 4, 8, 12, 16, 20 | ## 请求示例 ### 示例 1 ```json { "model": "sora2-portrait-12s", "prompt": "一只猫在草地上奔跑", "image_url": "https://example.com/image.jpg" // 可选 } ``` ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "sora2-portrait-12s", "prompt": "一只猫在草地上奔跑", "image_url": "https://example.com/image.jpg" // 可选 }' ``` ## 响应字段 | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | | `id` | string | Yes | 任务ID | | | `object` | string | Yes | 任务类型 | | | `model` | string | Yes | 模型名称 | | | `status` | string | Yes | 状态 | | | `progress` | string | Yes | 进度 | | | `created_at` | string | Yes | 创建时间 | | | `seconds` | string | Yes | 秒数 | | ## 响应示例 ### 示例 1 ```json { "id": "gen_xxxxxxxxxxxx", "object": "video.generation.job", "model": "sora2", "status": "queued", "progress": 0, "created_at": 1770405483, "seconds": "12" } ``` ## 任务状态与结果 创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。 --- # 原生 OpenAI 格式 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/sora-2/openai-format Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/sora-2/openai-format.md Description: Sora 2 原生 OpenAI 格式接口。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 ## Endpoint ```http POST /v1/chat/completions ``` ## Header 参数 | Name | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `Authorization` | string | No | | Bearer {your_token} | ## 请求体参数 | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | | `model` | string | Yes | 模型名称 | 可选：sora2-landscape-4s，sora2-landscape-8s，sora2-landscape-12s，sora2-portrait-4s，sora2-portrait-8s，sora2-portrait-12s | ## 请求示例 ### 示例 1 ```json // 文生视频 { "model": "sora2-landscape-4s", "messages": [ { "role": "user", "content": "一只猫在草地奔跑" } ], "stream": true } // 图生视频 { "model": "sora2-landscape-4s", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "让图中的人物动起来" }, { "type": "image_url", "image_url": { "url": "https://example.com/portrait.jpg" } } ] } ], "stream": true } ``` ```bash curl -X POST "{BASE_URL}/v1/chat/completions" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '// 文生视频 { "model": "sora2-landscape-4s", "messages": [ { "role": "user", "content": "一只猫在草地奔跑" } ], "stream": true } // 图生视频 { "model": "sora2-landscape-4s", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "让图中的人物动起来" }, { "type": "image_url", "image_url": { "url": "https://example.com/portrait.jpg" } } ] } ], "stream": true }' ``` ## 响应字段 | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | ## 响应示例 ### 示例 1 ```json { "id": "xxxxxxxxxxxxxxxxxxxxx", "object": "chat.completion.chunk", "created": 1770408254, "model": "sora2", "choices": [ { "index": 0, "delta": { "content": "\n\n✅ **视频生成完成！**\n\n**视频链接**: https://xxxx.xxxx.cn/xxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.mp4\n**任务用时**: 127秒\n" }, "finish_reason": null } ] } ``` ### 示例 2 ```json { "id": "chatcmpl-b5e9c8b352cc4dcc81815884ab943", "object": "chat.completion.chunk", "created": 1770408254, "model": "sora2", "choices": [ { "index": 0, "delta": { "content": "\n🖼️ 正在处理输入内容... (50%)" }, "finish_reason": null } ] } ``` --- # Veo 3.1 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/veo-3-1 Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/veo-3-1.md Description: 通过 UniAll 视频 API 调用 Veo 3.1 模型生成视频。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 Veo 3.1 支持文生视频、图生视频、首尾帧、多图参考和视频续写。公共模型名同时表达分辨率和速度档位。 ## 支持模型 | 模型 | 档位 | | --- | --- | | `veo3.1-video-720p` | 标准 720p。 | | `veo3.1-video-1080p` | 标准 1080p。 | | `veo3.1-video-4k` | 标准 4K。 | | `veo3.1-fast-video-720p` | 快速 720p。 | | `veo3.1-fast-video-1080p` | 快速 1080p。 | | `veo3.1-fast-video-4k` | 快速 4K。 | ## Endpoint ```http POST /v1/video/generations GET /v1/videos/{task_id} ``` ## Authentication ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## 请求参数 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | Veo 3.1 公共模型 ID。 | | `prompt` | string | 强烈建议 | 主提示词。Schema 不强制，但生产请求应传。 | | `image` | string | 条件必填 | 图生视频的单张源图 URL。 | | `images` | string[] | 条件必填 | 多图参考生视频，`2` 到 `3` 张图。 | | `last_image` | string | 条件必填 | 目标尾帧图 URL，与 `image` 配合使用。 | | `video` | string | 条件必填 | 视频续写的源视频 URL。 | | `size` | string | 建议 | 分辨率提示，应与所选模型档位一致。 | | `aspect_ratio` | string | 否 | 文生视频允许 `16:9` 或 `9:16`；图生和续写不一定生效。 | | `duration` | integer | 条件必填 | 输出秒数，允许值为 `4`、`6`、`8`；视频续写不使用。 | | `extra_body.generate_audio` | boolean | 否 | 是否生成声音，上游通常默认 `true`。 | | `extra_body.negative_prompt` | string | 否 | 不希望出现的内容。 | | `extra_body.seed` | integer | 否 | 随机种子。 | ## 文生视频示例 ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "veo3.1-video-1080p", "prompt": "A golden-hour street interview shot, slight handheld movement, natural city ambience, realistic human speech.", "size": "1080p", "aspect_ratio": "16:9", "duration": 8, "extra_body": { "generate_audio": true, "negative_prompt": "watermark, blur", "seed": 7 } }' ``` ## 图生视频示例 ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "veo3.1-video-720p", "prompt": "A product slowly rotates on a clean studio desk with soft reflected light.", "image": "https://example.com/keyframe.png", "size": "720p", "aspect_ratio": "16:9", "duration": 6, "extra_body": { "generate_audio": false, "negative_prompt": "artifacts, camera shake" } }' ``` ## 首尾帧示例 ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "veo3.1-fast-video-1080p", "prompt": "Transition naturally from the first frame to the last frame, preserving subject identity and camera continuity.", "image": "https://example.com/start-frame.png", "last_image": "https://example.com/end-frame.png", "size": "1080p", "aspect_ratio": "16:9", "duration": 6 }' ``` ## 任务状态与结果 创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。 ## 计费说明 Veo 计费与模型档位、速度档、分辨率、输出时长和是否生成音频有关。最终以任务结算记录和当前产品价格为准。 ## 常见错误 - `duration` 不在 `4`、`6`、`8` 允许值中。 - `size` 与所选模型档位不一致。 - 期望图生视频或续写一定遵循 `aspect_ratio`。 - 参考图超过 `3` 张。 - 传入 `video` 但没有通过提示词或扩展字段说明续写意图。 ## 相关页面 - [视频生成概览](/zh-CN/models/video/overview) - [Kling 视频生成](/zh-CN/models/video/kling) - [Vidu 视频生成](/zh-CN/models/video/vidu) --- # 创建视频生成任务 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/veo-3-1/create-task Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/veo-3-1/create-task.md Description: Veo 3.1 创建视频生成任务接口。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 ## 说明 | 公共模型名 | 当前支持的视频生成能力 | |---|---| | `veo3.1-video-720p` | 文生视频、单图生视频、首尾帧、多图参考生视频、视频续写 | | `veo3.1-video-1080p` | 文生视频、单图生视频、首尾帧、多图参考生视频、视频续写 | | `veo3.1-video-4k` | 文生视频、单图生视频、首尾帧、多图参考生视频、视频续写 | | `veo3.1-fast-video-720p` | 文生视频、单图生视频、首尾帧、视频续写 | | `veo3.1-fast-video-1080p` | 文生视频、单图生视频、首尾帧、视频续写 | | `veo3.1-fast-video-4k` | 文生视频、单图生视频、首尾帧、视频续写 | ## Endpoint ```http POST /v1/video/generations ``` ## Query 参数 | Name | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `Authorization` | string | No | | Bearer {your_token} | ## 请求体参数 | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | | `model` | string | Yes | 公共模型名 | | | `prompt` | string | Yes | 主提示词 | 结构上不是绝对必填，但实际强烈建议传 | | `image` | string | Yes | 单张源图 URL | 图生视频 | | `images` | string | Yes | 多张参考图 URL 列表 | 2 到 3 张图会触发多图参考生视频 | | `last_image` | string | Yes | 目标尾帧图 URL | 首尾帧，与image配合使用 | | `video` | string | Yes | 源视频 UR | 触发视频续写 | | `size` | string | Yes | 分辨率提示 | 必须与所选公共模型档位保持一致 | | `aspect_ratio` | string | Yes | 输出比例 | 文生视频允许值：`16:9`、`9:16`；图生视频，视频续写不使用，可传输出不保证效果 | | `duration` | string | Yes | 输出时长，单位秒 | 允许值：`4`、`6`、`8`；视频续写不使用 | | `extra_body` | object | Yes | 扩展字段 | | ## 请求示例 ### 文生视频 ```json { "model": "veo3.1-video-1080p", "prompt": "黄金时刻的街头采访镜头，镜头轻微手持晃动，人物真实发声，环境中有自然城市背景音。", "size": "1080p", "aspect_ratio": "16:9", "duration": 8, "extra_body": { "generate_audio": true, "negative_prompt": "水印, 模糊", "seed": 7 } } ``` ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "veo3.1-video-1080p", "prompt": "黄金时刻的街头采访镜头，镜头轻微手持晃动，人物真实发声，环境中有自然城市背景音。", "size": "1080p", "aspect_ratio": "16:9", "duration": 8, "extra_body": { "generate_audio": true, "negative_prompt": "水印, 模糊", "seed": 7 } }' ``` ### 单图生视频 ```json { "model": "veo3.1-video-720p", "prompt": "商品在干净的摄影棚桌面上缓慢旋转，伴随柔和反射光。", "image": "https://example.com/keyframe.png", "size": "720p", "aspect_ratio": "16:9", "duration": 6, "extra_body": { "generate_audio": false, "negative_prompt": "伪影, 抖动" } } ``` ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "veo3.1-video-720p", "prompt": "商品在干净的摄影棚桌面上缓慢旋转，伴随柔和反射光。", "image": "https://example.com/keyframe.png", "size": "720p", "aspect_ratio": "16:9", "duration": 6, "extra_body": { "generate_audio": false, "negative_prompt": "伪影, 抖动" } }' ``` ### 首尾帧 ```json { "model": "veo3.1-fast-video-1080p", "prompt": "让画面从首帧自然过渡到尾帧，保持主体身份一致、镜头语言连贯。", "image": "https://example.com/start-frame.png", "last_image": "https://example.com/end-frame.png", "size": "1080p", "aspect_ratio": "16:9", "duration": 6, "extra_body": { "generate_audio": true } } ``` ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "veo3.1-fast-video-1080p", "prompt": "让画面从首帧自然过渡到尾帧，保持主体身份一致、镜头语言连贯。", "image": "https://example.com/start-frame.png", "last_image": "https://example.com/end-frame.png", "size": "1080p", "aspect_ratio": "16:9", "duration": 6, "extra_body": { "generate_audio": true } }' ``` ### 多图参考一致性生视频 ```json { "model": "veo3.1-video-1080p", "prompt": "保持同一角色的脸、服装和身份一致，在雨夜小巷中向前行走。", "images": [ "https://example.com/ref-1.png", "https://example.com/ref-2.png" ], "size": "1080p", "aspect_ratio": "9:16", "duration": 6, "extra_body": { "generate_audio": true, "seed": 11 } } ``` ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "veo3.1-video-1080p", "prompt": "保持同一角色的脸、服装和身份一致，在雨夜小巷中向前行走。", "images": [ "https://example.com/ref-1.png", "https://example.com/ref-2.png" ], "size": "1080p", "aspect_ratio": "9:16", "duration": 6, "extra_body": { "generate_audio": true, "seed": 11 } }' ``` ### 视频续写 ```json { "model": "veo3.1-video-720p", "prompt": "自然续接原视频中的动作，并保持同样的场景风格。", "video": "https://example.com/source.mp4", "size": "720p", "duration": 6, "extra_body": { "negative_prompt": "闪烁, 故障感", "seed": 9 } } ``` ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "veo3.1-video-720p", "prompt": "自然续接原视频中的动作，并保持同样的场景风格。", "video": "https://example.com/source.mp4", "size": "720p", "duration": 6, "extra_body": { "negative_prompt": "闪烁, 故障感", "seed": 9 } }' ``` ## 响应字段 | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | ## 响应示例 ### 示例 1 ```json {} ``` ## 任务状态与结果 创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。 --- # Vidu Q3 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/vidu Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/vidu.md Description: 通过 UniAll 调用 Vidu Q3 系列，创建文生、单图、首尾帧和多参考图视频。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 更新时间：2026-08-04 ## 概览 Vidu Q3 系列只使用两个稳定公共模型名，通过请求体顶层的 `resolution` 参数选择输出分辨率，不再把分辨率写进模型名。 | 公共模型 | 系列 | 文生视频 | 单图生视频 | 首尾帧 | 多参考图 | | --- | --- | --- | --- | --- | --- | | `viduq3p` | Q3 Pro | 支持 | 支持 | 支持 | 支持 1 至 4 张 | | `viduq3t` | Q3 Turbo | 支持 | 支持 | 支持 | 支持 1 至 4 张 | 两个模型均支持 `540p`、`720p` 和 `1080p`，这两个 ID 是 Vidu Q3 对外唯一保留的公共模型名。 ## 适用场景 Vidu Q3 适合以下任务： - 根据文字提示词生成视频； - 让一张可公开访问的图片动起来； - 根据首帧和尾帧生成连续视频； - 使用 1 至 4 张参考图约束人物、主体或视觉风格。 客户端只需选择公共模型并传入请求参数。不要传入渠道名、上游模型名、上游任务字段或路由控制参数。 ## 接口 新接入统一使用以下接口： | 用途 | 方法 | 路径 | | --- | --- | --- | | 创建视频任务 | `POST` | `/v1/videos` | | 查询视频任务 | `GET` | `/v1/videos/{task_id}` | | 下载视频文件 | `GET` | `/v1/videos/{task_id}/content` | 以下兼容接口仍可使用： | 用途 | 方法 | 路径 | | --- | --- | --- | | 创建视频任务 | `POST` | `/v1/videos/generations` | | 查询视频任务 | `GET` | `/v1/videos/generations/{task_id}` | | 创建视频任务 | `POST` | `/v1/video/generations` | | 查询视频任务 | `GET` | `/v1/video/generations/{task_id}` | 新接入建议统一使用 `/v1/videos`。 ## 鉴权 所有请求均使用 UniAll Bearer Token： ```http Authorization: Bearer sk-*** ``` 创建任务时还需发送： ```http Content-Type: application/json ``` ## 请求体参数 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | `viduq3p` 或 `viduq3t`。 | | `prompt` | string | 是 | 视频生成提示词。 | | `duration` | integer | 是 | 输出时长，范围为 `1` 至 `16` 秒。 | | `aspect_ratio` | string | 否 | `16:9`、`9:16`、`3:4`、`4:3` 或 `1:1`。 | | `image` | string | 条件必填 | 单图模式的输入图或首尾帧模式的首帧，必须是公开可访问的 HTTP(S) URL。 | | `last_image` | string | 条件必填 | 尾帧图片的公开 HTTP(S) URL，必须与 `image` 一起传入。 | | `reference_image_urls` | string[] | 条件必填 | 多参考图模式的 1 至 4 个公开 HTTP(S) 图片 URL。 | | `resolution` | string | 是 | `540p`、`720p` 或 `1080p`。 | | `audio` | boolean | 否 | 是否生成声音。 | | `bgm` | boolean | 否 | 文生视频的背景音乐控制。 | | `seed` | integer | 否 | 随机种子。 | 根据生成模式选择输入字段： | 模式 | 输入字段 | | --- | --- | | 文生视频 | `prompt` | | 单图生视频 | `prompt` + `image` | | 首尾帧生视频 | `prompt` + `image` + `last_image` | | 多参考图生视频 | `prompt` + `reference_image_urls` | 字段约束： - 每次请求都必须传入顶层 `resolution`。 - `image` 与 `reference_image_urls` 不能同时传入。 - `last_image` 不能单独使用，必须与 `image` 组成首尾帧。 - 首尾帧和多参考图模式不要使用 `images` 或 `image_urls`。 - `resolution`、`audio`、`bgm` 和 `seed` 都直接放在请求体顶层，不要包在 `extra_body` 中。 - `size` 不是 `resolution` 的兼容别名。 ## 请求示例 ### 文生视频 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "viduq3p", "prompt": "A cinematic aerial shot over a futuristic coastal city at sunrise, soft light, slow camera push-in.", "duration": 5, "aspect_ratio": "16:9", "resolution": "720p", "audio": false, "bgm": false, "seed": 42 }' ``` ### 单图生视频 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "viduq3t", "prompt": "The person slowly raises their head and looks at the camera while the camera gently moves forward.", "image": "https://example.com/source.png", "duration": 5, "aspect_ratio": "9:16", "resolution": "540p", "audio": false, "seed": 42 }' ``` ### 首尾帧生视频 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "viduq3p", "prompt": "The person turns naturally from a front view to a side view while identity and motion remain consistent.", "image": "https://example.com/head.png", "last_image": "https://example.com/tail.png", "duration": 6, "aspect_ratio": "16:9", "resolution": "720p", "audio": false, "seed": 42 }' ``` ### 多参考图生视频 ```bash curl -X POST "{BASE_URL}/v1/videos" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "viduq3p", "prompt": "A @Image1 walking through a beach in the visual style of @Image2", "reference_image_urls": [ "https://example.com/ref-1.png", "https://example.com/ref-2.png" ], "duration": 5, "aspect_ratio": "16:9", "resolution": "1080p", "audio": false, "seed": 42 }' ``` 两个公共模型都支持 `reference_image_urls`。参考图提示词可以按数组顺序使用 `@Image1`、`@Image2` 等标记。 ## 响应示例 ### 任务创建成功 请保存 `id` 或兼容字段 `task_id`，用于后续查询： ```json { "id": "task_xxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "viduq3p", "status": "queued", "progress": 0, "created_at": 1785772800 } ``` 公共响应不会返回渠道标识、上游任务 ID、凭证信息或上游原始响应。 ## 任务状态与结果 创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。 ## 计费说明 计费取决于公共模型、请求的 `resolution` 和实际输出视频秒数。模型名本身不承载分辨率或时段计费档位。 百度 VOD/BV 渠道当前正常时段的参考消耗如下，适用于文生视频、单图生视频和首尾帧视频： | 公共模型 | `540p` | `720p` | `1080p` | | --- | ---: | ---: | ---: | | `viduq3p`（Q3 Pro） | 0.28125 元/秒 | 0.625 元/秒 | 0.75 元/秒 | | `viduq3t`（Q3 Turbo） | 0.21875 元/秒 | 0.375 元/秒 | 0.40625 元/秒 | 渠道消耗 = 单价 × 实际输出时长。多参考图请求可能选择其他符合条件的渠道，不能直接套用这张百度 VOD 表。最终对外价格和结算以 UniAll 模型页及消费日志为准。 ## 常见错误 以下情况会在任务创建前被拒绝： - 使用 `viduq3p` 或 `viduq3t` 之外的模型名； - 缺少 `resolution`，或传入 `540p`、`720p`、`1080p` 以外的值； - 使用 `size` 代替 `resolution`； - 缺少 `duration`，或传入 `1` 至 `16` 之外的值； - 使用 `21:9`、`1920x1080` 等不支持的画幅比例； - `reference_image_urls` 为空或超过 4 张； - 同时传入 `image` 与 `reference_image_urls`，或单独传入 `last_image`； - 图片 URL 无法由服务端公开访问； - 把支持的顶层参数放进 `extra_body`。 ## 相关页面 - [视频生成概览](/zh-CN/models/video/overview) - [模型列表](/zh-CN/models) --- # Wan 2.6 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/wan-2-6 Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/wan-2-6.md Description: 通过 UniAll 视频 API 调用 Wan 2.6 模型生成视频。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 Wan 2.6 覆盖文生视频、图生视频和参考生视频模型家族。来源范围还包含 Wan 2.6 公共模型秒数参照表。 ## 支持模型 | 模型 | 类型 | 秒数规则 | | --- | --- | --- | | `wan2.6-video-720p` | 文生视频 / 图生视频 | 必传；`5`、`10` 或 `15`。 | | `wan2.6-video-1080p` | 文生视频 / 图生视频 | 必传；`5`、`10` 或 `15`。 | | `wan2.6-i2v-flash-720p-audio` | 图生视频有声 | 必传；`5` 到 `15` 的任意整数。 | | `wan2.6-i2v-flash-720p-silent` | 图生视频无声 | 必传；`5` 到 `15` 的任意整数。 | | `wan2.6-i2v-flash-1080p-audio` | 图生视频有声 | 必传；`5` 到 `15` 的任意整数。 | | `wan2.6-i2v-flash-1080p-silent` | 图生视频无声 | 必传；`5` 到 `15` 的任意整数。 | | `wan2.6-r2v-720p` | 参考生视频 | 必传；以账号模型配置为准。 | | `wan2.6-r2v-1080p` | 参考生视频 | 必传；以账号模型配置为准。 | | `wan2.6-r2v-flash-720p-audio` | 参考生视频有声 | 必传；以账号模型配置为准。 | | `wan2.6-r2v-flash-720p-silent` | 参考生视频无声 | 必传；以账号模型配置为准。 | | `wan2.6-r2v-flash-1080p-audio` | 参考生视频有声 | 必传；以账号模型配置为准。 | | `wan2.6-r2v-flash-1080p-silent` | 参考生视频无声 | 必传；以账号模型配置为准。 | ## Endpoint ```http POST /v1/video/generations GET /v1/videos/{task_id} ``` ## Authentication ```http Authorization: Bearer sk-*** Content-Type: application/json ``` ## 请求参数 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | Wan 2.6 模型 ID。 | | `prompt` | string | 是 | 提示词。 | | `image` | string | 条件必填 | 图生视频参考图。 | | `images` | string[] | 条件必填 | R2V 模型参考图。 | | `videos` | string[] | 条件必填 | R2V 模型参考视频。 | | `duration` | integer | 是 | 参照支持模型表。 | | `size` | string | 否 | 输出尺寸。文生视频可用它控制横版或竖版；图生视频跟随参考图方向。 | | `extra_body.negative_prompt` | string | 否 | 不希望出现的内容。 | | `extra_body.shot_type` | string | 否 | `single` 或 `multi`。 | | `extra_body.seed` | integer | 否 | `-1` 表示随机；固定值更利于复现。 | | `extra_body.audio` | string | 否 | 公开可访问的音频 URL。 | | `extra_body.enable_prompt_expansion` | boolean | 否 | R2V 模型提示词扩展开关。 | 常见 `size` 包括 `1280*720`、`720*1280`、`1920*1080` 和 `1080*1920`。 ## 文生视频示例 ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "wan2.6-video-1080p", "prompt": "sunrise", "duration": 5, "size": "1080*1920", "extra_body": { "negative_prompt": "blur, watermark", "shot_type": "multi", "seed": -1 } }' ``` ## 参考视频示例 ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "wan2.6-r2v-flash-720p-audio", "prompt": "Keep the same subject identity and cinematic style, generate a faster-paced new shot.", "videos": [ "https://example.com/reference-shot-1.mp4" ], "size": "1280*720", "duration": 5, "extra_body": { "negative_prompt": "watermark, blur, flicker", "audio": "https://example.com/guide-audio.mp3", "shot_type": "single", "enable_prompt_expansion": false, "seed": -1 } }' ``` ## 多图参考示例 ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "wan2.6-r2v-flash-1080p-silent", "prompt": "Keep the same product identity and style, generate a clean marketing video.", "images": [ "https://example.com/ref-1.png", "https://example.com/ref-2.png" ], "size": "1920*1080", "duration": 10, "extra_body": { "negative_prompt": "watermark, blur", "shot_type": "multi", "enable_prompt_expansion": true, "seed": 42 } }' ``` ## 任务状态与结果 创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。 ## 计费说明 Wan 2.6 计费与模型家族、输出分辨率、时长、音频模式，以及任务是文生、图生还是参考生视频有关。最终以结算记录为准。 ## 常见错误 - 使用所选模型不允许的秒数。 - 期望图生视频通过 `size` 控制横竖版；图生通常跟随参考图方向。 - 传入私有媒体 URL。 - 用非 R2V 模型传 R2V 字段。 - 静音模型中传入 `audio`。 ## 相关页面 - [视频生成概览](/zh-CN/models/video/overview) - [Vidu 视频生成](/zh-CN/models/video/vidu) - [Sora 2 视频生成](/zh-CN/models/video/sora-2) --- # 创建视频生成任务 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/wan-2-6/create-task Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/wan-2-6/create-task.md Description: Wan 2.6 创建视频生成任务接口。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 ## Endpoint ```http POST /v1/video/generations ``` ## Header 参数 | Name | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `Authorization` | string | No | | Bearer {your_token} | ## 请求体参数 | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | | `model` | string | Yes | 模型名称 | “wan2.6-video-720p”，“wan2.6-video-1080p” | | `prompt` | string | Yes | 提示词 | | | `image` | string | Yes | 参考图 | | | `duration` | string | Yes | 秒数 | | | `size` | string | Yes | 产出视频尺寸 | "1280*720", "720*1280", "1920*1080", "1080*1920", 注意：文生视频时可选size控制横版竖版，图生视频时size参数无效，但仍然可以传入，但是产出视频横版竖版跟随参考图 | | `extra_body` | object | Yes | | | ## 请求示例 ### 示例 1 ```json { "model": "wan2.6-video-1080p", "prompt": "日出", "duration": 5, "size": "1080*1920", "extra_body": { "negative_prompt": "不要出现模糊, 不要出现水印", "shot_type": "multi", "seed": -1 } } ``` ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "wan2.6-video-1080p", "prompt": "日出", "duration": 5, "size": "1080*1920", "extra_body": { "negative_prompt": "不要出现模糊, 不要出现水印", "shot_type": "multi", "seed": -1 } }' ``` ## 响应字段 | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | ## 响应示例 ### 成功 ```json { "id": "task_xxxxxxxxxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxx", "object": "video.generation.job", "model": "wan2.6-video-1080p", "status": "in_progress", "progress": 5, "created_at": 1773984104 } ``` ## 任务状态与结果 创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。 --- # Wan 系列模型秒数参照表 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/wan-2-6/duration-table Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/wan-2-6/duration-table.md Description: Wan 模型秒数来源参照表。 ## WAN 2.6 | 公共模型 | 类型 | 秒数要求 | 当前允许值 | |---|---|---|---| | `wan2.6-video-720p` | 文生视频 / 图生视频 | 必传 | `5`、`10`、`15` | | `wan2.6-video-1080p` | 文生视频 / 图生视频 | 必传 | `5`、`10`、`15` | | `wan2.6-i2v-flash-720p-audio` | 图生视频 有声 | 必传 | `5` 到 `15` 的任意整数 | | `wan2.6-i2v-flash-720p-silent` | 图生视频 无声 | 必传 | `5` 到 `15` 的任意整数 | | `wan2.6-i2v-flash-1080p-audio` | 图生视频 有声 | 必传 | `5` 到 `15` 的任意整数 | | `wan2.6-i2v-flash-1080p-silent` | 图生视频 无声 | 必传 | `5` 到 `15` 的任意整数 | | `wan2.6-r2v-720p` | 参考生视频 | 必传 | `5`、`10` | | `wan2.6-r2v-1080p` | 参考生视频 | 必传 | `5`、`10` | | `wan2.6-r2v-flash-720p-audio` | 参考生视频 有声 | 必传 | `5`、`10` | | `wan2.6-r2v-flash-720p-silent` | 参考生视频 无声 | 必传 | `5`、`10` | | `wan2.6-r2v-flash-1080p-audio` | 参考生视频 有声 | 必传 | `5`、`10` | | `wan2.6-r2v-flash-1080p-silent` | 参考生视频 无声 | 必传 | `5`、`10` | ## 一句话总结 - `wan2.6-video-*`：`5 / 10 / 15` - `wan2.6-i2v-flash-*`：`5~15` 任意整数 - `wan2.6-r2v-*`：`5 / 10` - `wan2.6-r2v-flash-*`：`5 / 10` --- # Wan 2.6 R2V 系列创建视频任务 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/wan-2-6/r2v-create-task Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/wan-2-6/r2v-create-task.md Description: Wan 2.6 R2V 创建视频任务接口。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 ## Endpoint ```http POST /v1/video/generations ``` ## 请求体参数 | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | | `model` | string | No | Example field | Appears in a request example; no separate field description is provided. | | `prompt` | string | No | Example field | Appears in a request example; no separate field description is provided. | | `videos` | array | No | Example field | Appears in a request example; no separate field description is provided. | | `size` | string | No | Example field | Appears in a request example; no separate field description is provided. | | `duration` | number | No | Example field | Appears in a request example; no separate field description is provided. | | `extra_body` | object | No | Example field | Appears in a request example; no separate field description is provided. | | `images` | array | No | Example field | Appears in a request example; no separate field description is provided. | ## 请求示例 ### 示例 1：视频参考 ```json { "model": "wan2.6-r2v-flash-720p-audio", "prompt": "保持相同主体身份与电影感风格，生成一段更快节奏的新镜头。", "videos": [ "https://example.com/reference-shot-1.mp4" ], "size": "1280*720", "duration": 5, "extra_body": { "negative_prompt": "watermark, blur, flicker", "audio": "https://example.com/guide-audio.mp3", "shot_type": "single", "enable_prompt_expansion": false, "seed": -1 } } ``` ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "wan2.6-r2v-flash-720p-audio", "prompt": "保持相同主体身份与电影感风格，生成一段更快节奏的新镜头。", "videos": [ "https://example.com/reference-shot-1.mp4" ], "size": "1280*720", "duration": 5, "extra_body": { "negative_prompt": "watermark, blur, flicker", "audio": "https://example.com/guide-audio.mp3", "shot_type": "single", "enable_prompt_expansion": false, "seed": -1 } }' ``` ### 示例 2：多图参考 ```json { "model": "wan2.6-r2v-flash-1080p-silent", "prompt": "保持相同产品身份与风格，生成一段干净的营销视频。", "images": [ "https://example.com/ref-1.png", "https://example.com/ref-2.png" ], "size": "1920*1080", "duration": 10, "extra_body": { "negative_prompt": "watermark, blur", "shot_type": "multi", "enable_prompt_expansion": true, "seed": 42 } } ``` ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "wan2.6-r2v-flash-1080p-silent", "prompt": "保持相同产品身份与风格，生成一段干净的营销视频。", "images": [ "https://example.com/ref-1.png", "https://example.com/ref-2.png" ], "size": "1920*1080", "duration": 10, "extra_body": { "negative_prompt": "watermark, blur", "shot_type": "multi", "enable_prompt_expansion": true, "seed": 42 } }' ``` ## 响应字段 | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | ## 响应示例 ### 示例 1 ```json {} ``` ## 任务状态与结果 创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。 --- # Wan 2.2 Animate 视频编辑 Locale: zh-CN URL: https://docs.uniall.ai/zh-CN/models/video/wan-2-6/wan-2-2-animate Source: i18n/zh-CN/docusaurus-plugin-content-docs/current/models/video/wan-2-6/wan-2-2-animate.md Description: Wan 2.2 Animate 视频编辑接口。 本页示例中的 `{BASE_URL}` 表示 `https://api.uniall.ai`。 ## 说明 它支持两种工作模式： - `animate` - 用输入视频里的动作，驱动输入图片中的人物或主体动起来 - `replace` - 用输入图片中的人物或主体，替换输入视频里的主体 换成更直白的话： - `animate` 更接近“动作驱动 / 动作替换” - `replace` 更接近“视频换人 / 角色替换” ## Endpoint ```http POST /v1/video/generations ``` ## Header 参数 | Name | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `Authorization` | string | No | | Bearer {your_token} | ## 请求体参数 | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | | `model` | string | Yes | 公共模型名 | 使用 `wan2.2-animate-480p` 或 `wan2.2-animate-720p` | | `prompt` | string | Yes | 补充提示词 | 可选，但建议填写风格、场景、镜头意图 | | `image` | string | Yes | 参考图URL | 实际上建议必填 \| 源角色图片 \| 只能一张 | | `video` | string | Yes | 视频URL | 实际上建议必填 \| 源动作或替换视频 \| 只能一段 | | `duration` | string | Yes | 目标时长，单位秒 | 必填 | | `mode` | string | Yes | 工作模式 | 允许值：`animate`、`replace`（归一化字段，可不在extra_body中传递） | | `seed` | string | Yes | 随机种子 | 随机种子，（归一化字段，可不在extra_body中传递） | | `extra_body` | object | Yes | | | ## 请求示例 ### 示例 ```json { "model": "string", "prompt": "string", "image": "string", "video": "string", "duration": "string", "mode": "string", "seed": "string", "extra_body": { "mode": "string", "seed": "string" } } ``` ```bash curl -X POST "{BASE_URL}/v1/video/generations" \ -H "Authorization: Bearer sk-***" \ -H "Content-Type: application/json" \ -d '{ "model": "string", "prompt": "string", "image": "string", "video": "string", "duration": "string", "mode": "string", "seed": "string", "extra_body": { "mode": "string", "seed": "string" } }' ``` ## 响应字段 | Field | Type | Required | Title | Description | | --- | --- | --- | --- | --- | ## 响应示例 ### 示例 1 ```json {} ``` ## 任务状态与结果 创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/zh-CN/models/video/overview#视频任务生命周期)。