Name: Happy Horse 1.1 Text-to-Video API | api.market
Brand: magicapi
SKU: api-magicapi-text-to-video-generator-api-alibaba-happyhorse-1-1
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎥 High-Resolution Text-to-Video API (Happy Horse 1.1)

## Overview
Happy Horse 1.1 is a video generation model from Alibaba. The mode depends on how many images you send in `images`:

- **No images**: text-to-video from your `prompt`.
- **One image**: image-to-video. The image is animated as the first frame, and the `prompt` is optional.
- **Two to nine images**: reference-to-video. Refer to the images in your prompt as [Image 1], [Image 2] and so on.

You choose a `resolution` of 720p or 1080p (default 1080p), a `duration` from 3 to 15 seconds (default 5) and one of five aspect ratios. Each request returns the URL of one video.

## Features
- **Three modes in one endpoint**: text-to-video, image-to-video and reference-to-video, selected by the number of images in `images`.
- **Resolution**: `720p` or `1080p` (default).
- **Duration**: any whole number of seconds from 3 to 15 (default 5).
- **Aspect ratios**: `16:9` (default), `9:16`, `1:1`, `4:3`, `3:4`. For image-to-video the input image's aspect ratio is used instead.
- **Input images**: jpg, png, bmp or webp, up to 10MB each, aspect ratio between 1:2.5 and 2.5:1, each side at least 300px.
- **Seed**: set a seed (0 to 2147483647) to reproduce a result.

## Use Cases
1. **Short clips from a description**: turn a written scene into a video for social posts or ads.
2. **Animating a still image**: bring a product photo, illustration or photo to life as the first frame of a clip.
3. **Videos built from references**: combine several reference images (a character, a place, an object) into one scene.
4. **Vertical and square formats**: generate `9:16` or `1:1` clips for mobile placements.

## Visual Examples
### Example Input
Prompt: "A golden retriever runs through shallow waves on a beach at sunset, slow motion"

Settings: `resolution` `720p`, `duration` `5`. No input images (text-to-video); `aspect_ratio` was left at its default `16:9`.

