Image-to-video

The Image-to-Video API transforms static images into dynamic videos with motion and effects. This guide walks you through the process of generating videos from your images.

Overview

The Image-to-Video endpoint allows you to animate static images by applying various motion effects, transformations, and optional style transfers. You can upload your own images or provide image URLs.

Endpoint: POST https://app-api.pixverse.ai/openapi/v2/video/img/generate
API reference

Image upload task : https://docs.platform.pixverse.ai/upload-image-13016631e0

generation task : https://docs.platform.pixverse.ai/image-to-video-generation-13016633e0

Prerequisites

Before you begin, make sure you have:

A valid PixVerse API key

A different Ai-trace-id for each unique request

An active subscription plan with available credits or purchased credits

A image in supported formats (JPG, PNG, Webp)

maximum dimensions 10000 pixels

Supported formats: "png", "webp", "jpeg", "jpg"

Supported mime-type : "image/jpeg","image/jpg","image/png","image/webp"

Quick-start

1: Upload your image

2: Image-to-video generation task

3. Check generation status & download

Step-by-Step Guide

1. Prepare Your Image

For best results, ensure your image:

Has good resolution (at least 1024×1024 pixels recommended)

Has clear subjects with some space around them

Is free from heavy text overlays or watermarks

Has good lighting and contrast

2. Prepare Your upload image API Request and uplaod image to get img_id

Construct your API request with the appropriate parameters:

Responses

{
    "ErrCode": 0,
    "ErrMsg": "string",
    "Resp": {
        "img_id": 0,
        "img_url": "string"
    }
}

3. Prepare your image-to-video API request

If you want to use effect please go to : https://docs.platform.pixverse.ai/how-to-use-effects-796054m0

4. Parameter details

https://docs.platform.pixverse.ai/how-to-use-image-to-video-882971m0

5. Handle the API Response

The API returns a JSON response with a video_id:

{
  "ErrCode": 0,
  "ErrMsg": "success",
  "Resp": {
    "video_id": 0
  }
}

6. Check Generation Status

After creating the task, you will receive a video_id

Query periodically Get Video Generation Status API using this video_id

The status will change from 5 to 1 when processing is complete

  {
 "ErrCode": 0,
 "ErrMsg": "string",
 "Resp": {
   "create_time": "string",
   "id": 0,
   "modify_time": "string",
   "negative_prompt": "string",
   "outputHeight": 0,
   "outputWidth": 0,
   "prompt": "string",
   "resolution_ratio": 0,
   "seed": 0,
   "size": 0,
   "status": 5, // 1: Generation successful, 5: In progress, 7: Moderation failed, 8: Generation failed.
   "style": "string",
   "url": "string" // The url is accessible when status is 1.
 }
}

7. Download the Generated Video

You can access a generated video with "url"

  {
 "ErrCode": 0,
 "ErrMsg": "string",
 "Resp": {
   "create_time": "string",
   "id": 0,
   "modify_time": "string",
   "negative_prompt": "string",
   "outputHeight": 0,
   "outputWidth": 0,
   "prompt": "string",
   "resolution_ratio": 0,
   "seed": 0,
   "size": 0,
   "status": 1, // 1: Generation successful, 5: In progress, 7: Moderation failed, 8: Generation failed.
   "style": "string",
   "url": "string" // The url is accessible when status is 1.
 }
}

Troubleshooting

Common issue

Your video is stuck in "Generating" status and hasn't completed after a long wait.

Please check if you're using the same AI-trace-ID for every request. This is the most common cause of this issue.

Status codes: 1: Generation successful; 5: Waiting for generation; 7: Content moderation failure; 8: Generation failed;

If you encounter status code 7, it means your generated video was filtered by our content moderation system. Please modify your parameters and try again. Any credits used for filtered videos will be automatically refunded to your account.

Common error codes

400/500 status : Incorrect code

400013 : Invalid binding request: incorrect parameter type or value

400017 : Invalid parameter

500044 : Reached the limit for concurrent generations.

Overview#

Prerequisites#

Quick-start#

Step-by-Step Guide#

1. Prepare Your Image#

2. Prepare Your upload image API Request and uplaod image to get img_id#

3. Prepare your image-to-video API request#

4. Parameter details#

5. Handle the API Response#

6. Check Generation Status#

7. Download the Generated Video#

Troubleshooting#

Common issue#

Common error codes#

Overview

Prerequisites

Quick-start

Step-by-Step Guide

1. Prepare Your Image

2. Prepare Your upload image API Request and uplaod image to get img_id

3. Prepare your image-to-video API request

4. Parameter details

5. Handle the API Response

6. Check Generation Status

7. Download the Generated Video

Troubleshooting

Common issue

Common error codes