HappyHorse API Documentation

Complete guide to integrating the HappyHorse 1.0 Video Generation API into your applications.

API v1.0 Base URL: https://happyhorse.app

Quick Start

bash

curl -X POST 'https://happyhorse.app/api/generate' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "happyhorse-1.0/video",
    "prompt": "A cinematic shot of mountains at sunrise",
    "mode": "pro",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

Authentication

All API requests require authentication using a Bearer token in the Authorization header.

Get Your API Key: You can get your API key from the API Keys page in your dashboard. → Get Your API Key

http

Authorization: Bearer YOUR_API_KEY

Available Models

HappyHorse 1.0

High-quality AI video generation powered by HappyHorse

Type	Description	Duration	Credits
`pro (text-to-video)`	Pro quality text-to-video generation	3-15s	54/s (no audio) · 80/s (with audio)
`pro (image-to-video)`	Pro quality image-to-video animation	3-15s	54/s (no audio) · 80/s (with audio)
`std (text-to-video)`	Standard quality text-to-video	3-15s	40/s (no audio) · 60/s (with audio)
`std (image-to-video)`	Standard quality image-to-video	3-15s	40/s (no audio) · 60/s (with audio)

API Endpoints

Create a new video generation task. Requires model field set to 'happyhorse-1.0/video'.

Request Body

Body parametersJSON

model:string

Model name, must be 'happyhorse-1.0/video'

prompt:optional string

Text description of the video to generate (max 2500 chars). Required unless multi_shots is true.

mode:optional string

Quality mode: 'pro' or 'std' (default: std) Defaults to std.

duration:optional number

Video duration in seconds (3-15, default: 5) Defaults to 5.

aspect_ratio:optional string

Output aspect ratio (16:9, 9:16, 1:1) Defaults to 16:9.

image_urls:optional string[]

Array of image URLs for image-to-video. Single-shot: up to 2 URLs (first frame + last frame). Multi-shot: 1 URL (first frame only). When provided, aspect_ratio is auto-adapted.

sound:optional boolean

Enable native audio generation (default: true) Defaults to true.

cfg_scale:optional number

Prompt adherence strength (0-1, default: 0.5). Higher values follow the prompt more closely. Defaults to 0.5.

multi_shots:optional boolean

Enable multi-shot mode with multiple prompts Defaults to false.

multi_prompt:optional array

Array of 'prompt, duration' objects for multi-shot mode (max 5 shots, each prompt max 500 chars, each duration 1-12s)

happyhorse_elements:optional array

Array of element objects. In your prompt, reference an element by writing @ immediately followed by that element's name value (e.g. if name is 'element_dog', include @element_dog in the prompt text). Each element: name (string), description (string), element_input_urls (2-4 image URLs). Max 3 elements per task.

Text to Video

json

{
  "model": "happyhorse-1.0/video",
  "prompt": "A majestic eagle soaring through clouds at sunset",
  "mode": "pro",
  "duration": 5,
  "aspect_ratio": "16:9",
  "sound": true
}

Image to Video

json

{
  "model": "happyhorse-1.0/video",
  "prompt": "The character slowly turns and smiles",
  "mode": "pro",
  "image_urls": ["https://example.com/my-image.jpg"],
  "duration": 5
}

Multi-Shot Video

json

{
  "model": "happyhorse-1.0/video",
  "mode": "pro",
  "multi_shots": true,
  "multi_prompt": [
    { "prompt": "A woman walks into a coffee shop", "duration": 3 },
    { "prompt": "She orders a latte and sits by the window", "duration": 4 },
    { "prompt": "She looks outside and smiles", "duration": 3 }
  ],
  "aspect_ratio": "16:9"
}

Responses

Task created successfully

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "n92abc123hh10",
    "status": "IN_PROGRESS"
  }
}

Check the status of a video generation task using the task_id returned from the generate endpoint.

Query Parameters

task_id:string

The unique task ID returned from the generate endpoint (prefixed with n92)

Example Request

bash

curl -X GET 'https://happyhorse.app/api/status?task_id=n92abc123hh10' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Tip: The response field contains a resultUrls array. Access data.response.resultUrls[0] to get the video URL.

javascript

// Extract video URL from response
const videoUrl = data.response.resultUrls[0];

Responses

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "n92abc123hh10",
    "status": "SUCCESS",
    "consumed_credits": 400,
    "created_at": "2026-04-08T10:30:00Z",
    "type": "text-to-video",
    "request": {
      "model": "happyhorse-1.0/video",
      "prompt": "A majestic eagle soaring through clouds at sunset",
      "mode": "pro",
      "duration": 5,
      "aspect_ratio": "16:9"
    },
    "response": {
      "resultUrls": [
        "https://cdn.example.com/videos/abc123.mp4"
      ]
    },
    "error_message": null
  }
}

API Playground

Test the API directly from your browser. Replace YOUR_API_KEY with your actual API key.

API PlaygroundPOST

Base URL

Endpoint

Headers

Request body

Error Codes

HTTP status	Code	Description
400 Bad Request	INVALID_PROMPT	The prompt is invalid or empty
400 Bad Request	INVALID_DURATION	Duration out of supported range (3-15s)
400 Bad Request	INVALID_MODEL	Model must be 'happyhorse-1.0/video'
401 Unauthorized	INVALID_API_KEY	API key is missing or invalid
402 Payment Required	INSUFFICIENT_CREDITS	Not enough credits for this operation
429 Too Many Requests	RATE_LIMITED	Too many requests, please slow down
500 Internal Server Error	INTERNAL_ERROR	Server error, please try again later