Veo 3.1 Official

veo-3.1-official supports text-to-video, first-frame, and first-and-last-frame generation. Choose fast or quality mode to generate 4-, 6-, or 8-second videos at 720p, 1080p, or 4k. Audio is off by default; enable it with generate_audio.

This page covers the separate veo-3.1-official model. For veo-3 or veo-3-extend, see the Veo 3.1 documentation. Their parameters and pricing differ.

Model and Endpoints

Generation and task queries require an Authorization: Bearer sk-your-api-key header. See Authentication. Use Content-Type: application/json for generation and estimate requests.

Pricing

Pricing depends on mode, resolution, audio, and requested duration. The following rates are in credits per second before account multipliers. Input images carry no additional charge.

Base credits = credits per second × requested duration. Apply the account multiplier to the base credits, then round to two decimal places using exact decimal rounding, with halves rounded up.

When you supply only prompt, the defaults are fast, 8 seconds, 720p, 16:9, and no audio. At the standard multiplier of 1, this costs 16.64 × 8 = 133.12 credits. With an account multiplier of 0.75, the same request costs 99.84 credits.

Credits are pre-charged when the task is created. Successful tasks settle at the price recorded at submission; later price or account multiplier changes do not reprice the task.

Request Parameters

Request Body

Input Parameters

Numbers and booleans must use native JSON types. For example, 8, 1, true, and false are valid types; "8", "1", "true", and "false" are not. Omit optional fields to use their defaults; null is not a substitute for omission.

Images must be directly downloadable. Local file paths and Base64 data are unsupported. For text-to-video, omit both image fields; no generation-type parameter is needed.

This model does not support lite, the Auto aspect ratio, reference-based generation, or video extension. Do not send the legacy fields image_urls, video_urls, generation_type, seeds, watermark, enable_translation, or n. Use singular seed and the first/last-frame fields above.

Generation Examples

Replace the example API key and image URLs with your own values.

Text-to-Video

This minimal request uses all defaults and costs 133.12 credits at the standard multiplier.

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-official",
    "input": {
      "prompt": "A drone slowly glides over mountains at sunset, soft golden light, cinematic camera movement"
    }
  }'

First-Frame Generation

Use first_frame_image to set the first frame. This example creates a 6-second portrait video at 1080p without audio, costing 20.80 × 6 = 124.80 credits at the standard multiplier.

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-official",
    "input": {
      "prompt": "The camera slowly moves toward a vase as sunlight shifts naturally by the window",
      "mode": "fast",
      "duration": 6,
      "resolution": "1080p",
      "aspect_ratio": "9:16",
      "generate_audio": false,
      "first_frame_image": "https://example.com/first-frame.jpg",
      "resize_mode": "crop",
      "person_generation": "disallow",
      "seed": 123456
    }
  }'

First and Last Frames with Audio

Supply both frames and set generate_audio: true. This example uses quality, 4 seconds, and 4k, costing 124.80 × 4 = 499.20 credits at the standard multiplier.

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-official",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "A beach transitions from early dawn to sunrise, smooth forward camera movement, gentle ocean sounds",
      "mode": "quality",
      "duration": 4,
      "resolution": "4k",
      "aspect_ratio": "16:9",
      "generate_audio": true,
      "first_frame_image": "https://example.com/start.jpg",
      "last_frame_image": "https://example.com/end.jpg",
      "resize_mode": "pad",
      "negative_prompt": "blur, camera shake",
      "person_generation": "disallow",
      "sample_count": 1,
      "enhance_prompt": true,
      "nsfw_checker": true
    }
  }'

Estimate Credits

Send the same model and input as your generation request to the estimate endpoint. Estimates and generation share parameter defaults and validation. Estimation does not charge credits or create a task.

curl -X POST https://api.aivideoapi.ai/v1/estimate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-official",
    "input": {
      "prompt": "A drone slowly glides over mountains at sunset, soft golden light, cinematic camera movement"
    }
  }'

With the default parameters and standard multiplier, the main response fields are shown below. Additional pricing details are omitted:

{
  "model": "veo-3.1-official",
  "credits": 133.12,
  "base_credits": 133.12,
  "multiplier": 1,
  "pricing_type": "formula"
}

base_credits is the amount before the multiplier; credits is the estimate after applying the account multiplier. Include an API key to use your account multiplier, or omit authentication for the standard rate. Estimates match the task pre-charge when the input, pricing, and account multiplier are unchanged. An estimate does not reserve a price; the submission price applies.

Creation Response and Task Queries

A successful creation response returns a task ID; it does not mean the video has finished generating:

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1"
  }
}

Save data.taskId and query it with an API key belonging to the same account:

curl https://api.aivideoapi.ai/v1/tasks/2e723e68-7a4a-4f38-a27a-8e638f6c44a1 \
  -H "Authorization: Bearer sk-your-api-key"

Statuses are pending while waiting, processing during processing, completed on completion, and failed on failure. Successfully cancelled tasks have status cancelled. Queries may skip intermediate states.

created_at and completed_at are Unix timestamps in seconds. output.metadata is optional; use output.urls to retrieve the video. Archived or cleared historical tasks may return output: null, so save your results promptly.

Processing

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "processing",
  "model": "veo-3.1-official",
  "credits_consumed": 0,
  "created_at": 1793318400,
  "progress": null
}

credits_consumed is the final consumption. A value of 0 during processing does not mean credits have not been pre-charged. progress: null means no percentage progress is available.

Completed

The following example shows a completed default request at the standard multiplier. Read the video URL from output.urls:

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "completed",
  "model": "veo-3.1-official",
  "credits_consumed": 133.12,
  "created_at": 1793318400,
  "completed_at": 1793318520,
  "output": {
    "urls": [
      "https://file.aivideoapi.ai/videos/example.mp4"
    ]
  }
}

Failed

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "failed",
  "model": "veo-3.1-official",
  "credits_consumed": 0,
  "created_at": 1793318400,
  "error": {
    "code": "upstream_error",
    "message": "Video generation failed."
  }
}

Confirmed failures refund the original pre-charge once; repeated queries do not trigger duplicate refunds. Successfully generated videos are not refunded because of later query, callback, or delivery issues. If a task encounters a temporary query error or delivery delay, continue querying the original task instead of immediately submitting again, which can create separately billed tasks.

Callbacks and Cancellation

Set callback_url when creating the task to receive completion or failure POST notifications. Callbacks carry the same task ID, status, final consumption, and result or error fields as task queries. Handle repeated notifications idempotently by task ID. See Callbacks for notification headers and retry rules. You can still query the final result if callback delivery fails.

Tasks cannot be cancelled after generation starts. Only queued tasks that have not begun execution may be cancelled with DELETE /v1/tasks/{taskId}, refunding the original pre-charge. The server response determines whether cancellation is available; a pending status alone does not guarantee it.

If cancellation is unavailable, the API returns HTTP 409 with error code task_not_cancellable. A rejected cancellation does not refund credits. See Error Codes for general API errors.