PixVerse Platform Docs
  1. Getting started
PixVerse Platform Docs
  • Learn about PixVerse Platform
    • Introduce to PixVerse Platform
    • Quick Start
  • Getting started
    • How does the API work?
    • How to get API key?
    • How to check account balance?
    • How to subscribe API plans?
    • How to use Text-to-video
    • How to use Image-to-video
    • How to use Effects?
    • How to use Transition(First-last frame Feature)
    • How to get video generation status?
  • API Reference
    • API Parameter Description
    • Get user credit balance
      GET
    • Upload Image
      POST
    • Text-to-Video generation
      POST
    • Image-to-Video generation
      POST
    • Transition(First-last frame) generation
      POST
    • Get Video Generation Status
      GET
  • Trouble Shooting
    • Common errors and Solutions
    • Error codes
    • FAQ
  • Resources
    • Model & Pricing
    • Rate limit
    • Support
    • Change Logs
    • Term of Service
    • Privacy policy
  • PixVerse Tools
    • PixVerse MCP
  1. Getting started

How to use Text-to-video

How to Generate Text-to-Video#

The Text-to-Video API transforms textual descriptions into dynamic video content. This guide will walk you through the process of generating videos from text prompts.

Overview#

The Text-to-Video endpoint allows you to create videos by providing a text description (prompt) and various customization parameters. Our AI model interprets your text prompt and generates a video that matches your description.
Endpoint: POST https://app-api.pixverse.ai/openapi/v2/video/text/generate
API Reference : https://docs.platform.pixverse.ai/text-to-video-generation-13016634e0

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 clear text description of the video you want to generate

Step-by-Step Guide#

1. Craft Your Text Prompt#

The quality of your prompt significantly impacts the generated video. Here are some tips:
Be specific and descriptive
Include details about scene, movement, lighting, and atmosphere
Keep prompts between 25-200 words for optimal results

Examples of Effective Prompts:#

✅ Good prompt: "A serene mountain lake at sunrise, with mist rising from the water. The camera slowly pans across the lake, capturing the golden sunlight reflecting on the surface. Birds fly overhead as the morning unfolds."
❌ Less effective prompt: "Mountain lake sunrise"

2. Prepare Your API Request#

Construct your API request with the appropriate parameters:

3. Parameter Details#

Parameter NameRequiredTypeDescription
modelRequiredstringv3.5
promptRequiredstring=< 2048 characters
negative_promptOptionalstring=< 2048 characters
template_idOptionalintegerMust activate effects in effects management before use.
Some effects don't support certain resolutions, please check effects management
camera_movementOptionalstringAdd your camera_movement on your videos(supports v4/v4.5 model)
supports value: "horizontal_left","horizontal_right","vertical_up","vertical_down",
"zoom_in","zoom_out","auto_camera","crane_up",
"quickly_zoom_in","quickly_zoom_out","smooth_zoom_in",
"camera_rotation","robo_arm","super_dolly_out","whip_pan","hitchcock",
"left_follow","right_follow","pan_left","pan_right","fix_bg"
styleOptionalstring"anime"
"3d_animation"
"day"
"cyberpunk"
"comic"
Do not include style parameter unless needed
motion_modeOptionalstringDefault - "normal"
"fast"(only allows 5-second duration)
1080p doesn't support "fast". If not provided, defaults to normal
durationRequiredinteger5,8
1080p doesn't support 8
qualityRequiredstring"360p"(Turbo model), "540p", "720p", "1080p"
seedOptionalintegerRandom seed, int32 random number between 0 - 2147483647

4. Handle the API Response#

The API returns a JSON response with a video_id:
{
  "ErrCode": 0,
  "ErrMsg": "success",
  "Resp": {
    "video_id": 0
  }
}

5. 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,
   "style": "string",
   "url": "string"
 }
}

6. 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,
   "style": "string",
   "url": "string"
 }
}

Trobule shooting#

Common issue#

1.
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.
2.
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.
Previous
How to subscribe API plans?
Next
How to use Image-to-video