PixVerse Video Generation

Use EasyRouter's unified API to call all PixVerse video models (C1 / V6 / V5.6 / V5.5 / V5 / V4.5 / V4 / V3.5) with support for text-to-video and image-to-video.

PixVerse is a high-quality AI video generation platform. EasyRouter integrates with PixVerse OpenAPI v2 and exposes it via the OpenAI-compatible /v1/videos endpoint. All 8 PixVerse model versions are supported for text-to-video and image-to-video.

PixVerse uses an async task-based API: submit a request, receive a task_id, poll for status, then download the video via the proxy endpoint.

1. Supported Models

In the model field, always use the PixVerse/<version> form, e.g. PixVerse/v5.6.

Model	Highlights	Duration	Audio
`PixVerse/c1`	Flagship, per-second billing, most flexible	1~15s (per-second)	✓
`PixVerse/v6`	Latest generation, per-second billing	1~15s (per-second)	✓
`PixVerse/v5.6`	Single-clip mode, stable quality	5 / 8 / 10s	✓
`PixVerse/v5.5`	Supports Multi-Clip stitching	5 / 8 / 10s	✓
`PixVerse/v5`	Generation 5 baseline	5 / 8s	✗
`PixVerse/v4.5`	Generation 4.5, supports Fast Motion	5 / 8s	✗
`PixVerse/v4`	Generation 4, supports Fast Motion	5 / 8s	✗
`PixVerse/v3.5`	Generation 3.5, supports Fast Motion	5 / 8s	✗

The PixVerse/ prefix is case-sensitive. Use exactly PixVerse/v5.6. The version suffix (v5.6, c1) is case-insensitive but lowercase is recommended.

2. Common Endpoints

All PixVerse models use the OpenAI-compatible /v1/videos endpoint.

2.1 Submit Task

POST /v1/videos

Request Headers

Header	Required	Description
`Authorization`	✓	`Bearer sk-YourApiKey`
`Content-Type`	✓	`application/json`

Request Body Fields

Field	Type	Required	Description
`model`	string	✓	PixVerse model name (see table above)
`prompt`	string	✓	Text prompt, up to 2048 characters
`image`	string	—	Reference image for image-to-video (URL or base64 data URI). Auto-switches to image-to-video mode
`images`	string[]	—	Array variant of `image` (use one or the other)
`duration`	int	—	Duration in seconds, default 5. Supported values depend on model
`resolution`	string	—	Resolution tier (same as `size`; recommended, aligns with other models): `720P` / `1080P`
`size`	string	—	Resolution: `360p`, `540p`, `720p`, `1080p`, or pixel form like `1920x1080`. `resolution` takes precedence when both are provided
`metadata`	object	—	Container for PixVerse-specific parameters (see Section 3)

Response

{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video",
  "model": "PixVerse/v5.6",
  "status": "queued",
  "progress": 0,
  "created_at": 1730000000
}

The id / task_id is a public ID generated by EasyRouter (prefixed with task_). Use this value for subsequent queries — it's not the same as PixVerse's upstream video_id.

2.2 Query Task Status

GET /v1/videos/{task_id}

Response (in progress)

{
  "id": "task_xxxxxxxxxxxxx",
  "status": "in_progress",
  "progress": 30,
  "created_at": 1730000000
}

Response (completed)

{
  "id": "task_xxxxxxxxxxxxx",
  "status": "completed",
  "progress": 100,
  "created_at": 1730000000,
  "completed_at": 1730000060,
  "size": "1280x720",
  "metadata": {
    "url": "https://media.pixverse.ai/xxx.mp4"
  }
}

Status Enum

Status	Description
`queued`	Submitted, queued
`in_progress`	Generating
`completed`	Finished, `metadata.url` is the video URL
`failed`	Failed, see `error.message`

2.3 Download Video Content

GET /v1/videos/{task_id}/content

Returns raw video bytes (Content-Type: video/mp4). EasyRouter proxies the PixVerse temporary URL so your client never sees the upstream URL, and you don't have to worry about URL expiration.

Strongly recommended: use the /content proxy endpoint to download videos, not the raw metadata.url. The raw URL is a temporary link (usually valid for a few hours); the proxy endpoint never expires as long as the task record exists.

3. PixVerse-Specific Parameters (metadata)

All PixVerse-specific fields are passed via the metadata object in the request body.

3.1 Common Fields

Field	Type	Applies to	Description
`quality`	string	All	Resolution (overrides top-level `size`): `360p` / `540p` / `720p` / `1080p`
`aspect_ratio`	string	Text-to-video	Aspect ratio: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `2:3`, `3:2`, `21:9`
`motion_mode`	string	V4.5 / V4 / V3.5	`normal` (default) or `fast` (×2 pricing, only 5s at 360p/540p/720p)
`camera_movement`	string	All	Camera movement: `zoom_in`, `zoom_out`, `pan_left`, `pan_right`, etc.
`seed`	int	All	Random seed, 0 ~ 2147483647
`template_id`	int	All	Template ID
`style`	string	All	Style, e.g., `anime`
`water_mark`	bool	All	Add watermark
`negative_prompt`	string	All	Negative prompt

