Generate Videos

Create AI-generated videos from text prompts, source images, or existing captions.

Generate Videos

POST /api/v1/videos/generate

Generate AI videos from a text prompt, a source image, or an existing caption generation. Post mode rewrites that caption into a video prompt for the length, frame, and audio you set. If the post has a photo, that photo is the opening frame. Some models then keep the photo's aspect ratio. Others use size as the output frame.

Video generation requires at least one credit purchase on the account. Signup credits are not enough. See Purchase required.

Request Body

Field	Type	Default	Description
`prompt`	string	—	Required unless `generation_id` is set. With a post, this is optional extra direction.
`size`	string	`landscape`	`landscape` (16:9) or `portrait` (9:16). Output frame for text-to-video. When an opening image is attached, some models keep the image's aspect ratio and only store this value. Others use it as the output frame.
`duration`	integer	—	Whole seconds only. Must be a length that model allows.
`model`	string	current default	Video model. Leave it out to use the current default.
`has_audio`	boolean	`false`	Generate with audio. Not every model supports it. Post mode includes this in the rewrite.
`enhance_prompt`	boolean	`false`	Polish a prompt you wrote. Ignored for post mode, which always rewrites the caption.
`source_image`	uuid	—	Media ID of an image for image-to-video. Cannot be combined with `generation_id`.
`generation_id`	uuid	—	Caption generation to turn into a video.
`source_post_type`	string	—	Which post type's caption to use. Use with `generation_id`.

Models

model is optional. Leave it out to use the current default. size, duration, audio, and prompt length have to be valid for that model. If they are not, the API returns 400.

This uses credits. The amount depends on the model, the duration, and whether audio is on. The response includes credits_used.

Example — Text-to-Video

curl -X POST https://powerpost.ai/api/v1/videos/generate \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A golden retriever running through a field of wildflowers at sunset",
    "size": "landscape",
    "duration": 5,
    "has_audio": false
  }'

Response

{
  "video_generation_id": "7a8b9c0d-e1f2-3456-abcd-ef7890123456",
  "status": "processing",
  "credits_used": 15,
  "remaining_credits": 85,
  "status_url": "/api/v1/videos/generations/7a8b9c0d-e1f2-3456-abcd-ef7890123456"
}

Errors

Code	Description
400	Invalid request body, an unsupported model/size/duration combination, or `source_image` not found
401	Invalid API key
402	Insufficient credits (`INSUFFICIENT_CREDITS`)
402	Purchase required (`MEDIA_REQUIRES_PURCHASE`)
403	API key is missing the `videos:generate` scope
429	Rate limit exceeded

Example — Image-to-Video

Upload an image first via Upload Media, then pass its media_id as source_image.

size is accepted here too. It defaults to landscape and is stored on the job. Some models follow the image's aspect ratio. Others use size as the output frame. video.width and video.height are that stored size.

curl -X POST https://powerpost.ai/api/v1/videos/generate \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The dog starts running and jumps over a fence",
    "source_image": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "size": "landscape",
    "duration": 5
  }'

Get Video Generation Status

GET /api/v1/videos/generations/{id}

Poll this endpoint to check if your video is ready.

Response — Processing

{
  "video_generation_id": "7a8b9c0d-...",
  "status": "processing",
  "prompt": "A golden retriever running...",
  "size": "landscape",
  "duration": 5,
  "has_audio": false,
  "model": "kling-3.0-pro",
  "created_at": "2026-03-11T10:00:00Z"
}

Response — Completed

{
  "video_generation_id": "7a8b9c0d-...",
  "status": "completed",
  "prompt": "A golden retriever running...",
  "size": "landscape",
  "duration": 5,
  "has_audio": false,
  "model": "kling-3.0-pro",
  "created_at": "2026-03-11T10:00:00Z",
  "video": {
    "media_id": "vid-001-abcd",
    "url": "https://powerpost.ai/storage/videos/vid-001-abcd.mp4",
    "thumbnail_url": "https://powerpost.ai/storage/thumbs/vid-001-abcd.jpg",
    "width": 1920,
    "height": 1080,
    "duration": 5
  }
}

Response — Failed

{
  "video_generation_id": "7a8b9c0d-...",
  "status": "failed",
  "prompt": "A golden retriever running...",
  "size": "landscape",
  "duration": 5,
  "has_audio": false,
  "model": "kling-3.0-pro",
  "created_at": "2026-03-11T10:00:00Z",
  "error": {
    "code": "VIDEO_GENERATION_FAILED",
    "message": "Video generation timed out"
  }
}

Video URLs are signed and valid for 7 days. Use media_id to reference the video permanently when creating posts.

Errors

Code	Description
401	Invalid API key
403	API key is missing the `videos:read` scope
404	Video generation not found
429	Rate limit exceeded

