---
title: "Generate a video"
method: POST
path: "/ai/videos"
tags: ["Generation"]
---

# Generate a video

`POST /ai/videos`

## Request

- Base URL: `https://api.vidmoat.com/v1`
- URL: `https://api.vidmoat.com/v1/ai/videos`
- Auth: HTTP bearer

Start a generated clip with Grok, Alibaba HappyHorse or Wan 3.0. Returns a job to poll. Paid Studio only; trials and full-waiver promotions are excluded.

Priced per second, not flat. Grok: 40 credits a second (200 for the 5-second default, 600 for the 15-second maximum). HappyHorse 1.1 (`provider: "qwen"`): 112, 224 or 288 a second at 480p, 720p or 1080p, 3 to 15 seconds. Wan 3.0 (`provider: "wan"`): 80, 160 or 320 a second, 2 to 15 seconds. Use quoteOnly:true first, then pin the provider and maxCredits. One video job runs at a time per account. A HappyHorse first frame keeps the image's aspect ratio, so omit aspectRatio; HappyHorse has no audio control. Google video is not supported.

## Request body

- object
  - `prompt` string, required: Up to 800 characters.
  - `durationSec` integer: Whole seconds, from the provider's minimum (Grok 1, Wan 2, HappyHorse 3) to 15.
  - `provider` 'grok' | 'qwen' | 'wan' | 'auto': `qwen` is Alibaba HappyHorse 1.1. Auto picks the cheapest compatible route (and is the default when you ask for 1080p without a provider).
  - `resolution` '480p' | '720p' | '1080p': Grok does not do 1080p.
  - `aspectRatio` string: 16:9, 9:16, 1:1, 4:3, 3:4, 4:5, 5:4, 9:21 or 21:9 (Wan: 16:9, 9:16, 1:1, 4:3, 3:4, 21:9).
  - `referenceUrls` string[]: Up to 7 reference images for consistency: your uploads or public HTTPS images. Grok with references is limited to 720p. Not with `imageUrl`.
  - `imageUrl` string: A starting frame. Not with `referenceUrls`.
  - `withAudio` boolean: Generate audio where the provider supports it (not HappyHorse).
  - `projectId` string: Project to attach the job to.
  - `maxCredits` number: Never spend more than this.
  - `quoteOnly` boolean: `true` returns the route and price without starting a job.

## Response `202`

Generate a video

- object
  - `id` string: The job id. Poll it with Get a generation job.
  - `status` string: `PROCESSING`.
  - `durationSec` integer: Seconds billed.
  - `credits` object: `{ charged, remaining, basis }`.
  - `poll` string: The path to poll.

## Other responses

- `400`: `invalid_request`: No prompt, or a refused reference.
- `402`: `plan_required`: The plan has no video generation. `insufficient_credits`: Not enough credits, or the account is on a trial or a full-waiver promotion. `quota_exceeded`: A video job is already running on the account.
- `422`: `prompt_rejected`: The prompt failed the safety check. Nothing was charged. `field` names the field.
- `502`: `provider_error`: The generation provider failed. The charge is refunded.

---

[API](https://skmtc.dev/vidmoat/apis/vidmoat-api.md) · [All operations](https://skmtc.dev/vidmoat/apis/vidmoat-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vidmoat/apis/vidmoat-api/revisions/23e24e25c756?raw)