Veo 3.1

Generate 8-second videos with sound at 720p, 1080p or 4K from text, one or two frames, or up to three reference images; pick Quality, Fast or Lite, each priced on its own.

• Asynchronous: the create call returns a task ID; the video arrives when the task succeeds.
• One model ID, three tiers: quality chooses Quality, Fast or Lite, and each is priced on its own at each resolution.
• There is no duration field: the model sets the length, and the price is per video (the price list describes it as 8 seconds with sound).
• Reference images need Fast or Lite: leave quality out and Fast is used; asking for Quality is refused. Text and frame requests default to Quality.
• Billed per video by tier and resolution, not by the second. A failed task costs nothing.

Opens this model in the API Explorer. Enter your BeatAPI API key to create a task: the call is real and is billed to your own balance.

Endpoint and authentication

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

Send the body as JSON with Content-Type: application/json. Idempotency-Key is optional: send a unique value (at most 255 characters) per logical request and reuse it only to retry that exact body. Within 24 hours a retry with the same key and body returns the first response again with Idempotent-Replayed: true; the same key with a different body returns 409 idempotency_conflict. Responses other than 2xx are not stored, so a retry after a 400 or 402 runs again.

How a request works

Input modes

Request parameters

The gateway also checks these combinations before creating the task:

• images cannot be combined with reference inputs

Input media limits

The gateway reads every input before the task is created and refuses one outside these limits with a 400 bad_request that names the input. Nothing is charged.

• The gateway checks only that every image is a public HTTPS link. It does not measure size, format or dimensions before the task is created, so an image the model cannot use fails the task after submission; the message says what to change and the whole reservation is returned.
• Have a local file? Upload it with POST /v1/files and pass the returned data.url.

Choosing a tier

One model ID covers three tiers. They are separate products with separate prices, picked with quality.

• Prices at each resolution are in the table under Billing. Quality is the most expensive tier and Lite the cheapest at every resolution.

Fields this model does not accept

Sending one of these is refused before anything is charged, instead of being ignored:

• duration → field "duration" is not supported by model veo-3.1. Every Veo 3.1 video is 8 seconds long; there is nothing to choose.
• reference_videos, reference_audios, generate_audio, seed, sound, task_type, output_format → field "<name>" is not supported by model veo-3.1 (with the field you sent). There is no field to turn sound on or off.
• Any other unknown field → unknown field: <name>.

Request examples

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 slow tracking shot along a rain-lit night market, neon reflections on wet stone, ambient crowd sound",
  "quality": "Fast",
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

Text to video (Fast)

An 8-second 720p clip on the Fast tier. quality is sent on purpose: left out, a text request is billed as 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 slow tracking shot along a rain-lit night market, neon reflections on wet stone, ambient crowd sound",
  "quality": "Fast",
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

Text to video (Quality, 1080p)

The Quality tier at 1080p, portrait.

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, gulls calling, waves on the shore",
  "quality": "Quality",
  "aspect_ratio": "9:16",
  "resolution": "1080p"
}'

Text to video (Lite, 4K)

4k and 4K are the same value.

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 close-up of coffee being poured into a white cup, steam rising, soft kitchen sounds",
  "quality": "Lite",
  "aspect_ratio": "16:9",
  "resolution": "4k"
}'

First and last frame

The video moves from the first image to the second. With one link in images it starts from that image.

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": "The camera pushes in from the bottle on the table to the singer on a neon stage in one continuous move",
  "images": [
    "https://media.beatapi.io/samples/smart-bottle.png",
    "https://media.beatapi.io/samples/neon-singer.png"
  ],
  "quality": "Quality",
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

Reference images

Needs Fast or Lite, and aspect_ratio 16:9 or 9:16.

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": "The singer from the second reference image walks past the bottle from the first reference image on a neon street, handheld camera",
  "reference_images": [
    "https://media.beatapi.io/samples/smart-bottle.png",
    "https://media.beatapi.io/samples/neon-singer.png"
  ],
  "quality": "Fast",
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

Responses

Create a task (201)

The task object. output is null until the task succeeds. Fields marked “while running” disappear once the task finishes.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "veo-3.1",
    "capability_version": 1,
    "media_type": "video",
    "model": "veo-3.1",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 8,
    "output": null,
    "usage": {
      "credits_reserved": 0.3,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.3
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Finished task

GET /v1/tasks/{task_id} returns HTTP 200 with status: "succeeded" and the result in data.output.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "veo-3.1",
    "capability_version": 1,
    "media_type": "video",
    "model": "veo-3.1",
    "status": "succeeded",
    "stage": "succeeded",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": {
      "media": [
        {
          "type": "video",
          "url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4",
          "mime_type": "video/mp4"
        }
      ],
      "r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4"
    },
    "usage": {
      "credits_reserved": 0.3,
      "credits_settled": 0.3,
      "credits_refunded": 0,
      "credits_charged": 0.3
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Output fields

Failed task

A failed task is still HTTP 200 on GET /v1/tasks/{task_id}: the failure is in the body. The reservation is returned in full, so nothing is charged.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "veo-3.1",
    "capability_version": 1,
    "media_type": "video",
    "model": "veo-3.1",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.3,
      "credits_settled": 0,
      "credits_refunded": 0.3,
      "credits_charged": 0
    },
    "retryable": true,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": "processing_failed",
    "error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
  }
}

Complete example

Create a task, wait for it with the server’s polling hint, and print the result URLs. Set BEATAPI_API_KEY in your environment and install requests.

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
    # One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(3):
        response = requests.post(f"{API}/v1/videos/tasks", headers=headers, json=body, timeout=60)
        if response.status_code in (429, 503) and attempt < 2:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        break
    try:
        payload = response.json()
    except ValueError:  # an edge error page is not JSON
        response.raise_for_status()
        raise
    if not response.ok:
        error = payload["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
    return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        if response.status_code == 429 or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        response.raise_for_status()
        task = response.json()["data"]
        if task["status"] in ("succeeded", "failed"):
            return task
        time.sleep(task.get("poll_after_seconds", 5))
    raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
  "model": "veo-3.1",
  "prompt": "A slow tracking shot along a rain-lit night market, neon reflections on wet stone, ambient crowd sound",
  "quality": "Fast",
  "aspect_ratio": "16:9",
  "resolution": "720p"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
    raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
    print(item["url"])

Billing

• The price is per video, not per second: every video is 8 seconds, and the price depends on the tier (quality) and the resolution. Sound is included.
• The list below has one row per tier and resolution. Quality is the most expensive tier and Lite the cheapest at every resolution; 4K costs the most within a tier.
• Leave quality out and a text or frame request is billed as Quality, while a reference-image request is billed as Fast. Send quality to be sure of the price.
• The price is reserved when the task is created and settled when the video is ready. A failed task, including one refused by moderation after submission, is refunded in full.

Current list prices, the same as on Pricing. An account with a negotiated discount pays less; data.usage on the task always shows the amount actually charged.

Common errors

HTTP errors at a glance

Errors before a task exists arrive as a non-2xx response, and nothing is charged. Branch on error.code or error.retryable; message names the problem. The full list and retry policy are on Errors.

{
  "error": {
    "code": "bad_request",
    "message": "\"prompt\" is required",
    "retryable": false,
    "request_id": "req_5f0c2a9e4b7d4e31"
  }
}