# Vipeak AI Model Guide API Documentation

- Version: 1.0
- Last updated: 2026-11-22T14:23:05.025Z
- Base URL: https://123vips.com

Base URL: https://123vips.com

This is the caller-facing source of truth for currently available models, request fields, media combinations, and result polling.

## Table of Contents

- [Authentication](#authentication)
- [Quick Start](#quick-start)
- [Mulerouter Routing](#mulerouter-routing)
- [Supported Models](#supported-models)
- [Reusable Media](#reusable-media)
- [Seedance 2.0 V3](#seedance-2-0-v3)
- [Seedream 5.0 Pro Image](#seedream-5-0-pro-image)
- [Qwen Image 3.0](#qwen-image-3-0)
- [W3.0 (w3.0-video)](#w3-0-w3-0-video)
- [W3.0-Pro (w3.0-video-pro)](#w3-0-pro-w3-0-video-pro)
- [W3.0-Prime (w3.0-video-prime)](#w3-0-prime-w3-0-video-prime)
- [W3.0-VSR-Prime (w3.0-video-prime-pro)](#w3-0-vsr-prime-w3-0-video-prime-pro)
- [Seedance 2.5 Video (seedance25)](#seedance-2-5-video-seedance25)
- [Seedance 2.5 Video (seedance-nsfw)](#seedance-2-5-video-seedance-nsfw)
- [Vega 1.0 Lite](#vega-1-0-lite)
- [Advanced Task Polling](#advanced-task-polling)
- [Z-Image Spicy Pro](#z-image-spicy-pro)
- [Qwen Image Edit Spicy](#qwen-image-edit-spicy)
- [Account Balance](#account-balance)
- [Billing](#billing)
- [Endpoints](#endpoints)

## Authentication

```http
Authorization: Bearer <user-token>
```

---

## Quick Start

1. Keep your API token on your server and send it as `Authorization: Bearer <user-token>`.
2. Query the model catalog with `GET /api/models` when you need machine-readable model metadata.
3. Query the account balance with `GET /api/v3/account/balance`; when using a sub token, read `token.remaining` for that token's quota.
4. Upload reusable media first when your model supports asset references, then use the returned asset id in generation requests.
5. Create a video or image task with one of the documented endpoints and keep the returned task id.
6. Poll the matching task endpoint until the status is `succeeded` or `failed`.
7. Download successful output promptly; temporary upstream media links may expire.

Base URL: https://123vips.com


---

## Mulerouter Routing

Generation requests are fulfilled by Mulerouter. The platform keeps a stable public API surface and maps every request to the matching Mulerouter model, so callers only ever send their Vipeak AI token.

| Public model | Platform provider | `videoCapability` / Mulerouter node | Result type |
|--------------|-------------------|-----------------------------------|-------------|
| W3.0 | `wan30` | `w3.0-video` | video |
| W3.0-Pro | `wan30` | `w3.0-video-pro` | video |
| W3.0-Prime | `wan30` | `w3.0-video-prime` | video |
| W3.0-VSR-Prime | `wan30` | `w3.0-video-prime-pro` | video |
| Z-Image Spicy Pro | — | `z-image-spicy-pro` | text-to-image |
| Qwen Image Edit Spicy | — | `qwen-image-edit-spicy` | image edit |

---

## Supported Models

| Model | Model / Provider | Capability | Create | Result |
| --- | --- | --- | --- | --- |
| Seedance 2.0 Standard | dreamina-seedance-2-0-260128 | - | /api/v3/contents/generations/tasks | /api/v3/contents/generations/tasks/<taskId> |
| Seedance 2.0 Fast | dreamina-seedance-2-0-fast-260128 | - | /api/v3/contents/generations/tasks | /api/v3/contents/generations/tasks/<taskId> |
| W3.0 | wan30 | w3.0-video | /api/advanced/generate | /api/generation-records/<taskId> |
| W3.0-Pro | wan30 | w3.0-video-pro | /api/advanced/generate | /api/generation-records/<taskId> |
| W3.0-Prime | wan30 | w3.0-video-prime | /api/advanced/generate | /api/generation-records/<taskId> |
| W3.0-VSR-Prime | wan30 | w3.0-video-prime-pro | /api/advanced/generate | /api/generation-records/<taskId> |
| Seedance 2.5 | seedance25 | reference / first_last_frame | /api/advanced/generate | /api/generation-records/<taskId> |
| Seedance 2.5 | seedance-nsfw | reference / first_last_frame / edit / extend | /api/advanced/generate | /api/generation-records/<taskId> |
| Vega 1.0 Lite | wand-vega-video / 1.0-lite | text / first frame / last frame / first_last_frame / multimodal references | /api/advanced/generate | /api/generation-records/<taskId> |
| Seedream 5.0 Pro | seedream-5.0-pro | - | /api/v3/images/generations | /api/v3/contents/generations/tasks/<taskId> |
| Qwen Image 3.0 | qwen-image-3.0-pro / qwen-image-3.0 | - | /api/v3/images/generations | /api/v3/contents/generations/tasks/<taskId> |
| Z-Image Spicy Pro | z-image-spicy-pro | text-to-image | /api/wan27/image-edit | /api/generation-records/<taskId> |
| Qwen Image Edit Spicy | qwen-image-edit-spicy | image-edit | /api/wan27/image-edit | /api/generation-records/<taskId> |

---

## Reusable Media

For V3 requests, create an asset with the BytePlus-compatible action and use `asset://<asset-id>`. For Advanced requests, upload with `/api/user-assets` and use the returned `asset.id` without the `asset://` prefix.

```http
POST /?Action=CreateAsset&Version=2024-01-01
Authorization: Bearer <user-token>
Content-Type: application/json

{
  "URL": "https://example.com/reference.png",
  "AssetType": "Image",
  "Name": "reference image",
  "Moderation": {
    "Strategy": "Skip"
  }
}
```

```http
POST /api/user-assets
Authorization: Bearer <user-token>
Content-Type: application/json

{
  "videoUrl": "https://example.com/reference.mp4",
  "fileName": "reference.mp4",
  "durationSeconds": 8
}
```

**Advanced asset fields**

| Parameter | Type | Required | Description | Default |
| --- | --- | --- | --- | --- |
| /api/user-assets | endpoint | No | Upload a reusable image, video, audio, or (with provider=wan30) document for Advanced generation. Reuse the returned asset.id in later requests. | - |
| url / imageUrl / videoUrl / audioUrl | string | For URL upload | Public http(s) media URL. The server imports the file into your asset library. | - |
| dataUrl | string | For inline upload | Base64 image, video, audio, or Wan 3.0 document data URL. | - |
| name / fileName | string | No | Asset display name and original file name. | Upload |
| durationSeconds | number | No | Known media duration in seconds. Supplying it avoids an extra duration probe when applicable. | - |
| provider | string | No | Set to `wan30` when uploading media for Wan 3.0 so its media-size limits are applied. | - |

---

## Seedance 2.0 V3

```http
POST /api/v3/contents/generations/tasks
Authorization: Bearer <user-token>
Content-Type: application/json

{
  "model": "dreamina-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "Use Image 1 as the subject reference and Video 1 as motion reference. Create a cinematic 5 second product promo video."
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://asset-id-from-upload"
      },
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/video1.mp4"
      },
      "role": "reference_video"
    }
  ],
  "ratio": "9:16",
  "resolution": "720p",
  "duration": 5,
  "generate_audio": true,
  "watermark": false
}
```

**Request fields and limits**

| Parameter | Type | Required | Description | Default |
| --- | --- | --- | --- | --- |
| model | string | Yes | `dreamina-seedance-2-0-260128` for standard or `dreamina-seedance-2-0-fast-260128` for fast. `dreamina-seedance-2-0-hc`, `dreamina-seedance-2-0-fast-hc`, and `dreamina-seedance-2-0-mini-hc` aliases are accepted. | - |
| content | array | Yes | 1-16 content blocks. Include one non-empty text block. Images max 9, videos max 3, audios max 3. | - |
| content[].type | enum | Yes | `text`, `image_url`, `video_url`, or `audio_url`. | - |
| content[].text | string | For text | Prompt text. Use Image 1, Video 1, Audio 1 labels yourself when referring to references. | - |
| content[].image_url.url | string | For image_url | Public image URL, supported image data URL, or `asset://<asset-id>`. JPG/PNG/WebP/BMP, max 20MB, width and height 300-6000px, aspect ratio 0.4-2.5. | - |
| content[].video_url.url | string | For video_url | Public video URL, supported video data URL, or `asset://<asset-id>`. Max 3 videos; pixel count 409600-8847360. | - |
| content[].audio_url.url | string | For audio_url | Public audio URL, supported audio data URL, or `asset://<asset-id>`. Max 3 audios; MP3/WAV/M4A/MP4 audio/AAC/OGG/WebM, max 30MB. Audio-only generation is rejected. | - |
| content[].role | enum | For media | Images: `first_frame`, `last_frame`, or `reference_image`. Videos: `reference_video`. Audios: `reference_audio`. First/last frame roles cannot be mixed with reference media. | reference_image for image_url |
| ratio | string | No | Output aspect ratio, for example `9:16`, `16:9`, or `1:1`. Ratio must stay between 0.4 and 2.5. | 9:16 |
| resolution | string | No | Standard model supports `480p`, `720p`, `1080p`, `4k`; fast/mini supports `480p`, `720p`. | 720p |
| duration | integer | No | Video duration in seconds, integer 5-15. | 5 |
| generate_audio | boolean | No | Default true. Set false to disable generated voice, effects, or background music. | true |
| watermark | boolean | No | Pass-through watermark flag. | false |
| callback_url | string(url) | No | Optional upstream callback URL when supported by the selected model/provider. | - |
| return_last_frame / priority / service_tier / execution_expires_after / seed / fps / camera_fixed | mixed | No | Provider-specific pass-through fields. The request forwards them when supported; unsupported fields are decided by the upstream model. | - |

The create response returns `id`. Poll the V3 task endpoint until `status` is `succeeded` or `failed`.

```http
GET /api/v3/contents/generations/tasks/<taskId>
Authorization: Bearer <user-token>
```

---

## Seedream 5.0 Pro Image

```http
POST /api/v3/images/generations
Authorization: Bearer <user-token>
Content-Type: application/json

{
  "model": "seedream-5.0-pro",
  "prompt": "Create a cinematic portrait while preserving the selected subject identity.",
  "image": [
    "asset://asset-id-from-upload"
  ],
  "size": "2K",
  "watermark": false,
  "output_format": "png",
  "optimize_prompt_options": {
    "mode": "standard"
  }
}
```

**Request fields and limits**

| Parameter | Type | Required | Description | Default |
| --- | --- | --- | --- | --- |
| /api/v3/images/generations | endpoint | Yes | Create a Seedream 5.0 Pro image task. The create response returns id/task_id and status. | - |
| /api/v3/contents/generations/tasks/<taskId> | endpoint | Yes | Query progress and final content.image_url. | - |
| model | string | Yes | Use `seedream-5.0-pro`. | seedream-5.0-pro |
| prompt | string | Yes | Non-empty image prompt or edit instruction. | - |
| image | string or array | No | Optional reference image or images. Use public image URLs, supported image data URLs, or asset:// ids returned by upload. Up to 9 reference images. | - |
| size | string | No | Supported values here: `1K`, `2K`. | 2K |
| response_format | enum | No | Use `url`. This async create endpoint returns a task id; read the final URL from task detail. | url |
| watermark | boolean | No | Pass-through watermark flag. | false |
| output_format | enum | No | `png` or `jpeg`. | - |
| optimize_prompt_options.mode | enum | No | `standard` or `fast` when prompt optimization is needed. | - |
| image input limits | rule | For image | Supported image uploads are max 20MB. Upstream reference images must be larger than 14x14px, aspect ratio between 1/16 and 16, and total pixels no more than 36000000. | - |

The create response returns `id`/`task_id`. Poll the V3 task endpoint and read `content.image_url` after success.

---

## Qwen Image 3.0

```http
POST /api/v3/images/generations
Authorization: Bearer <user-token>
Content-Type: application/json

{
  "model": "qwen-image-3.0-pro",
  "prompt": "Keep the subject identity and create a clean studio campaign image.",
  "image": [
    "asset://asset-id-from-upload"
  ],
  "size": "2K",
  "n": 1,
  "prompt_extend": true,
  "prompt_extend_mode": "direct",
  "watermark": false
}
```

**Request fields and limits**

| Parameter | Type | Required | Description | Default |
| --- | --- | --- | --- | --- |
| /api/v3/images/generations | endpoint | Yes | Create an asynchronous Qwen Image 3.0 task. | - |
| /api/v3/contents/generations/tasks/<taskId> | endpoint | Yes | Query progress and final content.image_url, content.image_urls, or data[].url. | - |
| model | enum | Yes | `qwen-image-3.0-pro` or `qwen-image-3.0`. | qwen-image-3.0-pro |
| prompt | string | Yes | Non-empty image prompt or edit instruction. | - |
| image | string or array | No | Optional 1-3 reference images. Use public image URLs, supported image data URLs, or asset:// ids returned by upload. | - |
| size | string | No | Use `1K`, `2K`, or `width*height`. Pixel area must be 512*512 through 2048*2048 and aspect ratio must be 1:8 through 8:1. | 2K |
| n | integer | No | Number of output images, integer 1-6. | 1 |
| negative_prompt | string | No | Optional negative prompt supplied by the caller. | - |
| prompt_extend | boolean | No | Enable prompt extension. | true |
| prompt_extend_mode | enum | No | `direct`; `agent` is accepted only for text-to-image without reference images. | direct |
| seed | integer | No | Integer 0-2147483647. | - |
| watermark | boolean | No | Whether to add an upstream watermark. | false |
| image input limits | rule | For image | JPG/JPEG, PNG, BMP, TIFF, WebP, or GIF; max 10MB per image. Recommended width and height are 384-2048px. | - |

The create response is asynchronous. Poll the V3 task endpoint and read `content.image_url`, `content.image_urls`, or `data[].url` after success.

---

## W3.0 (w3.0-video)

```http
POST /api/advanced/generate
Authorization: Bearer <user-token>
Content-Type: application/json

{
  "provider": "wan30",
  "videoCapability": "w3.0-video",
  "mediaMode": "multimodal",
  "prompt": "Use Image 1 as the character and Video 1 as the motion reference.",
  "referenceImages": [
    {
      "assetId": "uploaded-image-asset-id"
    }
  ],
  "referenceVideos": [
    {
      "assetId": "uploaded-video-asset-id"
    }
  ],
  "ratio": "9:16",
  "resolution": "720p",
  "duration": 8,
  "generateAudio": true
}
```

**Request fields and limits**

| Parameter | Type | Required | Description | Default |
| --- | --- | --- | --- | --- |
| /api/advanced/generate | endpoint | Yes | Create an asynchronous W3.0 video task. | - |
| provider | string | Yes | Use `wan30`. | wan30 |
| videoCapability | enum | Yes | Use the Mulerouter node `w3.0-video` for W3.0. | w3.0-video |
| prompt | string | Unless media is supplied | Video prompt, up to 5000 characters. When using references, name them in request order as Image 1, Video 1, Audio 1, etc. | - |
| mediaMode | enum | No | `multimodal` for reference media or `first_last_frame` for explicit first and last frames. These modes cannot be mixed. | multimodal |
| referenceImages | array | For image references | 0-10 images. Each item accepts assetId, url/imageUrl, or dataUrl plus optional fileName. | [] |
| referenceVideos | array | For video references | 0-5 videos. Each item accepts assetId, url/videoUrl, or dataUrl plus optional fileName. | [] |
| referenceAudios | array | For audio references | 0-5 audios. Each item accepts assetId, url/audioUrl, or dataUrl plus optional fileName. | [] |
| referenceFileAssetId / referenceFile | string/object | For document input | One PDF, Word, Excel, PowerPoint, TXT, or Markdown document, up to 100MB. It cannot be combined with other media inputs. | - |
| firstFrameUrl / firstFrameDataUrl / firstFrameAssetId | string | For first_last_frame | First-frame image. | - |
| lastFrameUrl / lastFrameDataUrl / lastFrameAssetId | string | For first_last_frame | Last-frame image. Both frame images are required. | - |
| resolution | enum | No | `480p`, `720p`, or `1080p`. | 1080p |
| ratio | enum | No | `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, or `adaptive`. | adaptive |
| duration | integer | No | Output duration from 2-30 seconds. Use `-1` for adaptive output duration. | 5 |
| generateAudio / generate_audio | boolean | No | Whether the output should include generated audio. | true |
| prompt_extend | boolean | No | Whether to rewrite and expand the prompt before generation. Disable it for strict professional prompt adherence; it is enabled by default. | true |
| seed | integer | No | Integer from 0 to 2147483647. | - |
| watermark | boolean | No | Whether to add a watermark. | false |
| image limits | rule | For image | JPG/JPEG, PNG, BMP, or WebP; max 20MB; width and height 240-8000px; aspect ratio no wider than 8:1. PNG transparency is not supported. | - |
| video limits | rule | For video | MP4 or MOV; smaller than 100MB; width and height 240-4096px; aspect ratio no wider than 8:1; each video 1-15 seconds; all reference videos together at most 15 seconds. | - |
| audio limits | rule | For audio | MP3 or WAV; smaller than 15MB; each audio 1-15 seconds; all reference audios together at most 15 seconds. | - |
| duration combination | rule | When video references are used | If duration is not `-1`, total input-video seconds plus output duration must not exceed 30 seconds. | - |

---

## W3.0-Pro (w3.0-video-pro)

```http
POST /api/advanced/generate
Authorization: Bearer <user-token>
Content-Type: application/json

{
  "provider": "wan30",
  "videoCapability": "w3.0-video-pro",
  "mediaMode": "multimodal",
  "prompt": "Create a high-detail cinematic product shot.",
  "referenceImages": [
    {
      "assetId": "uploaded-image-asset-id"
    }
  ],
  "ratio": "16:9",
  "resolution": "2k",
  "duration": 5,
  "generateAudio": true
}
```

**Request fields and limits**

| Parameter | Type | Required | Description | Default |
| --- | --- | --- | --- | --- |
| /api/advanced/generate | endpoint | Yes | Create an asynchronous W3.0-Pro video task. | - |
| provider | string | Yes | Use `wan30`. | wan30 |
| videoCapability | enum | Yes | Use the Mulerouter node `w3.0-video-pro` for W3.0-Pro. | w3.0-video-pro |
| prompt | string | Unless media is supplied | Video prompt, up to 5000 characters. When using references, name them in request order as Image 1, Video 1, Audio 1, etc. | - |
| mediaMode | enum | No | `multimodal` for reference media or `first_last_frame` for explicit first and last frames. These modes cannot be mixed. | multimodal |
| referenceImages | array | For image references | 0-10 images. Each item accepts assetId, url/imageUrl, or dataUrl plus optional fileName. | [] |
| referenceVideos | array | For video references | 0-5 videos. Each item accepts assetId, url/videoUrl, or dataUrl plus optional fileName. | [] |
| referenceAudios | array | For audio references | 0-5 audios. Each item accepts assetId, url/audioUrl, or dataUrl plus optional fileName. | [] |
| referenceFileAssetId / referenceFile | string/object | For document input | One PDF, Word, Excel, PowerPoint, TXT, or Markdown document, up to 100MB. It cannot be combined with other media inputs. | - |
| firstFrameUrl / firstFrameDataUrl / firstFrameAssetId | string | For first_last_frame | First-frame image. | - |
| lastFrameUrl / lastFrameDataUrl / lastFrameAssetId | string | For first_last_frame | Last-frame image. Both frame images are required. | - |
| resolution | enum | No | `1080p`, `2k`, or `4k`. | 1080p |
| ratio | enum | No | `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, or `adaptive`. | adaptive |
| duration | integer | No | Output duration from 2-30 seconds. Use `-1` for adaptive output duration. | 5 |
| generateAudio / generate_audio | boolean | No | Whether the output should include generated audio. | true |
| prompt_extend | boolean | No | Whether to rewrite and expand the prompt before generation. Disable it for strict professional prompt adherence; it is enabled by default. | true |
| seed | integer | No | Integer from 0 to 2147483647. | - |
| watermark | boolean | No | Whether to add a watermark. | false |
| image limits | rule | For image | JPG/JPEG, PNG, BMP, or WebP; max 20MB; width and height 240-8000px; aspect ratio no wider than 8:1. PNG transparency is not supported. | - |
| video limits | rule | For video | MP4 or MOV; smaller than 100MB; width and height 240-4096px; aspect ratio no wider than 8:1; each video 1-15 seconds; all reference videos together at most 15 seconds. | - |
| audio limits | rule | For audio | MP3 or WAV; smaller than 15MB; each audio 1-15 seconds; all reference audios together at most 15 seconds. | - |
| duration combination | rule | When video references are used | If duration is not `-1`, total input-video seconds plus output duration must not exceed 30 seconds. | - |

---

## W3.0-Prime (w3.0-video-prime)

```http
POST /api/advanced/generate
Authorization: Bearer <user-token>
Content-Type: application/json

{
  "provider": "wan30",
  "videoCapability": "w3.0-video-prime",
  "mediaMode": "multimodal",
  "prompt": "Create a cinematic character performance with natural motion.",
  "referenceImages": [
    {
      "assetId": "uploaded-image-asset-id"
    }
  ],
  "ratio": "9:16",
  "resolution": "1080p",
  "duration": 5,
  "generateAudio": true
}
```

**Request fields and limits**

| Parameter | Type | Required | Description | Default |
| --- | --- | --- | --- | --- |
| /api/advanced/generate | endpoint | Yes | Create an asynchronous W3.0-Prime video task. | - |
| provider | string | Yes | Use `wan30`. | wan30 |
| videoCapability | enum | Yes | Use the Mulerouter node `w3.0-video-prime` for W3.0-Prime. | w3.0-video-prime |
| prompt | string | Unless media is supplied | Video prompt, up to 5000 characters. When using references, name them in request order as Image 1, Video 1, Audio 1, etc. | - |
| mediaMode | enum | No | `multimodal` for reference media or `first_last_frame` for explicit first and last frames. These modes cannot be mixed. | multimodal |
| referenceImages | array | For image references | 0-10 images. Each item accepts assetId, url/imageUrl, or dataUrl plus optional fileName. | [] |
| referenceVideos | array | For video references | 0-5 videos. Each item accepts assetId, url/videoUrl, or dataUrl plus optional fileName. | [] |
| referenceAudios | array | For audio references | 0-5 audios. Each item accepts assetId, url/audioUrl, or dataUrl plus optional fileName. | [] |
| referenceFileAssetId / referenceFile | string/object | For document input | One PDF, Word, Excel, PowerPoint, TXT, or Markdown document, up to 100MB. It cannot be combined with other media inputs. | - |
| firstFrameUrl / firstFrameDataUrl / firstFrameAssetId | string | For first_last_frame | First-frame image. | - |
| lastFrameUrl / lastFrameDataUrl / lastFrameAssetId | string | For first_last_frame | Last-frame image. Both frame images are required. | - |
| resolution | enum | No | `480p`, `720p`, or `1080p`. | 1080p |
| ratio | enum | No | `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, or `adaptive`. | adaptive |
| duration | integer | No | Output duration from 2-30 seconds. Use `-1` for adaptive output duration. | 5 |
| generateAudio / generate_audio | boolean | No | Whether the output should include generated audio. | true |
| prompt_extend | boolean | No | Whether to rewrite and expand the prompt before generation. Disable it for strict professional prompt adherence; it is enabled by default. | true |
| seed | integer | No | Integer from 0 to 2147483647. | - |
| watermark | boolean | No | Whether to add a watermark. | false |
| image limits | rule | For image | JPG/JPEG, PNG, BMP, or WebP; max 20MB; width and height 240-8000px; aspect ratio no wider than 8:1. PNG transparency is not supported. | - |
| video limits | rule | For video | MP4 or MOV; smaller than 100MB; width and height 240-4096px; aspect ratio no wider than 8:1; each video 1-15 seconds; all reference videos together at most 15 seconds. | - |
| audio limits | rule | For audio | MP3 or WAV; smaller than 15MB; each audio 1-15 seconds; all reference audios together at most 15 seconds. | - |
| duration combination | rule | When video references are used | If duration is not `-1`, total input-video seconds plus output duration must not exceed 30 seconds. | - |

---

## W3.0-VSR-Prime (w3.0-video-prime-pro)

```http
POST /api/advanced/generate
Authorization: Bearer <user-token>
Content-Type: application/json

{
  "provider": "wan30",
  "videoCapability": "w3.0-video-prime-pro",
  "mediaMode": "multimodal",
  "prompt": "Create a premium cinematic shot with precise identity and motion.",
  "referenceImages": [
    {
      "assetId": "uploaded-image-asset-id"
    }
  ],
  "ratio": "16:9",
  "resolution": "2k",
  "duration": 5,
  "generateAudio": true
}
```

**Request fields and limits**

| Parameter | Type | Required | Description | Default |
| --- | --- | --- | --- | --- |
| /api/advanced/generate | endpoint | Yes | Create an asynchronous W3.0-VSR-Prime video task. | - |
| provider | string | Yes | Use `wan30`. | wan30 |
| videoCapability | enum | Yes | Use the Mulerouter node `w3.0-video-prime-pro` for W3.0-VSR-Prime. | w3.0-video-prime-pro |
| prompt | string | Unless media is supplied | Video prompt, up to 5000 characters. When using references, name them in request order as Image 1, Video 1, Audio 1, etc. | - |
| mediaMode | enum | No | `multimodal` for reference media or `first_last_frame` for explicit first and last frames. These modes cannot be mixed. | multimodal |
| referenceImages | array | For image references | 0-10 images. Each item accepts assetId, url/imageUrl, or dataUrl plus optional fileName. | [] |
| referenceVideos | array | For video references | 0-5 videos. Each item accepts assetId, url/videoUrl, or dataUrl plus optional fileName. | [] |
| referenceAudios | array | For audio references | 0-5 audios. Each item accepts assetId, url/audioUrl, or dataUrl plus optional fileName. | [] |
| referenceFileAssetId / referenceFile | string/object | For document input | One PDF, Word, Excel, PowerPoint, TXT, or Markdown document, up to 100MB. It cannot be combined with other media inputs. | - |
| firstFrameUrl / firstFrameDataUrl / firstFrameAssetId | string | For first_last_frame | First-frame image. | - |
| lastFrameUrl / lastFrameDataUrl / lastFrameAssetId | string | For first_last_frame | Last-frame image. Both frame images are required. | - |
| resolution | enum | No | `1080p`, `2k`, or `4k`. | 1080p |
| ratio | enum | No | `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, or `adaptive`. | adaptive |
| duration | integer | No | Output duration from 2-30 seconds. Use `-1` for adaptive output duration. | 5 |
| generateAudio / generate_audio | boolean | No | Whether the output should include generated audio. | true |
| prompt_extend | boolean | No | Whether to rewrite and expand the prompt before generation. Disable it for strict professional prompt adherence; it is enabled by default. | true |
| seed | integer | No | Integer from 0 to 2147483647. | - |
| watermark | boolean | No | Whether to add a watermark. | false |
| image limits | rule | For image | JPG/JPEG, PNG, BMP, or WebP; max 20MB; width and height 240-8000px; aspect ratio no wider than 8:1. PNG transparency is not supported. | - |
| video limits | rule | For video | MP4 or MOV; smaller than 100MB; width and height 240-4096px; aspect ratio no wider than 8:1; each video 1-15 seconds; all reference videos together at most 15 seconds. | - |
| audio limits | rule | For audio | MP3 or WAV; smaller than 15MB; each audio 1-15 seconds; all reference audios together at most 15 seconds. | - |
| duration combination | rule | When video references are used | If duration is not `-1`, total input-video seconds plus output duration must not exceed 30 seconds. | - |

---

## Seedance 2.5 Video (seedance25)

```http
POST /api/advanced/generate
Authorization: Bearer <user-token>
Content-Type: application/json

{
  "provider": "seedance25",
  "functionMode": "reference",
  "prompt": "Use Image 1 as the subject and Video 1 as the action reference.",
  "referenceImages": [
    {
      "assetId": "uploaded-image-asset-id"
    }
  ],
  "referenceVideos": [
    {
      "assetId": "uploaded-video-asset-id"
    }
  ],
  "ratio": "9:16",
  "resolution": "720p",
  "duration": 8,
  "generateAudio": true
}
```

**Request fields and limits**

| Parameter | Type | Required | Description | Default |
| --- | --- | --- | --- | --- |
| /api/advanced/generate | endpoint | Yes | Create an asynchronous Seedance 2.5 video task. | - |
| provider | string | Yes | Use `seedance25`. | seedance25 |
| prompt | string | Yes | Video prompt, 1-5000 characters. | - |
| functionMode / seedanceMode / mediaMode | enum | No | `reference` (multimodal reference generation) or `first_last_frame`. `omini` is accepted as the reference-mode alias. | reference |
| referenceImages | array | For reference mode | 0-30 images. Each item accepts assetId, url/imageUrl, or dataUrl plus optional fileName. | [] |
| referenceVideos / referenceVideoUrls / referenceVideoAssetIds | array | For video references | Reference mode accepts 0-10 videos. | [] |
| referenceAudios / referenceAudioUrls / referenceAudioAssetIds | array | For reference mode | 0-10 audios. Audio-only reference generation is not supported; include at least one image or video. | [] |
| firstFrameUrl / firstFrameDataUrl / firstFrameAssetId | string | For first_last_frame | First-frame image. | - |
| lastFrameUrl / lastFrameDataUrl / lastFrameAssetId | string | For first_last_frame | Last-frame image. Both frames are required and cannot be mixed with reference media. | - |
| resolution | enum | No | `480p` or `720p`. | 480p |
| ratio | enum | No | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, or `9:16`. | 16:9 |
| duration | integer | No | Integer 4-30 seconds for 480p, or 4-29 seconds for 720p. | 4 |
| generateAudio / generate_audio | boolean | No | Generate native audio. This does not change the upstream price. | true |
| reference total | rule | For reference mode | At least one reference is required; at most 50 images, videos, and audios combined. | - |

---

## Seedance 2.5 Video (seedance-nsfw)

```http
POST /api/advanced/generate
Authorization: Bearer <user-token>
Content-Type: application/json

{
  "provider": "seedance-nsfw",
  "functionMode": "reference",
  "prompt": "Use Image 1 as the subject and Video 1 as the action reference.",
  "referenceImages": [
    {
      "assetId": "uploaded-image-asset-id"
    }
  ],
  "referenceVideos": [
    {
      "assetId": "uploaded-video-asset-id"
    }
  ],
  "ratio": "9:16",
  "resolution": "720p",
  "duration": 8,
  "generateAudio": true
}
```

**Request fields and limits**

| Parameter | Type | Required | Description | Default |
| --- | --- | --- | --- | --- |
| /api/advanced/generate | endpoint | Yes | Create an asynchronous Seedance 2.5 video task. | - |
| provider | string | Yes | Use `seedance-nsfw`. | seedance-nsfw |
| prompt | string | Unless media is supplied | Video prompt, up to 6000 characters. References keep request order as Image 1, Video 1, Audio 1, etc. | - |
| functionMode / seedanceMode / mediaMode | enum | No | `reference`/`omini`, `first_last_frame`, `edit`, or `extend`. | reference |
| referenceImages | array | For image references | 0-30 images. Each item accepts assetId, url/imageUrl, or dataUrl plus optional fileName. | [] |
| referenceVideos / referenceVideoAssetIds | array | For video references | Reference mode accepts 0-10 videos. Edit and extend require exactly one source video. | [] |
| referenceAudios / referenceAudioAssetIds | array | For audio references | 0-10 audios. Audio-only reference generation is supported by this direct model. | [] |
| firstFrameUrl / firstFrameDataUrl / firstFrameAssetId | string | For first_last_frame | First-frame image. | - |
| lastFrameUrl / lastFrameDataUrl / lastFrameAssetId | string | For first_last_frame | Last-frame image. Both frames are required and cannot be mixed with reference media. | - |
| resolution | enum | No | `480p` or `720p`. | 480p |
| ratio | enum | No | `16:9`, `21:9`, `9:16`, `4:3`, `3:4`, `1:1`, or `adaptive`. | adaptive |
| duration | integer | No | Output duration from 4-30 seconds. Edit follows the source-video duration. | 4 |
| generateAudio / generate_audio | boolean | No | Generate output audio. The upstream default is true. | true |
| seed | integer | No | `-1` for random, or an integer from 0 to 4294967295. | -1 |
| reference total | rule | For reference mode | At most 50 images, videos, and audios combined. | - |

---

## Vega 1.0 Lite

```http
POST /api/advanced/generate
Authorization: Bearer <user-token>
Content-Type: application/json

{
  "provider": "vega10-lite",
  "prompt": "Create a polished cinematic shot that follows the supplied frames.",
  "mediaMode": "first_frame",
  "firstFrameUrl": "https://example.com/first-frame.png",
  "ratio": "16:9",
  "resolution": "768P",
  "duration": 5
}
```

**Request fields and limits**

| Parameter | Type | Required | Description | Default |
| --- | --- | --- | --- | --- |
| /api/advanced/generate | endpoint | Yes | Create an asynchronous Vega 1.0 Lite video task through Tencent VOD. | - |
| provider | string | Yes | Use `vega10-lite`. | vega10-lite |
| prompt | string | Yes | Non-empty video prompt, max 7000 characters. Prompt enhancement is controlled by enhancePromptMode. | - |
| mediaMode | enum | No | `text_to_video`, `first_frame`, `last_frame`, `first_last_frame`, `reference_video`, or `draft_followup`. | text_to_video |
| firstFrameUrl | string | For first_frame / first_last_frame | Public HTTP(S) first-frame image URL. Asset IDs and data URLs are not accepted. | - |
| lastFrameUrl | string | For last_frame / first_last_frame | Public HTTP(S) last-frame image URL. This is a standalone mode and does not require a first frame. | - |
| reference limits | rule | For reference mode | Up to 9 images, 3 videos, and 3 audios (12 references total). Each video and audio must be 2-15 seconds, and each media type must total at most 15 seconds. Image max 30MB, video max 50MB, audio max 15MB. | - |
| referenceImages | array | No | Public HTTP(S) image reference URLs: JPG/JPEG, PNG, WebP, HEIC, or HEIF; max 30MB each. | [] |
| referenceVideos | array | No | Public HTTP(S) video reference URLs: H.264/AVC or H.265/HEVC; max 50MB each. | [] |
| referenceAudios | array | No | Public HTTP(S) WAV or MP3 audio reference URLs, max 15MB each. Audio must be paired with an image or video. | [] |
| resolution | enum | No | `480P`, `768P`, `1080P`, `2K`, `4K` | 1080P |
| ratio | enum | No | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `adaptive` | 16:9 |
| duration | integer | No | Integer 4-15 seconds. Edit requires -1. | 5 |
| seed | integer | No | Optional non-negative integer seed. | - |
| taskType | enum | No | `auto` or `reference`. | auto |
| draft / draftTaskId | boolean / string | No | Not supported for this model. | - |
| assetGroupId | string | No | Optional upstream asset group id. | - |
| generateAudio | boolean | No | Maps to OutputConfig.AudioGeneration Enabled/Disabled. | true |
| returnLastFrame | boolean | No | Maps to ExtInfo.AdditionalParameters.return_last_frame. | false |
| returnVegaUsage | boolean | No | Maps to WandVegaParameters.ReturnVegaUsage. | false |
| enhancePromptMode | enum | No | `auto`, `enable`, or `disable`. | auto |
| moderationMode | enum | No | `Moderation_L1` or `Moderation_L2`. | Moderation_L1 |
| generateMode | enum | No | Not supported for this model. | - |
| videoQualityMode | enum | No | `Standard`, `Fast`, or `SuperFast`. | Standard |
| outputFormat | enum | No | `mp4` or `mov`. | mp4 |
| pricing | rule | Yes | Vega prices come from PostgreSQL admin pricing. Requests fail with HTTP 422 `MODEL_PRICING_UNAVAILABLE` before charging or calling upstream when a required rate is missing. | - |
| media transport | rule | Yes | Vega 1.0 Lite submits public URLs as FileInfos Type=Url. Inputs use FileInfos Usage FirstFrame, LastFrame, or Reference. Use public URLs only; asset IDs and data URLs are rejected. | - |

---

## Advanced Task Polling

Advanced video tasks return `taskId`. Poll the generation record until its status is `succeeded` or `failed`.

```http
GET /api/generation-records/<taskId>
Authorization: Bearer <user-token>
```

---

## Z-Image Spicy Pro

```http
POST /api/wan27/image-edit
Authorization: Bearer <user-token>
Content-Type: application/json

{
  "prompt": "A cinematic portrait of a traveler in a rain-soaked neon city, ultra detailed.",
  "ratio": "9:16",
  "resolution": "2K",
  "prompt_extend": true,
  "seed": 123456,
  "watermark": false,
  "async": true
}
```

**Request fields and limits**

| Parameter | Type | Required | Description | Default |
| --- | --- | --- | --- | --- |
| /api/wan27/image-edit | endpoint | Yes | Create a Z-Image Spicy Pro text-to-image task. Send no input image. | - |
| prompt | string | Yes | Non-empty image prompt. | - |
| imageUrls / imageAssetIds | array | No | Leave empty for text-to-image. Supplying one or more images switches the request to image editing. | [] |
| imageUrl / imageAssetId | string | No | Leave empty for text-to-image. | - |
| ratio | string | No | `1:1`, `3:4`, `4:3`, `9:16`, or `16:9`. | 9:16 |
| resolution | string | No | `1K` or `2K`. | 2K |
| size | string | No | Explicit output size as `width*height`, for example `1440*2560`. Width and height must each stay within 256-2560px. When omitted, the platform derives it from `resolution` and `ratio`. | derived from resolution + ratio |
| model | string | No | Optional explicit model id. The platform normally selects the serving model from the request shape, so most callers omit this field. | - |
| n | integer | No | Number of output images. Keep it at `1`; single-image output is the supported shape for this engine. | 1 |
| prompt_extend | boolean | No | Whether to expand the prompt before generation. | true |
| seed | integer | No | Integer 0-2147483647. | random |
| watermark | boolean | No | Whether to add a watermark. | false |
| async / asyncResponse / returnImmediately | boolean | No | Return immediately with task info instead of waiting for the image result. | false |

---

## Qwen Image Edit Spicy

```http
POST /api/wan27/image-edit
Authorization: Bearer <user-token>
Content-Type: application/json

{
  "prompt": "Turn the subject into a cinematic portrait while preserving identity.",
  "imageUrls": [
    "https://example.com/reference.png"
  ],
  "ratio": "9:16",
  "resolution": "2K",
  "seed": 42,
  "watermark": false,
  "async": true
}
```

**Request fields and limits**

| Parameter | Type | Required | Description | Default |
| --- | --- | --- | --- | --- |
| /api/wan27/image-edit | endpoint | Yes | Create a Qwen Image Edit Spicy image-editing task. | - |
| prompt | string | Yes | Non-empty edit instruction. | - |
| imageUrls / imageAssetIds | array | Yes | 1-3 images. The first image is the picture being edited; the remaining ones are optional references. Use public image URLs or uploaded image asset ids. | [] |
| imageUrl / imageAssetId | string | Yes | Single input image URL or uploaded image asset id. | - |
| ratio | string | No | `1:1`, `3:4`, `4:3`, `9:16`, or `16:9`. The output size also follows the input image. | 9:16 |
| resolution | string | No | `1K` or `2K`. | 2K |
| size | string | No | Explicit output size as `width*height`. When omitted, the platform derives it from `resolution` and `ratio`. | derived from resolution + ratio |
| model | string | No | Optional explicit model id. The platform normally selects the serving model from the request shape, so most callers omit this field. | - |
| n | integer | No | Number of output images. Keep it at `1`; single-image output is the supported shape for this engine. | 1 |
| seed | integer | No | Integer 0-2147483647. | random |
| watermark | boolean | No | Whether to add a watermark. | false |
| async / asyncResponse / returnImmediately | boolean | No | Return immediately with task info instead of waiting for the image result. | false |

---

## Account Balance

Query the caller account balance and, when using a sub token, that token's quota.

```http
GET /api/v3/account/balance
Authorization: Bearer <user-token>
```

The response includes `account.credits`, the account currency, and `token` metadata for a sub token (`quotaLimit`, `usedAmount`, `usedCount`, and `remaining`). The token secret is never returned.

---

## Billing

1 USD equals 100 credits. Advanced generation is charged by the configured public rates.

---

## Endpoints

```json
{
  "docsMarkdown": "https://123vips.com/docs/api.md",
  "docsJson": "https://123vips.com/docs/api.json",
  "legacyDocsMarkdown": "https://123vips.com/docs/models.md",
  "modelsJson": "https://123vips.com/api/models",
  "accountBalance": "https://123vips.com/api/v3/account/balance",
  "byteplusGenerate": "https://123vips.com/api/v3/contents/generations/tasks",
  "byteplusTaskDetail": "https://123vips.com/api/v3/contents/generations/tasks/<taskId>",
  "seedream5ImageGenerate": "https://123vips.com/api/v3/images/generations",
  "seedream5ImageTaskDetail": "https://123vips.com/api/v3/contents/generations/tasks/<taskId>",
  "qwenImage3Generate": "https://123vips.com/api/v3/images/generations",
  "qwenImage3TaskDetail": "https://123vips.com/api/v3/contents/generations/tasks/<taskId>",
  "byteplusAssetAction": "https://123vips.com/?Action=CreateAsset&Version=2024-01-01",
  "advancedAssetUpload": "https://123vips.com/api/user-assets",
  "advancedGenerate": "https://123vips.com/api/advanced/generate",
  "wan27ImageEdit": "https://123vips.com/api/wan27/image-edit",
  "generationRecordDetail": "https://123vips.com/api/generation-records/<taskId>"
}
```

---
