HappyHorse Video API Documentation

Overview

Asynchronous video generation powered by HappyHorse models on Alibaba DashScope. Supports HappyHorse 1.0 and 1.1 for text-to-video, image-to-video, and reference-to-video; video-edit remains on HappyHorse 1.0. HappyHorse 1.1 generation supports 480P, 720P, or 1080P; 1.0 and video-edit support 720P or 1080P.

Primary Endpoint

POST/api/v1/userHappyhorseVideo/start

Generate a video using HappyHorse models on Alibaba DashScope. If model_version is omitted, new tasks keep the legacy 1.0 behavior. Supported modes: - t2v: text → video (happyhorse-1.0-t2v / happyhorse-1.1-t2v) - i2v: image first_frame → video (happyhorse-1.0-i2v / happyhorse-1.1-i2v) - r2v: reference images → video (happyhorse-1.0-r2v / happyhorse-1.1-r2v) - video-edit: video + reference images → edited video (happyhorse-1.0-video-edit) ### 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: `mode`. - 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/userHappyhorseVideo/allRecords` — List HappyHorse tasks. - `GET /api/v1/userHappyhorseVideo/{_id}` — Get HappyHorse task details. - `DELETE /api/v1/userHappyhorseVideo/{_id}` — Delete a HappyHorse task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).

Request Parameters

Name	Type	Required	Description
mode	enum: t2v \| i2v \| r2v \| video-edit	Yes	Generation mode
name	string	No	Task name
model_version	enum: 1.0 \| 1.1	No	Model version for t2v / i2v / r2v. video-edit always uses 1.0. HappyHorse 1.1 additionally supports more aspect ratios and 480P/720P/1080P; duration is 3-15s for both versions.; default: "1.0"
prompt	string	No	Required for t2v / r2v / video-edit; optional for i2v
image_url	string	No	First frame image URL (i2v only)
reference_image_urls	array<string>	No	Reference images (r2v requires 1-9; video-edit allows 0-5)
edit_video_url	string	No	Input video URL (video-edit only)
input_video_seconds	number	No	Frontend-detected input video duration in seconds (used to estimate coins for video-edit)
duration	enum: 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| 13 \| 14 \| 15	No	Output duration (seconds). Integer 3-15 for both model versions. Ignored for video-edit (decided by input video).; default: "5"
resolution	enum: 480P \| 720P \| 1080P	No	Output resolution. 480P is only supported by HappyHorse 1.1 t2v / i2v / r2v; 1.0 and video-edit support 720P / 1080P.; default: "720P"
ratio	enum: 16:9 \| 9:16 \| 1:1 \| 4:3 \| 3:4 \| 4:5 \| 5:4 \| 9:21 \| 21:9	No	Aspect ratio (t2v / r2v only). model_version=1.0 supports 16:9, 9:16, 1:1, 4:3, 3:4; model_version=1.1 also supports 4:5, 5:4, 9:21, 21:9.; default: "16:9"
audio_setting	enum: auto \| origin	No	Audio control (video-edit only). auto = model decides; origin = keep input video audio.; default: "auto"
seed	integer	No	Random seed [0, 2147483647]
watermark	boolean	No	DashScope watermark switch; default: true
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": {
        "mode": {
          "type": "string",
          "enum": [
            "t2v",
            "i2v",
            "r2v",
            "video-edit"
          ],
          "description": "Generation mode"
        },
        "name": {
          "type": "string",
          "description": "Task name"
        },
        "model_version": {
          "type": "string",
          "enum": [
            "1.0",
            "1.1"
          ],
          "default": "1.0",
          "description": "Model version for t2v / i2v / r2v. video-edit always uses 1.0. HappyHorse 1.1 additionally supports more aspect ratios and 480P/720P/1080P; duration is 3-15s for both versions."
        },
        "prompt": {
          "type": "string",
          "description": "Required for t2v / r2v / video-edit; optional for i2v"
        },
        "image_url": {
          "type": "string",
          "description": "First frame image URL (i2v only)"
        },
        "reference_image_urls": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Reference images (r2v requires 1-9; video-edit allows 0-5)"
        },
        "edit_video_url": {
          "type": "string",
          "description": "Input video URL (video-edit only)"
        },
        "input_video_seconds": {
          "type": "number",
          "description": "Frontend-detected input video duration in seconds (used to estimate coins for video-edit)"
        },
        "duration": {
          "type": "string",
          "enum": [
            "3",
            "4",
            "5",
            "6",
            "7",
            "8",
            "9",
            "10",
            "11",
            "12",
            "13",
            "14",
            "15"
          ],
          "default": "5",
          "description": "Output duration (seconds). Integer 3-15 for both model versions. Ignored for video-edit (decided by input video)."
        },
        "resolution": {
          "type": "string",
          "enum": [
            "480P",
            "720P",
            "1080P"
          ],
          "default": "720P",
          "description": "Output resolution. 480P is only supported by HappyHorse 1.1 t2v / i2v / r2v; 1.0 and video-edit support 720P / 1080P."
        },
        "ratio": {
          "type": "string",
          "enum": [
            "16:9",
            "9:16",
            "1:1",
            "4:3",
            "3:4",
            "4:5",
            "5:4",
            "9:21",
            "21:9"
          ],
          "default": "16:9",
          "description": "Aspect ratio (t2v / r2v only). model_version=1.0 supports 16:9, 9:16, 1:1, 4:3, 3:4; model_version=1.1 also supports 4:5, 5:4, 9:21, 21:9."
        },
        "audio_setting": {
          "type": "string",
          "enum": [
            "auto",
            "origin"
          ],
          "default": "auto",
          "description": "Audio control (video-edit only). auto = model decides; origin = keep input video audio."
        },
        "seed": {
          "type": "integer",
          "description": "Random seed [0, 2147483647]"
        },
        "watermark": {
          "type": "boolean",
          "default": true,
          "description": "DashScope watermark switch"
        },
        "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": [
        "mode"
      ]
    },
    {
      "$ref": "#/components/schemas/WebhookInput"
    }
  ]
}

Response Fields

code: enum: 0
data: object
data._id: string: Task ID for detail and batch polling.
data.name: string
data.prompt: string
data.is_downloaded: boolean
data.is_previewed: boolean
data.current_status: string: Persisted task state; use the concrete task family schema for its allowed values and terminal states.
data.createdAt: string
data.updatedAt: string
data.expirationDate: string
data.remainingDays: number
data.isExpired: boolean
data.coins: number
data.hasRefundCoin: boolean: Whether charged credits were refunded.
data.failed_code: string
data.failed_message: string
data.failed_reason: string: Public failure category when available.
data.image_url: string
data.image_urls: array<string>
data.result_url: string
data.video_url: string
data.result_video_url: string
data.cover_url: string
data.result_cover: string
data.hd_video_url: string
data.video_time: number
data.duration_seconds: number
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/userHappyhorseVideo/start" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "t2v"
}'

Related Endpoints

GET/api/v1/userHappyhorseVideo/{_id}

Get HappyHorse task details

POST/api/v1/userHappyhorseVideo/start

Start HappyHorse video generation task (T2V / I2V / R2V / Video-Edit)

GET/api/v1/userHappyhorseVideo/allRecords

List HappyHorse tasks

POST/api/v1/userHappyhorseVideo/batchDetail

Batch query task details

DELETE/api/v1/userHappyhorseVideo/{_id}

Delete a HappyHorse task

Responses

200

Task created successfully

401

Unauthorized - Invalid or missing bearer token