Developer view
Async task workflow
Text-to-video
Image-to-video
Status polling
API Overview
The HappyHorse API is best understood as a task-based video generation interface. Instead of returning a finished clip immediately, the API accepts a generation request, returns a task identifier, and expects the client to check a status endpoint until the output is ready.
That workflow fits developer integrations where video generation happens behind a product UI, inside an automation pipeline, or as part of a prompt-driven creative tool. The primary request patterns center on text-to-video generation, image-to-video extensions, and predictable status tracking for downstream delivery.
HappyHorse API
A developer-facing overview page for authentication, endpoints, payload design, and polling flow.
Text-to-video
Prompt-based clip creation for apps that need short-form video generation from structured text input.
Image-to-video
An extension path where an existing image reference can be used as the visual starting point for motion.
Base URL & Authentication
Base URL
https://api.happyhorse.ai
This hostname is shown in documentation format as a stable integration placeholder. Production hostnames and version paths can vary by release channel or account provisioning path.
Authentication
Authorization: Bearer YOUR_API_KEY
Send your API key in the request headers as a bearer token. This page demonstrates the header format without claiming a self-serve credential issuance flow on this site.
Header example
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Available Model / API Capability
| Capability |
Typical API Value |
Integration Note |
| Model |
happyhorse-1.0/video |
Use a model identifier explicitly in the request body so client behavior stays predictable across releases. |
| Generation mode |
text-to-video or image-to-video |
Start with text prompts for direct generation, or attach an image reference when the workflow calls for motion from an existing visual. |
| Aspect ratio |
16:9, 9:16, 1:1 |
Aspect ratio should be set intentionally because it affects framing, motion composition, and product UI layout. |
| Duration |
5 or 10 seconds |
Shorter durations are easier to validate in early integrations and are common in task-based generation APIs. |
| Quality mode |
std or pro |
Expose quality as an explicit setting so users can trade off speed, credits, and output polish. |
| Prompt-based generation |
Natural-language prompt plus optional sound flag |
Prompt structure usually performs better when scene, camera motion, subject action, and mood are described directly. |
API Endpoints
POST
/api/generate
Create a video generation task. This is the main write endpoint for prompt-driven video requests and can be extended to image-to-video when an image input field is supported in the request payload.
- Use for text generation requests and task creation.
- Common fields include model, prompt, mode, duration, aspect_ratio, and sound.
- Successful acceptance returns a task_id and an initial processing state.
GET
/api/status
Query the state of a previously created task. The client sends a task identifier and receives processing updates plus result URL information when the clip is ready.
- Use task_id to fetch queued, processing, completed, or failed states.
- Completed responses typically expose resultUrls or a direct video_url field.
- Polling should be rate-aware to avoid unnecessary 429 responses.
Request Example
The examples below show a straightforward text-to-video request. For an image-to-video flow, keep the same async pattern and extend the payload with the image input field used by your integration channel.
cURL
curl -X POST "https://api.happyhorse.ai/api/generate" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "happyhorse-1.0/video",
"prompt": "A silver horse runs through a rain-soaked neon alley, cinematic camera move, detailed reflections, high motion clarity.",
"mode": "text-to-video",
"duration": 5,
"aspect_ratio": "16:9",
"quality": "pro",
"sound": true
}'
JavaScript fetch
const response = await fetch("https://api.happyhorse.ai/api/generate", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
model: "happyhorse-1.0/video",
prompt: "A silver horse runs through a rain-soaked neon alley, cinematic camera move, detailed reflections, high motion clarity.",
mode: "text-to-video",
duration: 5,
aspect_ratio: "16:9",
quality: "pro",
sound: true
})
});
const payload = await response.json();
Response Example
A status response usually contains the task identifier, current state, a readable message, and the result location once processing is complete.
{
"task_id": "hh_task_93d2a7c4f81d",
"status": "completed",
"message": "Video generation completed.",
"data": {
"model": "happyhorse-1.0/video",
"mode": "text-to-video",
"duration": 5,
"aspect_ratio": "16:9",
"resultUrls": [
"https://cdn.example.com/happyhorse/hh_task_93d2a7c4f81d.mp4"
],
"video_url": "https://cdn.example.com/happyhorse/hh_task_93d2a7c4f81d.mp4"
}
}
Error Codes
| Status |
Name |
Meaning |
| 400 |
Invalid request |
The payload is missing required fields or contains invalid values such as an unsupported mode, duration, or aspect ratio. |
| 401 |
Invalid API key |
The bearer token is missing, malformed, expired, or not recognized for the current request. |
| 402 |
Insufficient credits |
The request was understood but cannot be processed because the account or integration channel lacks available credits. |
| 429 |
Rate limited |
The client is sending too many requests in a short window and should back off before retrying. |
| 500 |
Internal error |
The server could not finish the request because of an internal processing issue. Retry only after a short delay. |
API Workflow
1
Authenticate
Attach a bearer token in the Authorization header for every request.
2
Send generation request
POST the model, prompt, mode, duration, aspect ratio, and optional generation flags to /api/generate.
3
Receive task ID
Store the returned task identifier so the client can track the job asynchronously.
4
Poll status endpoint
Call /api/status with the task ID until the request is completed or fails.
5
Fetch result
Read the completed response payload and use the returned result URL to deliver or store the video output.
HappyHorse API FAQ
What is the HappyHorse API used for?
The HappyHorse API is used for async video generation workflows, including prompt submission, task tracking, and result retrieval in a developer integration.
Does the API support text to video?
Yes. The main request pattern shown here is a text-to-video generation task built from model, prompt, duration, aspect ratio, and quality settings.
Can I use images as input?
Image-to-video is treated as an extension path for integrations that accept an image reference alongside the usual generation parameters.
How do I check generation status?
Store the returned task ID from the create request, then call the status endpoint until the job reports a completed or failed state.
What authentication method is used?
This page uses a bearer-token pattern in the request header. It is documentation-style guidance, not a claim that this site issues production credentials.
Does the API return a task ID?
Yes. A task ID is central to the async workflow because it lets the client poll status and fetch result URLs after processing.
What should I do if a request fails?
Check the status code first, validate request fields and token formatting, then retry only when the error is transient such as rate limiting or a temporary server issue.
Related HappyHorse Pages
