# Happy Horse API

> Provider: **Alibaba**
> Source: https://www.pixazo.ai/models/happy-horse

HappyHorse text-to-video generates physically realistic, motion-smooth video from text prompts.

## Happy Horse 1.0

### Text to Video

## Base URL

```
https://gateway.pixazo.ai/happy-horse-1-0/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Text to Video - Happy Horse API

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/happy-horse-1-0/v1/generateHappyhorseT2VRequest
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "A small cardboard train running through a tiny city at night"
}
```

```
import requests

url = "https://gateway.pixazo.ai/happy-horse-1-0/v1/generateHappyhorseT2VRequest"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "prompt": "A small cardboard train running through a tiny city at night"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = 'https://gateway.pixazo.ai/happy-horse-1-0/v1/generateHappyhorseT2VRequest';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};
const data = {
  prompt: 'A small cardboard train running through a tiny city at night'
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```
curl -v -X POST "https://gateway.pixazo.ai/happy-horse-1-0/v1/generateHappyhorseT2VRequest" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "A small cardboard train running through a tiny city at night"
  }'
```

## Output

```
{
  "request_id": "happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=happy-horse-1-0&operation=text-to-video)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Text to Video

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

non-empty; ≤ 5000 latin chars / 2500 Chinese chars (truncated past)

Text description of the desired video

resolution

No

string

"1080P"

"720P", "1080P"

Output video resolution

ratio

No

string

"16:9"

"16:9", "9:16", "1:1", "4:3", "3:4"

Output aspect ratio

duration

No

integer

5

3–15 (seconds)

Length of generated video in seconds

watermark

No

boolean

true

true, false

Add a "HappyHorse" watermark in the lower-right corner of the output

seed

No

integer

random

0–2147483647

Random seed for reproducibility. Note: same seed does not guarantee identical output (generation is probabilistic)

## Example Request

```
{
  "prompt": "A small cardboard train running through a tiny city at night",
  "resolution": "1080P",
  "ratio": "16:9",
  "duration": 15,
  "watermark": false,
  "seed": 42
}
```

## Response

```
{
  "request_id": "happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_SUBSCRIPTION\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'happy-horse-1-0' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "happy-horse-1-0",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "happy-horse-1-0",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/happy-horse-1-0_019dxxxx-xxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-04-07T10:00:00.000Z",
  "updated_at": "2026-04-07T10:02:30.000Z",
  "completed_at": "2026-04-07T10:02:30.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

### Image to Video

## Base URL

```
https://gateway.pixazo.ai/happy-horse-1-0/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Image to Video - Happy Horse API

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/happy-horse-1-0/v1/generateHappyhorseI2VRequest
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "input": {
    "media": [
      { "type": "first_frame", "url": "https://cdn.translate.alibaba.com/r/wanx-demo-1.png" }
    ]
  }
}
```

```
import requests

