Veo Video API Documentation

Overview

Text-to-video generation powered by Google DeepMind's Veo model. Produces high-definition, cinematic video clips from a text prompt or a reference image.

Primary Endpoint

POST/api/v1/veoVideo/start

Generate videos using Google DeepMind's Veo 3.1 AI model. Supports text-to-video, image-to-video, and reference-based generation. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `POST /api/v1/veoVideo/batchDetail` — Batch query task details. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).

Request Parameters

Name	Type	Required	Description
name	string	No	Name of the video generation task (optional, auto-generated if not provided)
prompt	string	Yes	Text prompt describing the video content. Can be empty to use default placeholder text.
generationType	enum: TEXT_2_VIDEO \| FIRST_AND_LAST_FRAMES_2_VIDEO \| REFERENCE_2_VIDEO	No	Type of generation (TEXT_2_VIDEO for text-only, FIRST_AND_LAST_FRAMES_2_VIDEO for image frames, REFERENCE_2_VIDEO for reference images); default: "TEXT_2_VIDEO"
imageUrls	array<string>	No	Image URLs for image-to-video generation. For FIRST_AND_LAST_FRAMES_2_VIDEO mode, 1-2 images (start/end frames). For REFERENCE_2_VIDEO mode, 1-3 reference images.
model	enum: veo3 \| veo3_fast	No	Generation model (veo3 for quality, veo3_fast for speed); default: "veo3_fast"
aspectRatio	enum: 16:9 \| 9:16 \| Auto	No	Video aspect ratio (Auto will determine automatically); default: "Auto"
watermark	string	No	Custom watermark text (optional)
seeds	number	No	Random seed for reproducible generation (10000-99999, optional)
minor_suspected_skip	boolean	No	Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block.; default: false
webhook_url	string	No	HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.; maxLength: 2048
webhook_token	string	No	Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.; maxLength: 256

Request schema and conditional rules

{
  "allOf": [
    {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the video generation task (optional, auto-generated if not provided)",
          "example": "My Veo Video"
        },
        "prompt": {
          "type": "string",
          "description": "Text prompt describing the video content. Can be empty to use default placeholder text.",
          "example": "Two person street interview in New York City. Sample Dialogue: Host: \"Did you hear the news?\" Person: \"Yes! Veo 3.1 is now available through this API.\""
        },
        "generationType": {
          "type": "string",
          "enum": [
            "TEXT_2_VIDEO",
            "FIRST_AND_LAST_FRAMES_2_VIDEO",
            "REFERENCE_2_VIDEO"
          ],
          "description": "Type of generation (TEXT_2_VIDEO for text-only, FIRST_AND_LAST_FRAMES_2_VIDEO for image frames, REFERENCE_2_VIDEO for reference images)",
          "default": "TEXT_2_VIDEO",
          "example": "TEXT_2_VIDEO"
        },
        "imageUrls": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Image URLs for image-to-video generation. For FIRST_AND_LAST_FRAMES_2_VIDEO mode, 1-2 images (start/end frames). For REFERENCE_2_VIDEO mode, 1-3 reference images.",
          "example": [
            "https://example.com/start_frame.jpg",
            "https://example.com/end_frame.jpg"
          ]
        },
        "model": {
          "type": "string",
          "enum": [
            "veo3",
            "veo3_fast"
          ],
          "description": "Generation model (veo3 for quality, veo3_fast for speed)",
          "default": "veo3_fast",
          "example": "veo3_fast"
        },
        "aspectRatio": {
          "type": "string",
          "enum": [
            "16:9",
            "9:16",
            "Auto"
          ],
          "description": "Video aspect ratio (Auto will determine automatically)",
          "default": "Auto",
          "example": "16:9"
        },
        "watermark": {
          "type": "string",
          "description": "Custom watermark text (optional)",
          "example": "MyBrand"
        },
        "seeds": {
          "type": "number",
          "description": "Random seed for reproducible generation (10000-99999, optional)",
          "example": 12345
        },
        "minor_suspected_skip": {
          "type": "boolean",
          "default": false,
          "description": "Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."
        }
      },
      "required": [
        "prompt"
      ]
    },
    {
      "$ref": "#/components/schemas/WebhookInput"
    }
  ]
}

Response Fields

code: integer
message: string
data: object
data._id: string: Task ID
data.name: string: Task name
data.prompt: string: Generation prompt
data.generationType: string: Generation type
data.model: string: Model used
data.aspectRatio: string: Aspect ratio
data.current_status: string: Current task status (initialized, submitted, generating, completed, failed)
data.coins: number: Credits consumed
data.createdAt: string: Task creation time
trace_id: string: Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.

Request Example

curl -X POST "https://headswap.app/api/v1/veoVideo/start" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Two person street interview in New York City. Sample Dialogue: Host: \"Did you hear the news?\" Person: \"Yes! Veo 3.1 is now available through this API.\""
}'

Related Endpoints

GET/api/v1/veoVideo/{_id}

Get Veo video detail

GET/api/v1/veoVideo/{_id}/1080p

Get 1080P HD video

POST/api/v1/veoVideo/start

Start Veo 3.1 video generation

GET/api/v1/veoVideo/allRecords

Get all Veo video records

POST/api/v1/veoVideo/batchDetail

Batch query task details

DELETE/api/v1/veoVideo/{_id}

Delete Veo video record

Responses

200

Video generation task started successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.

400

Bad Request - Invalid parameters

401

Unauthorized - Invalid or missing bearer token