motion_mode: fast has strict limits: only V4.5 / V4 / V3.5 models, at 5s duration, and at 360p/540p/720p resolution. Illegal combinations (e.g., 1080p + fast or 8s + fast) will return a 400 error with no charge.

3.2 Audio Generation (C1 / V6 / V5.6 / V5.5)

Field	Type	Applies to	Description
`generate_audio_switch`	bool	C1 / V6 / V5.6 / V5.5	Switch to "with audio" billing tier (upstream synthesizes audio alongside video)

V5 / V4.5 / V4 / V3.5 do not support audio generation. Passing generate_audio_switch: true on these models returns a 400 error.

3.3 Image-to-Video Advanced Fields

PixVerse image-to-video requires uploading an image first to get an img_id. EasyRouter automates the upload step:

Pass image: "https://..." or image: "data:image/png;base64,..." in the request body
EasyRouter uploads to PixVerse and forwards the img_id automatically

If you already have an img_id (advanced use case), you can pass it directly:

Field	Type	Description
`img_id`	int	Pre-uploaded image ID, takes priority over auto-upload

4. Full Examples

# Step 1: Submit the task
curl -X POST https://easyrouter.io/v1/videos \
  -H "Authorization: Bearer sk-YourApiKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "PixVerse/v5.6",
    "prompt": "A cat walking on the moon with a starry background",
    "duration": 5,
    "size": "720p",
    "metadata": {
      "aspect_ratio": "16:9",
      "seed": 42
    }
  }'

# Response:
# {
#   "id": "task_abc123...",
#   "task_id": "task_abc123...",
#   "status": "queued",
#   ...
# }

# Step 2: Poll for status (every 3~5 seconds is recommended)
curl https://easyrouter.io/v1/videos/task_abc123... \
  -H "Authorization: Bearer sk-YourApiKey"

# Step 3: Once status is "completed", download the video
curl https://easyrouter.io/v1/videos/task_abc123.../content \
  -H "Authorization: Bearer sk-YourApiKey" \
  -o cat_on_moon.mp4

curl -X POST https://easyrouter.io/v1/videos \
  -H "Authorization: Bearer sk-YourApiKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "PixVerse/v5.6",
    "prompt": "Make the cat jump",
    "image": "https://example.com/cat.jpg",
    "duration": 5,
    "size": "720p"
  }'

# Encode image as a data URI
IMG_BASE64=$(base64 -i cat.jpg)

curl -X POST https://easyrouter.io/v1/videos \
  -H "Authorization: Bearer sk-YourApiKey" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"PixVerse/v5.6\",
    \"prompt\": \"Make the cat jump\",
    \"image\": \"data:image/jpeg;base64,${IMG_BASE64}\",
    \"duration\": 5,
    \"size\": \"720p\"
  }"

# C1 / 720p / 5s with upstream-synthesized audio
curl -X POST https://easyrouter.io/v1/videos \
  -H "Authorization: Bearer sk-YourApiKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "PixVerse/c1",
    "prompt": "Ocean waves crashing on the shore, seagulls circling above",
    "duration": 5,
    "size": "720p",
    "metadata": {
      "generate_audio_switch": true,
      "aspect_ratio": "16:9"
    }
  }'

5. Error Handling

5.1 HTTP 400 Invalid Parameters (intercepted pre-submit, no charge)

EasyRouter strictly validates parameter combinations before forwarding upstream. The following illegal combinations return 400 Bad Request:

Scenario	Error message
V5 / V4.5 / V4 / V3.5 with `generate_audio_switch: true`	`model "v5" does not support audio generation`
V4.5 / V4 / V3.5 `fast` mode + 1080p	`V4/V4.5/V3.5 fast motion only supports 360p/540p/720p at 5s`
V4.5 / V4 / V3.5 `fast` mode + 8s	same as above
V5.6 / V5.5 / V5 with unsupported quality × duration	`combination 1080p / 10s not supported`
Unknown model name	`unknown model: "v999"`

5.2 HTTP 401 / 403 Auth Errors

401 Unauthorized: API Key invalid or expired
403 Forbidden: API Key not authorized for this model (check token model whitelist)

5.3 HTTP 402 Insufficient Balance

Returns insufficient user quota. Please top up in the EasyRouter console.

5.4 Task `failed` Status

Task was accepted but generation failed. Common reasons:

Reason	Description	Suggestion
`content moderation failed`	Content rejected by moderation	Revise prompt to avoid sensitive content
`generation failed`	Upstream generation failed	Retry, or lower resolution/duration
`upstream timeout`	Upstream timeout	Retry later

When a task ends with failed, EasyRouter automatically refunds the charge to your account. Refund records are visible in the console logs page.