HappyHorse 1.0 | BeatAPI API Documentation

curl -X POST https://api.beatapi.io/v1/videos/tasks \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "model": "happyhorse-1.0",
  "prompt": "The woman turns toward the camera and smiles, hair moving in the breeze.",
  "images": [
    "https://media.beatapi.io/samples/neon-singer.png"
  ],
  "duration": 5,
  "aspect_ratio": "9:16",
  "resolution": "720p"
}'

{
  "data": {
    "capability_id": "happyhorse-1.0",
    "capability_version": null,
    "completed_at": null,
    "created_at": 1782210000,
    "error_code": null,
    "error_message": null,
    "id": "task_8K2qA",
    "media_type": "video",
    "model": "happyhorse-1.0",
    "object": "task",
    "output": null,
    "request_id": "req_abc123",
    "stage": "queued",
    "status": "queued",
    "task_kind": "video",
    "updated_at": 1782210000,
    "usage": {
      "billable_duration_seconds": 5,
      "credits_charged": 0.7,
      "credits_refunded": 0,
      "credits_reserved": 0.7,
      "credits_settled": 0
    }
  }
}

Animate a photo into 3–15 seconds of 720p or 1080p video. Image input is required.

Supported modes

Mode	Required input	Rules
Image to video	`model`, `prompt`, `images`	Required. This model publishes no text-to-video mode.
Multiple source images	`model`, `prompt`, `images`	Up to nine angles of the same subject.

Async flow: Create the task, save data.id, then poll the Task with GET /v1/tasks/{task_id}. On succeeded, read data.output.media. On failed, read data.error_code and data.error_message, then follow the error and retry policy.

Using a local file? upload a local input first and pass the returned data.url.

Animate a photo into 3–15 seconds of 720p or 1080p video. Image input is required. ### Supported modes | Mode | Required input | Rules | | --- | --- | --- | | Image to video | `model`, `prompt`, `images` | Required. This model publishes no text-to-video mode. | | Multiple source images | `model`, `prompt`, `images` | Up to nine angles of the same subject. | **Async flow:** Create the task, save `data.id`, then [poll the Task](/quick-guide#get-task-status) with `GET /v1/tasks/{task_id}`. On `succeeded`, read `data.output.media`. On `failed`, read `data.error_code` and `data.error_message`, then follow the [error and retry policy](/quick-guide#errors-and-retry-policy). **Using a local file?** [upload a local input](/quick-guide#upload-an-input-file) first and pass the returned `data.url`.

Authentication

AuthorizationBearer

Send your API key as Authorization: Bearer <BEATAPI_API_KEY>.

Request

This endpoint expects an object.

model"happyhorse-1.0"Required

Must be happyhorse-1.0.

promptstringRequired1-5000 characters

What should happen in the shot — the motion, the expression, the camera.

imageslist of stringsRequired

Source images as public HTTPS URLs. At least one is required.

durationintegerOptional3-15Defaults to 5

Requested output duration in seconds.

aspect_ratioenumOptionalDefaults to 16:9

Output video aspect ratio.

resolutionenumOptionalDefaults to 720p

Output resolution tier. Price scales with it.

Response

Video generation task accepted

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

409

Conflict Error

429

Too Many Requests Error

Supported modes

Authentication

Headers

Request

Response

Errors

Supported modes