---
title: "Create an AI video generation job"
method: POST
path: "/api/v1/ai/generate-video"
tags: ["AI"]
---

# Create an AI video generation job

`POST /api/v1/ai/generate-video`

## Request

- Base URL: `https://www.poster.ly`
- URL: `https://www.poster.ly/api/v1/ai/generate-video`
- Auth: HTTP bearer

Queue a cost-guarded Google Veo or xAI Grok Imagine video generation job. This can spend included or purchased AI credits. Poll `/api/v1/ai/video-jobs/{id}` for status and the final `video_url`.

## Request body

- GenerateVideoRequest
  - `workspace_id` string: Optional. The workspace this call acts in and whose plan and credits it uses (from whoami). Needed only when the key can act in several workspaces.
  - `provider` 'google' | 'xai'
  - `prompt` string, required
  - `negative_prompt` string, nullable
  - `aspect_ratio` '1:1' | '16:9' | '9:16' | '4:3' | '3:4' | '3:2' | '2:3'
  - `duration_seconds` integer
  - `resolution` '480p' | '720p' | '1080p'
  - `model` 'lite' | 'fast' | 'standard': Google Veo tier. Ignored when provider is xai.
  - `image_url` string, uri, nullable
  - `end_image_url` string, uri, nullable
  - `reference_images` object[], nullable
    - `url` string, uri, required
    - `type` 'character' | 'object' | 'scene', required
  - `generate_audio` boolean: Google can disable generated audio. xAI Grok includes audio and requires this to remain true.
  - `source_video_url` string, uri, nullable

## Response `202`

Video generation job accepted

- GenerateVideoResponse
  - `job_id` string, required
  - `status` string, required
  - `message` string
  - `credit_cost` number, required
  - `included_credit_cost` number
  - `purchased_credit_cost` number
  - `current_balance` number
  - `purchased_balance` number, nullable
  - `included_credits_remaining` number

## Other responses

- `400`: Validation error
- `401`: Invalid or missing API key
- `402`: Validation error
- `429`: Too many requests

---

[API](https://skmtc.dev/poster/apis/posterly-api.md) · [All operations](https://skmtc.dev/poster/apis/posterly-api/llms.txt) · [OpenAPI document](https://skmtc.dev/poster/apis/posterly-api/revisions/60be02a61f95?raw)