Generate Videos

POST /api/v1/videos/generate

Video generation requires at least one credit purchase on the account. Signup credits are not enough. See Purchase required.

Request Body

Field	Type	Default	Description
`prompt`	string	—	Required unless `generation_id` is set. With a post, this is optional extra direction.
`size`	string	`landscape`	`landscape` (16:9) or `portrait` (9:16). Output frame for text-to-video. When an opening image is attached, some models keep the image's aspect ratio and only store this value. Others use it as the output frame.
`duration`	integer	—	Whole seconds only. Must be a length that model allows.
`model`	string	current default	Video model. Leave it out to use the current default.
`has_audio`	boolean	`false`	Generate with audio. Not every model supports it. Post mode includes this in the rewrite.
`enhance_prompt`	boolean	`false`	Polish a prompt you wrote. Ignored for post mode, which always rewrites the caption.
`source_image`	uuid	—	Media ID of an image for image-to-video. Cannot be combined with `generation_id`.
`generation_id`	uuid	—	Caption generation to turn into a video.
`source_post_type`	string	—	Which post type's caption to use. Use with `generation_id`.

Models

model is optional. Leave it out to use the current default. size, duration, audio, and prompt length have to be valid for that model. If they are not, the API returns 400.

This uses credits. The amount depends on the model, the duration, and whether audio is on. The response includes credits_used.

Example — Text-to-Video

curl -X POST https://powerpost.ai/api/v1/videos/generate \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A golden retriever running through a field of wildflowers at sunset",
    "size": "landscape",
    "duration": 5,
    "has_audio": false
  }'

Response

{
  "video_generation_id": "7a8b9c0d-e1f2-3456-abcd-ef7890123456",
  "status": "processing",
  "credits_used": 15,
  "remaining_credits": 85,
  "status_url": "/api/v1/videos/generations/7a8b9c0d-e1f2-3456-abcd-ef7890123456"
}

Errors

Code	Description
400	Invalid request body, an unsupported model/size/duration combination, or `source_image` not found
401	Invalid API key
402	Insufficient credits (`INSUFFICIENT_CREDITS`)
402	Purchase required (`MEDIA_REQUIRES_PURCHASE`)
403	API key is missing the `videos:generate` scope
429	Rate limit exceeded

Example — Image-to-Video

Upload an image first via Upload Media, then pass its media_id as source_image.

curl -X POST https://powerpost.ai/api/v1/videos/generate \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The dog starts running and jumps over a fence",
    "source_image": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "size": "landscape",
    "duration": 5
  }'

Get Video Generation Status

GET /api/v1/videos/generations/{id}

Poll this endpoint to check if your video is ready.

Response — Processing

{
  "video_generation_id": "7a8b9c0d-...",
  "status": "processing",
  "prompt": "A golden retriever running...",
  "size": "landscape",
  "duration": 5,
  "has_audio": false,
  "model": "kling-3.0-pro",
  "created_at": "2026-03-11T10:00:00Z"
}

Response — Completed

{
  "video_generation_id": "7a8b9c0d-...",
  "status": "completed",
  "prompt": "A golden retriever running...",
  "size": "landscape",
  "duration": 5,
  "has_audio": false,
  "model": "kling-3.0-pro",
  "created_at": "2026-03-11T10:00:00Z",
  "video": {
    "media_id": "vid-001-abcd",
    "url": "https://powerpost.ai/storage/videos/vid-001-abcd.mp4",
    "thumbnail_url": "https://powerpost.ai/storage/thumbs/vid-001-abcd.jpg",
    "width": 1920,
    "height": 1080,
    "duration": 5
  }
}

Response — Failed

{
  "video_generation_id": "7a8b9c0d-...",
  "status": "failed",
  "prompt": "A golden retriever running...",
  "size": "landscape",
  "duration": 5,
  "has_audio": false,
  "model": "kling-3.0-pro",
  "created_at": "2026-03-11T10:00:00Z",
  "error": {
    "code": "VIDEO_GENERATION_FAILED",
    "message": "Video generation timed out"
  }
}

Video URLs are signed and valid for 7 days. Use media_id to reference the video permanently when creating posts.

Errors

Code	Description
401	Invalid API key
403	API key is missing the `videos:read` scope
404	Video generation not found
429	Rate limit exceeded

Generate Videos

Generate Videos

Request Body

Models

Example — Text-to-Video

Response

Errors

Example — Image-to-Video

Get Video Generation Status

Response — Processing

Response — Completed

Response — Failed

Errors

See Also

On this page

Generate Videos

Generate Videos

Request Body

Models

Example — Text-to-Video

Response

Errors

Example — Image-to-Video

Get Video Generation Status

Response — Processing

Response — Completed

Response — Failed

Errors

See Also

On this page