Video API

Veo 3.1

POST https://api.beatapi.io/v1/videos/tasks

Generate fixed 8-second videos with selectable Quality, Fast, or Lite tiers and 720p, 1080p, or 4K output. Text and frame generation default to Quality at 720p; reference images require Fast or Lite.

Supported modes

ModeRequired inputRules
Qualitymodel, promptSet quality=Quality and optional resolution (720p, 1080p, or 4k).
Fastmodel, promptSet quality=Fast and optional resolution (720p, 1080p, or 4k).
Litemodel, promptSet quality=Lite and optional resolution (720p, 1080p, or 4k).
First and last framesmodel, prompt, imagesProvide one first-frame URL or two URLs in first-to-last order.
Reference imagesmodel, prompt, reference_imagesProvide 1–3 URLs, use Fast or Lite, and do not combine with images.

Async flow: Create the task, save data.id, then poll the Task with GET /v1/tasks/{task_id}. On succeeded, read data.output.media. On failed, read data.error_code and data.error_message, then follow the error and retry policy.

Using a local file? upload a local input first and pass the returned data.url.

Authorization

Authorization   string   required

Send your BeatAPI API key as a Bearer token. Create one on the Dashboard.

Authorization: Bearer <BEATAPI_API_KEY>

Keep permanent API keys on trusted servers. Content-Type: application/json is required for the request body. Idempotency-Key is optional when the endpoint exposes it and is recommended for safe retries with the exact same body.

Request body

model   string   required

Must be veo-3.1.

Value: veo-3.1

prompt   string   required

Video generation instructions.

Length: 1 to 5000 characters

images   string[]   optional

One first-frame image or first- and last-frame images as public HTTPS URLs.

Count: 1 to 2 items

aspect_ratio   enum<string>   optional

Output video aspect ratio.

Available options: 16:9, 9:16, auto
Default: "16:9"

resolution   enum<string>   optional

Output video resolution. 4k and 4K are equivalent. Price depends on quality and resolution.

Available options: 720p, 1080p, 4k, 4K
Default: "720p"

quality   enum<string>   optional

Text or frame generation tier. Reference-image generation tier.

Available options: Quality, Fast, Lite
Default: "Quality", "Fast"

watermark   string   optional

Optional watermark text forwarded to the selected model.

enable_translation   boolean   optional

Allow prompt translation before generation.

reference_images   string[]   required for some modes

Public HTTPS reference images.

Count: 1 to 3 items

Request examples

Quality

$curl --request POST \
>  --url https://api.beatapi.io/v1/videos/tasks \
>  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "model": "veo-3.1",
>  "prompt": "A cinematic aerial reveal of a quiet coastal village at sunrise.",
>  "aspect_ratio": "16:9",
>  "resolution": "720p",
>  "quality": "Quality"
>}'

Fast

$curl --request POST \
>  --url https://api.beatapi.io/v1/videos/tasks \
>  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "model": "veo-3.1",
>  "prompt": "A fast cinematic product reveal with natural camera motion.",
>  "aspect_ratio": "16:9",
>  "resolution": "1080p",
>  "quality": "Fast"
>}'

Lite

$curl --request POST \
>  --url https://api.beatapi.io/v1/videos/tasks \
>  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "model": "veo-3.1",
>  "prompt": "A concise storyboard-ready product reveal.",
>  "aspect_ratio": "16:9",
>  "resolution": "4k",
>  "quality": "Lite"
>}'

First and last frames

$curl --request POST \
>  --url https://api.beatapi.io/v1/videos/tasks \
>  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "model": "veo-3.1",
>  "prompt": "Move smoothly from the opening portrait to the final product reveal.",
>  "images": [
>    "https://media.beatapi.io/samples/neon-singer.png",
>    "https://media.beatapi.io/samples/smart-bottle.png"
>  ],
>  "aspect_ratio": "16:9",
>  "resolution": "720p",
>  "quality": "Quality"
>}'

Reference images (Fast)

$curl --request POST \
>  --url https://api.beatapi.io/v1/videos/tasks \
>  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "model": "veo-3.1",
>  "prompt": "Create a cohesive cinematic scene using the supplied visual references.",
>  "reference_images": [
>    "https://media.beatapi.io/samples/neon-singer.png",
>    "https://media.beatapi.io/samples/smart-bottle.png"
>  ],
>  "aspect_ratio": "16:9",
>  "resolution": "720p",
>  "quality": "Fast"
>}'

Response

A successful request returns HTTP 201.

1{
2  "data": {
3    "id": "task_8K2qA",
4    "object": "task",
5    "task_kind": "video",
6    "capability_id": "veo-3.1",
7    "capability_version": null,
8    "media_type": "video",
9    "model": "veo-3.1",
10    "status": "queued",
11    "stage": "queued",
12    "created_at": 1782210000,
13    "updated_at": 1782210000,
14    "completed_at": null,
15    "output": null,
16    "usage": {
17      "credits_reserved": 2.0,
18      "credits_charged": 2.0,
19      "billable_duration_seconds": 8,
20      "credits_settled": 0,
21      "credits_refunded": 0
22    },
23    "request_id": "req_abc123",
24    "error_code": null,
25    "error_message": null
26  }
27}

Errors

StatusMeaning
400Invalid request.
401Missing, invalid, or inactive API key.
402Insufficient USD balance
409Idempotency key conflicts with another request body
429Request rate limit exceeded.