Hailuo Video API Documentation

Overview

Generate videos with Hailuo from text prompts or image references with configurable duration and output settings.

Primary Endpoint

POST/api/v1/hailuoVideo/start

Generate videos using Hailuo. Only supports image-to-video mode. **Required:** `prompt` and at least one non-blank `image_url` or `image_urls` entry. A non-empty `image_url` takes precedence over `image_urls`; otherwise the first non-empty `image_urls` entry is used and must not be whitespace-only, and later entries are ignored. **Duration:** `6` or `10` seconds. **Resolution:** `768P` (default) or `1080P` (not available for 10s). This is an asynchronous API. After calling this endpoint, poll `/api/v1/hailuoVideo/{_id}` to check task status. Model tiers: standard/pro. Valid duration/resolution pairs: 6s+768P, 6s+1080P, 10s+768P; 10s+1080P is rejected. At least one non-blank image_url or image_urls entry is required. ### 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 - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/hailuoVideo/allRecords` — Get Hailuo Video task list. - `GET /api/v1/hailuoVideo/{_id}` — Get Hailuo Video task detail. - `DELETE /api/v1/hailuoVideo/{_id}` — Delete Hailuo Video task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).

Request Parameters

Name	Type	Required	Description
name	string	No	Task name (optional)
prompt	string	Yes	Text prompt describing the video content. Required.
image_urls	array<string>	No	Array of reference image URLs. At least one is required.
image_url	string	No	Single reference image URL (alternative to image_urls).
resolution	enum: 768P \| 1080P	No	Output video resolution. 1080P is not supported for 10s duration.; default: "768P"
duration	enum: 6 \| 10	No	Video duration in seconds.; default: "6"
model	enum: standard \| pro	No	Pricing/model tier; independent from resolution.; default: "standard"
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": "Task name (optional)",
          "example": "My Hailuo Video"
        },
        "prompt": {
          "type": "string",
          "description": "Text prompt describing the video content. Required.",
          "example": "A cat playing with a ball of yarn"
        },
        "image_urls": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Array of reference image URLs. At least one is required.",
          "example": [
            "https://example.com/image.jpg"
          ]
        },
        "image_url": {
          "type": "string",
          "description": "Single reference image URL (alternative to image_urls)."
        },
        "resolution": {
          "type": "string",
          "enum": [
            "768P",
            "1080P"
          ],
          "description": "Output video resolution. 1080P is not supported for 10s duration.",
          "default": "768P"
        },
        "duration": {
          "type": "string",
          "enum": [
            "6",
            "10"
          ],
          "description": "Video duration in seconds.",
          "default": "6"
        },
        "model": {
          "type": "string",
          "enum": [
            "standard",
            "pro"
          ],
          "default": "standard",
          "description": "Pricing/model tier; independent from resolution."
        },
        "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"
      ],
      "description": "prompt is required, plus at least one non-blank image_url OR image_urls entry. 10s+1080P is not supported.",
      "anyOf": [
        {
          "required": [
            "image_url"
          ],
          "properties": {
            "image_url": {
              "type": "string",
              "pattern": "\\S"
            }
          }
        },
        {
          "required": [
            "image_urls"
          ],
          "properties": {
            "image_url": {
              "type": "string",
              "enum": [
                ""
              ]
            },
            "image_urls": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "string"
              },
              "not": {
                "items": {
                  "pattern": "^\\s*$"
                }
              }
            }
          }
        }
      ],
      "not": {
        "required": [
          "duration",
          "resolution"
        ],
        "properties": {
          "duration": {
            "enum": [
              "10",
              10
            ]
          },
          "resolution": {
            "enum": [
              "1080P"
            ]
          }
        }
      }
    },
    {
      "$ref": "#/components/schemas/WebhookInput"
    }
  ]
}

Response Fields

code: integer
data: object
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://www.a2e.com.cn/api/v1/hailuoVideo/start" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "A cat playing with a ball of yarn",
  "image_url": "https://example.com/image.jpg"
}'

Related Endpoints

GET/api/v1/hailuoVideo/{_id}

Get Hailuo Video task detail

POST/api/v1/hailuoVideo/start

Start Hailuo video generation

GET/api/v1/hailuoVideo/allRecords

Get Hailuo Video task list

POST/api/v1/hailuoVideo/batchDetail

Batch query Hailuo Video task details

DELETE/api/v1/hailuoVideo/{_id}

Delete Hailuo Video task

Responses

200

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.

401

Unauthorized - Invalid or missing bearer token