url = "https://gateway.pixazo.ai/happy-horse-1-0/v1/generateHappyhorseI2VRequest"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "input": {
        "media": [
            {"type": "first_frame", "url": "https://cdn.translate.alibaba.com/r/wanx-demo-1.png"}
        ]
    }
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = 'https://gateway.pixazo.ai/happy-horse-1-0/v1/generateHappyhorseI2VRequest';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};
const data = {
  input: {
    media: [
      { type: 'first_frame', url: 'https://cdn.translate.alibaba.com/r/wanx-demo-1.png' }
    ]
  }
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```
curl -v -X POST "https://gateway.pixazo.ai/happy-horse-1-0/v1/generateHappyhorseI2VRequest" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "input": {
      "media": [
        { "type": "first_frame", "url": "https://cdn.translate.alibaba.com/r/wanx-demo-1.png" }
      ]
    }
  }'
```

## Output

```
{
  "request_id": "happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=happy-horse-1-0&operation=image-to-video)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Image to Video

Parameter

Required

Type

Default

Allowed values / range

Description

`input`

Yes

object

—

—

Container for prompt + media

`input.prompt`

No

string

—

any language; ≤ 5000 latin chars / 2500 Chinese chars (truncated past)

Describe motion, not the subject — the image already provides the subject

`input.media`

Yes

array

—

exactly 1 element

First-frame entry — see sub-fields below

`input.media[].type`

Yes

string

—

"first\_frame"

Only valid value for I2V

`input.media[].url`

Yes

string

—

publicly reachable HTTP(S) URL of JPEG/JPG/PNG/WEBP. Min 300×300 px. Aspect 1:2.5 to 2.5:1. Max 10 MB

First frame image URL

`parameters`

No

object

{}

—

Container for tuning options

`parameters.resolution`

No

string

"1080P"

"720P", "1080P"

Output video resolution

`parameters.duration`

No

integer

5

3–15 (seconds)

Length of generated video in seconds

`parameters.watermark`

No

boolean

true

true, false

Add a "HappyHorse" watermark in the lower-right corner of the output

`parameters.seed`

No

integer

random

0–2147483647

Random seed for reproducibility. Note: same seed does not guarantee identical output (generation is probabilistic)

**Note:** No `ratio` field for I2V — the output video's aspect ratio is auto-derived from the `input.media[].url` image's dimensions.

## Example Request

```
{
  "input": {
    "prompt": "A cat running on the grass",
    "media": [
      { "type": "first_frame", "url": "https://cdn.translate.alibaba.com/r/wanx-demo-1.png" }
    ]
  },
  "parameters": {
    "resolution": "1080P",
    "duration": 15,
    "watermark": false,
    "seed": 42
  }
}
```

## Response

```
{
  "request_id": "happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_SUBSCRIPTION\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'happy-horse-1-0' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "happy-horse-1-0",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "happy-horse-1-0",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/happy-horse-1-0_019dxxxx-xxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-04-07T10:00:00.000Z",
  "updated_at": "2026-04-07T10:02:30.000Z",
  "completed_at": "2026-04-07T10:02:30.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

### Reference to Video (Ref Image to Video)

## Base URL

```
https://gateway.pixazo.ai/happy-horse-1-0/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Reference to Video - Happy Horse 1.0 API

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/happy-horse-1-0/v1/generateHappyhorseR2VRequest
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "input": {
    "prompt": "A woman in a red qipao character1",
    "media": [
      { "type": "reference_image", "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/mvzfud/hh-v2v-girl.jpg" }
    ]
  }
}
```

```
import requests

url = "https://gateway.pixazo.ai/happy-horse-1-0/v1/generateHappyhorseR2VRequest"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "input": {
        "prompt": "A woman in a red qipao character1",
        "media": [
            {"type": "reference_image", "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/mvzfud/hh-v2v-girl.jpg"}
        ]
    }
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = 'https://gateway.pixazo.ai/happy-horse-1-0/v1/generateHappyhorseR2VRequest';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};
const data = {
  input: {
    prompt: 'A woman in a red qipao character1',
    media: [
      { type: 'reference_image', url: 'https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/mvzfud/hh-v2v-girl.jpg' }
    ]
  }
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```
curl -v -X POST "https://gateway.pixazo.ai/happy-horse-1-0/v1/generateHappyhorseR2VRequest" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "input": {
      "prompt": "A woman in a red qipao character1",
      "media": [
        { "type": "reference_image", "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/mvzfud/hh-v2v-girl.jpg" }
      ]
    }
  }'
```

## Output

```
{
  "request_id": "happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=happy-horse-1-0&operation=reference-to-video)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Reference to Video

Parameter

Required

Type

Default

Allowed

Description

`input`

Yes

object

—

—

Container for prompt + media.

`input.prompt`

Yes

string

—

any language

Describe the desired video. Use `character1`, `character2`, … tokens to reference images by their order in `media`. Max 5000 non-Chinese / 2500 Chinese characters (truncated past).

`input.media`

Yes

array

—

1–9 elements

Reference images. Array order maps to `characterN` tokens in the prompt.

`input.media[].type`

Yes

string

—

`"reference_image"`

Only valid value for R2V.

`input.media[].url`

Yes

string

—

HTTP(S) JPEG/JPG/PNG/WEBP

Publicly reachable image URL. Shortest side ≥ 400 px (720P+ recommended). Max 10 MB.

`parameters`

No

object

`{}`

—

Container for tuning options.

`parameters.resolution`

No

string

`"1080P"`

`"720P"`, `"1080P"`

Output video resolution.

`parameters.ratio`

No

string

`"16:9"`

`"16:9"`, `"9:16"`, `"3:4"`, `"4:3"`, `"1:1"`

Output aspect ratio.

`parameters.duration`

No

integer

5

3–15 (seconds)

Length of generated video.

`parameters.watermark`

No

boolean

`true`

`true`, `false`

Add “Happy Horse” watermark in the lower-right corner.

`parameters.seed`

No

integer

random

0–2147483647

Reproducibility hint (probabilistic — same seed does not guarantee identical output).

### `characterN` mapping

The order of items in `input.media` defines which `characterN` token in the prompt they map to. The first `reference_image` is `character1`, the second is `character2`, and so on up to `character9`. If your prompt mentions `character3`, you must have at least 3 entries in `media`.

## Example Request

```
{
  "input": {
    "prompt": "A woman in a red qipao character1. Side medium view outlining the silhouette, then a low-angle shot capturing her gracefully unfolding a folding fan character2, with tassel earrings character3 swaying lightly as she turns her head.",
    "media": [
      { "type": "reference_image", "url": "https://.../hh-v2v-girl.jpg" },
      { "type": "reference_image", "url": "https://.../hh-v2v2-folding-fan.jpg" },
      { "type": "reference_image", "url": "https://.../hh-v2v-earrings.jpg" }
    ]
  },
  "parameters": {
    "resolution": "1080P",
    "ratio": "16:9",
    "duration": 15,
    "watermark": false,
    "seed": 42
  }
}
```

## Response

```
{
  "request_id": "happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_SUBSCRIPTION\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'happy-horse-1-0' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "happy-horse-1-0",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "happy-horse-1-0",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/happy-horse-1-0_019dxxxx-xxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-04-07T10:00:00.000Z",
  "updated_at": "2026-04-07T10:02:30.000Z",
  "completed_at": "2026-04-07T10:02:30.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

### Video to Video (Video Editing)

## Base URL

```
https://gateway.pixazo.ai/happy-horse-1-0/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Video to Video - Happy Horse 1.0 API

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/happy-horse-1-0/v1/generateHappyhorseVideoEditRequest
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "input": {
    "prompt": "Make the video look like a Studio Ghibli scene",
    "media": [
      { "type": "video", "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260409/dozxak/Wan_Video_Edit_33_1.mp4" }
    ]
  }
}
```

```
import requests

url = "https://gateway.pixazo.ai/happy-horse-1-0/v1/generateHappyhorseVideoEditRequest"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "input": {
        "prompt": "Make the video look like a Studio Ghibli scene",
        "media": [
            {"type": "video", "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260409/dozxak/Wan_Video_Edit_33_1.mp4"}
        ]
    }
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = 'https://gateway.pixazo.ai/happy-horse-1-0/v1/generateHappyhorseVideoEditRequest';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};
const data = {
  input: {
    prompt: 'Make the video look like a Studio Ghibli scene',
    media: [
      { type: 'video', url: 'https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260409/dozxak/Wan_Video_Edit_33_1.mp4' }
    ]
  }
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```
curl -v -X POST "https://gateway.pixazo.ai/happy-horse-1-0/v1/generateHappyhorseVideoEditRequest" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "input": {
      "prompt": "Make the video look like a Studio Ghibli scene",
      "media": [
        { "type": "video", "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260409/dozxak/Wan_Video_Edit_33_1.mp4" }
      ]
    }
  }'
```

## Output

```
{
  "request_id": "happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=happy-horse-1-0&operation=video-to-video)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Video to Video

Parameter

Required

Type

Default

Allowed

Description

`input`

Yes

object

—

—

Container for prompt + media.

`input.prompt`

Yes

string

—

any language

Describe the intended edit (style transfer, object/clothing replacement, etc.). Max 5000 non-Chinese / 2500 Chinese characters (truncated past).

`input.media`

Yes

array

—

1 video + 0–5 reference\_image (1–6 total)

Source video plus optional reference images.

`input.media[].type`

Yes

string

—

`"video"` (exactly 1) or `"reference_image"` (0–5)

Element kind.

`input.media[].url` (video)

Yes

string

—

HTTP(S) MP4/MOV (H.264). Duration 3–60 s. Long side ≤ 2160 px, short side ≥ 320 px. Aspect 1:2.5–2.5:1. ≤ 100 MB. Frame rate > 8 fps.

Source video.

`input.media[].url` (reference\_image)

Conditional

string

—

HTTP(S) JPEG/JPG/PNG/WEBP. ≥ 300×300 px. Aspect 1:2.5–2.5:1. ≤ 10 MB.

Reference image.

`parameters`

No

object

`{}`

—

Container for tuning options.

`parameters.resolution`

No

string

`"1080P"`

`"720P"`, `"1080P"`

Output video resolution.

`parameters.watermark`

No

boolean

`true`

`true`, `false`

Add “Happy Horse” watermark in the lower-right corner.

`parameters.audio_setting`

No

string

`"auto"`

`"auto"`, `"origin"`

`auto` lets the model decide; `origin` keeps the input video's audio track verbatim.

`parameters.seed`

No

integer

random

0–2147483647

Reproducibility hint (probabilistic — same seed does not guarantee identical output).

### Notes specific to video edit

-   No `ratio` or `duration` — both are derived from the input video. If the input is ≤ 15 s, output matches; if > 15 s, only the first 15 s are processed, so output is at most 15 s.
-   The input video must be publicly reachable (HTTP/HTTPS). DashScope downloads it directly — R2 / S3 / CDN URLs work; `localhost` / private URLs do not.
-   For reference-image-based replacements, describe in the prompt what to put where (e.g. _“wear the sweater from image 1”_). Array order maps to the order images appear in `media`.
-   The `SUCCEEDED` response populates `usage.input_video_duration` (source length actually processed) and `usage.output_video_duration` separately — unlike T2V/I2V/R2V, where `input_video_duration` is always 0.

## Example Request

```
{
  "input": {
    "prompt": "Make the horse-headed humanoid character in the video wear the striped sweater from image 1, place the prop from image 2 on the table behind, change the wall art to image 3, swap the floor texture to match image 4, and recolor the curtains to match image 5",
    "media": [
      { "type": "video",           "url": "https://.../source.mp4" },
      { "type": "reference_image", "url": "https://.../sweater.webp" },
      { "type": "reference_image", "url": "https://.../prop.jpg" },
      { "type": "reference_image", "url": "https://.../wall-art.png" },
      { "type": "reference_image", "url": "https://.../floor.jpg" },
      { "type": "reference_image", "url": "https://.../curtains.webp" }
    ]
  },
  "parameters": {
    "resolution": "1080P",
    "watermark": false,
    "audio_setting": "origin",
    "seed": 42
  }
}
```

## Response

```
{
  "request_id": "happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_SUBSCRIPTION\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'happy-horse-1-0' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "happy-horse-1-0",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "happy-horse-1-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "happy-horse-1-0",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/happy-horse-1-0_019dxxxx-xxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-04-07T10:00:00.000Z",
  "updated_at": "2026-04-07T10:02:30.000Z",
  "completed_at": "2026-04-07T10:02:30.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.