Veo Video Generation

This guide is for developers: how to call Google Veo video generation models through aicentos. The API follows the OpenAI Videos API compatible format — use the openai channel type when integrating downstream.

Model capabilitiesCopy anchor link

Billing is based on video generation duration in seconds. See the aicentos console for exact unit prices; the final charge is based on the system's actual billing records.

Official capabilities vs. what aicentos exposesCopy anchor link

Reference docs:

• Google Gemini API Veo video generation
• Veo reference images
• Veo first and last frames
• Veo aspect ratio

Aspect ratioCopy anchor link

Set the aspect ratio via metadata.aspectRatio in JSON or the aspectRatio form field:

{
  "metadata": {
    "aspectRatio": "9:16"
  }
}

If aspectRatio is not passed explicitly, the system derives it from size first — for example, 1280x720 maps to 16:9 and 720x1280 to 9:16. If size is missing too, the upstream defaults to 16:9.

AudioCopy anchor link

The Veo 3.1 series generates audio natively, but the current Gemini API Veo parameter list does not expose generateAudio as a controllable parameter. Passing it may cause the upstream to return INVALID_ARGUMENT.

To control the audio, describe the dialogue, ambient sound, sound effects or music style in the prompt, for example:

A lighthouse by the sea at dusk, waves gently lapping the rocks, low wind and distant seabirds, cinematic lighting, stable camera movement

Image input capabilitiesCopy anchor link

• Image MIME types supported: image/jpeg, image/png, image/webp. Send a file or Base64; remote image URLs are not recommended.
• Reference-image note: the upstream does not support negativePrompt in the reference-image scenario and may return Negative prompt is not supported in your use case. Do not pass negativePrompt with reference-image requests.
• Implementation note: the Gemini API Veo predictLongRunning image input uses bytesBase64Encoded + mimeType, not the inlineData used by plain generateContent. aicentos converts multipart-uploaded images into the format the upstream expects.

Billing rulesCopy anchor link

• Billed by video generation duration in seconds. Use one of the durations each model supports (see the table above); arbitrary values are not recommended.
• If the request does not specify a duration, billing defaults to 8 seconds.
• Duration resolution order: metadata.durationSeconds > duration > seconds > default 8 seconds.
• Resolution detection order: metadata.resolution > size > default 720p.
• 720p / 1080p / 4K are billed under the same rules; there is no separate resolution surcharge.
• aspectRatio only controls landscape vs. portrait; it does not change the price.
• 4K supports 8 seconds only.
• See the aicentos console for exact unit prices.

API endpointsCopy anchor link

These 3 endpoints are recommended:

To get the result URL directly from the status query, you can also use:

AuthenticationCopy anchor link

export BASE_URL="https://aicentos.com"
export AICENTOS_API_KEY="sk-xxxxxx"

All requests include:

-H "Authorization: Bearer $AICENTOS_API_KEY"

Create a text-to-video taskCopy anchor link

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "A lighthouse by the sea at dusk, slow push-in shot, waves gently lapping the rocks, cinematic lighting, stable camera movement",
    "seconds": "8",
    "size": "1280x720",
    "metadata": {
      "negativePrompt": "blurry, watermark, distorted, low quality",
      "resolution": "720p",
      "aspectRatio": "16:9",
      "seed": 20260401
    }
  }'

Typical response:

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "queued",
  "progress": 0,
  "created_at": 1775025000
}

Create an image-to-video task (first frame)Copy anchor link

For image-to-video, multipart/form-data is recommended, and the first-frame image field must be named input_reference.

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=The girl in the frame turns her head toward the camera, a light breeze moves her hair, city lights in the background softly blurred, smooth steady push-in" \
  -F "input_reference=@./first-frame.png;type=image/png" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "negativePrompt=blurry, watermark, deformed hands" \
  -F "seed=20260401"

Create a first/last frame taskCopy anchor link

First/last frame tasks require both frames: first frame via input_reference, last frame via last_frame or lastFrame.

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=Transition naturally from the first frame with a girl to the last frame with a boy, smooth steady push-in, blurred city lights, hair and clothes moving slightly in the breeze, a natural and realistic transition" \
  -F "input_reference=@./first-frame.png;type=image/png" \
  -F "last_frame=@./last-frame.png;type=image/png" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "negativePrompt=blurry, watermark, distorted face, deformed hands" \
  -F "seed=20260402"

Create a reference-image taskCopy anchor link

Reference-image tasks are supported on the Veo 3.1 series only, up to 3 images, with referenceType limited to asset. Field names: reference_image, reference_images or referenceImages. Do not pass negativePrompt on reference-image tasks.

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=Follow the characters' appearance from the two images and the night-city atmosphere to generate a cinematic two-person street shot, smooth steady push-in, background lights softly blurred, the characters looking naturally at the camera" \
  -F "reference_image=@./ref-1.png;type=image/png" \
  -F "reference_image=@./ref-2.png;type=image/png" \
  -F "reference_type=asset" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "seed=20260403"

JSON / Base64 is also supported:

{
  "model": "veo-3.1-generate-preview",
  "prompt": "Generate an ad shot using the product appearance from the reference images",
  "duration": 8,
  "metadata": {
    "resolution": "720p",
    "aspectRatio": "16:9",
    "referenceImages": [
      {
        "image": {
          "bytesBase64Encoded": "BASE64_IMAGE",
          "mimeType": "image/png"
        },
        "referenceType": "asset"
      }
    ]
  }
}

Check task statusCopy anchor link

First save the id or task_id returned by the create endpoint:

export TASK_ID="task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Then check the status:

curl -X GET "$BASE_URL/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"

While in progress, a typical response:

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1775025000
}

When complete, a typical response:

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "completed",
  "progress": 100,
  "created_at": 1775025000,
  "completed_at": 1775025068
}

Check task status and get the result URLCopy anchor link

To get a downloadable URL directly from the status query, call:

curl -X GET "$BASE_URL/v1/video/generations/$TASK_ID" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"

Typical response:

{
  "code": "success",
  "message": "",
  "data": {
    "error": null,
    "format": "mp4",
    "metadata": null,
    "status": "succeeded",
    "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "url": "https://aicentos.com/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/content"
  }
}

Download the videoCopy anchor link

Once the task completes, download directly:

curl -L "$BASE_URL/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -o veo-result.mp4

Status valuesCopy anchor link

GET /v1/videos/{task_id} mainly returns these statuses:

GET /v1/video/generations/{task_id} mainly returns these statuses:

Integration notesCopy anchor link

• prompt is required.
• For image-to-video, the image field must be named input_reference.
• First/last frame tasks require both frames: first frame via input_reference, last frame via last_frame or lastFrame.
• Reference-image tasks are supported on the Veo 3.1 series only, up to 3 images, and must use 8 seconds.
• Do not pass negativePrompt on reference-image tasks.
• For Gemini image-to-video, remote image URLs are not recommended; send a file or Base64.
• Poll GET /v1/videos/{task_id} and download only after status=completed.
• The Veo 3.1 series accepts 4, 6 or 8 seconds; 1080p and 4k require 8 seconds. Use aspectRatio=16:9 for landscape and aspectRatio=9:16 for portrait; if omitted, 16:9 is assumed.
• Do not pass generateAudio. The Veo 3.1 series generates audio natively, but the current Gemini API does not support toggling audio via generateAudio; passing it may cause the upstream to return INVALID_ARGUMENT.
• To control the audio, describe the dialogue, ambient sound, sound effects or music style in the prompt.
• Official Veo 3.1 supports video extension, but the current aicentos API does not yet expose official video input.