### Example Output
[Watch the example video](https://blog.api.market/wp-content/uploads/2026/10/happyhorse-1.1-output-api-market.mp4)

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | No | `""` |  | Text prompt for video generation. Optional when a single image is provided (image-to-video). Required for text-to-video and reference-to-video. When providing multiple reference images, refer to them in the prompt as [Image 1], [Image 2], etc. |
| `images` | array of URLs | No | `[]` |  | Input images. Provide no images for text-to-video, one image to animate it as the first frame (image-to-video), or multiple images (up to 9) for reference-to-video. Accepts jpg/png/bmp/webp, <=10MB each, aspect ratio between 1:2.5 and 2.5:1, each side >=300px. |
| `resolution` | string | No | `1080p` | `720p`, `1080p` | Output video resolution |
| `aspect_ratio` | string | No | `16:9` | `16:9`, `9:16`, `1:1`, `4:3`, `3:4` | Aspect ratio of the generated video. Only applies to text-to-video and reference-to-video. When a single image is provided (image-to-video), the image's aspect ratio is used. |
| `duration` | integer | No | `5` | `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15` | Duration of the generated video in seconds |
| `seed` | integer | No | none |  | Random seed for reproducible generation. Range: 0-2147483647 |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.175 per API unit.
- **1 API unit = 1 second of 720p output video.** The number of seconds is the `duration` you request (default 5).
- **720p**: 1 unit per second, so a request costs `duration` times $0.175.
- **1080p** (the default when you do not set `resolution`): `duration` times 1.286 units, rounded up to a whole unit per request.
- **Worked example**: a 5 second 1080p video is 5 x 1.286 = 6.43 units, rounded up to 7 units = $1.225. The same video at 720p is 5 units = $0.875.

Every duration and resolution:

| `duration` | 720p units | 720p price | 1080p units | 1080p price |
| --- | --- | --- | --- | --- |
| 3 | 3 | $0.525 | 4 | $0.70 |
| 4 | 4 | $0.70 | 6 | $1.05 |
| 5 | 5 | $0.875 | 7 | $1.225 |
| 6 | 6 | $1.05 | 8 | $1.40 |
| 7 | 7 | $1.225 | 10 | $1.75 |
| 8 | 8 | $1.40 | 11 | $1.925 |
| 9 | 9 | $1.575 | 12 | $2.10 |
| 10 | 10 | $1.75 | 13 | $2.275 |
| 11 | 11 | $1.925 | 15 | $2.625 |
| 12 | 12 | $2.10 | 16 | $2.80 |
| 13 | 13 | $2.275 | 17 | $2.975 |
| 14 | 14 | $2.45 | 19 | $3.325 |
| 15 | 15 | $2.625 | 20 | $3.50 |

- Aspect ratio, prompt, images and seed do not change the price.
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/text-to-video-generator-api-alibaba-happyhorse-1-1`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/text-to-video-generator-api-alibaba-happyhorse-1-1/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "57e8eee02a055de60a4dee9ba0d36ac7c8ea4a5714575e8d58dcfae3c150f7b3",
    "input": {
      "prompt": "A golden retriever runs through shallow waves on a beach at sunset, slow motion",
      "resolution": "720p",
      "duration": 5
    }
  }'
```

Response (201 Created):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "57e8eee02a055de60a4dee9ba0d36ac7c8ea4a5714575e8d58dcfae3c150f7b3",
  "status": "starting",
  "created_at": "2026-10-13T10:43:25.053Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/text-to-video-generator-api-alibaba-happyhorse-1-1/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/10/happyhorse-1.1-output-api-market.mp4",
  "error": null,
  "created_at": "2026-10-13T10:43:25.053Z",
  "started_at": "2026-10-13T10:43:26.053Z",
  "completed_at": "2026-10-13T10:44:55.053Z"
}
```

`output` is a single URL string pointing to the generated video.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a `duration` outside 3 to 15, a `resolution` other than `720p` or `1080p`, or a missing `prompt` for text-to-video.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits

All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/text-to-video-generator-api-alibaba-happyhorse-1-1";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "57e8eee02a055de60a4dee9ba0d36ac7c8ea4a5714575e8d58dcfae3c150f7b3", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 1000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

createAndWaitForPrediction({
      "prompt": "A golden retriever runs through shallow waves on a beach at sunset, slow motion",
      "resolution": "720p",
      "duration": 5
  }).then((output) => console.log(output));
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/text-to-video-generator-api-alibaba-happyhorse-1-1"

def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "57e8eee02a055de60a4dee9ba0d36ac7c8ea4a5714575e8d58dcfae3c150f7b3", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])

def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 10 minutes")

print(create_and_wait_for_prediction({
    "prompt": "A golden retriever runs through shallow waves on a beach at sunset, slow motion",
    "resolution": "720p",
    "duration": 5
}))
```

## FAQ
- **How do I switch between text-to-video and image-to-video?**
  - Send no images for text-to-video, one image in `images` for image-to-video, or two to nine images for reference-to-video.
- **Is the prompt required?**
  - It is required for text-to-video and reference-to-video. It is optional when you send a single image.
- **Does `aspect_ratio` apply when I send one image?**
  - No. For image-to-video the input image's aspect ratio is used.
- **What image formats are accepted?**
  - jpg, png, bmp and webp, up to 10MB each, with each side at least 300px.
- **How much does a 10 second 1080p video cost?**
  - 10 x 1.286 = 12.86, rounded up to 13 units = $2.275.
- **Is the 201 response from POST an error?**
  - No. 201 Created means the prediction was accepted. Use the returned `id` to poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, adjust the input and try again.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Text-to-video with Alibaba Happy Horse 1.1 from text, one image or up to 9 reference images. 720p or 1080p, 3 to 15 seconds, five aspect ratios, pay per second.