# HappyHorse-1.0 API

> HappyHorse-1.0 — high-quality AI video generation.

- **Provider**: Alibaba
- **Model id**: `happyhorse-reference-to-video`
- **Modality**: video
- **Price**: 14–24 credits /sec

## Overview

HappyHorse-1.0 is called in two steps: create a generation task, then poll the task until the result is ready.

## Authentication

All requests require a Bearer Token in the request header:

```
Authorization: Bearer YOUR_API_KEY
```

## Create Task

`POST https://you.bot/api/v1/generate`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| modelId | string | Yes | Model id: `happyhorse-reference-to-video` |
| input | object | Yes | Input parameters object (see below) |
| callbackUrl | string | No | https URL we POST the finished task to. Signed with `X-Webhook-Signature` once you create a webhook signing key in Dashboard → Settings |

### input object parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| prompt | string | Yes | Required text prompt describing the desired video. Use “character1”, “character2”, ... in the prompt to refer to the corresponding images in the media array (order matches the array). Max 5,000 non‑Chinese characters or 2,500 Chinese characters; extra content is truncated. Max 5000 characters. (example: Animate the reference still: a slow push-in as warm chocolate oozes from the split lava cake, steam curling upward and a fine dusting of cocoa settling, gentle… — full value in the request example) |
| reference_image | string[] | Yes | Reference image URL list. Provide 1–9 images. The order defines which image is character1, character2, etc. Minimum resolution: short side ≥ 400px; 720p+ clear images are recommended. Avoid small, blurry, or heavily compressed images, as they may degrade results. (image URL) |
| resolution | string | No | Output video resolution. Valid values: 720P, 1080P (default). (options: 720p \| 1080p) (default: 1080p) |
| aspect_ratio | string | No | Output aspect ratio. Valid values: 16:9 (default), 9:16, 1:1, 4:3, 3:4. (options: 16:9 \| 9:16 \| 1:1 \| 4:3 \| 3:4) (default: 16:9) |
| duration | number | No | Output duration in seconds (integer). Must be between 3 and 15. Defaults to 5. (range 3-15) (default: 5) |
| seed | number | No | Random seed. Range: [0, 2147483647]. If not specified, the system generates a seed automatically. Fixing the seed can improve reproducibility, but results may still vary due to the model’s stochasticity. |

### Request example

```json
{
  "modelId": "happyhorse-reference-to-video",
  "input": {
    "prompt": "Animate the reference still: a slow push-in as warm chocolate oozes from the split lava cake, steam curling upward and a fine dusting of cocoa settling, gentle candlelight flicker across the plate.",
    "reference_image": [
      "https://you.bot/examples/grok-imagine-text-to-image.jpg"
    ],
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": 5,
    "seed": 1
  }
}
```

### Response example

```json
{
  "taskId": "281e5b0…f39b9",
  "creditsCharged": 70
}
```

## Query Task

`GET https://you.bot/api/v1/task/{taskId}?model=happyhorse-reference-to-video`

When `state` is `success`, the output is in `resultUrls`: `{ "state": "success", "resultUrls": [ ... ] }`. (Text models return inline in the create response.)

## Error Codes

| Code | Description |
|------|-------------|
| 200 | Request successful |
| 400 | Invalid request parameters |
| 401 | Authentication failed — check API Key |
| 402 | Insufficient account balance |
| 403 | IP not allowed for this key, or the key is restricted to other models |
| 404 | Task not found, or it has expired |
| 409 | Duplicate request — an identical submit arrived moments ago. Nothing was charged; retry is safe |
| 413 | Payload too large — see the character and file-size limits for this model |
| 429 | Rate limit exceeded — retry after the Retry-After header |
| 500 | Internal server error |
| 504 | Upstream timed out — nothing was delivered; retry is safe |