Happy Horse API Examples for PoYo

Focused server-side examples for building with happy-horse on PoYo.

Model Page | Docs | Get API Key | Pricing | Main Examples

Happy Horse is useful for fast video generation and editing workflows: product motion tests, stylized social clips, reference-driven videos, and short creative drafts.

Sample output: PoYo model page sample.

This is an official PoYo model page sample, not a file generated by this repo.

What This Repo Covers

• Text-to-video with happy-horse
• Image-to-video, reference-to-video, and video-edit request patterns
• cURL and Node.js backend examples
• Async task flow: submit, store data.task_id, poll status, retrieve files
• Webhook receiver notes for production callbacks
• Prompt examples and production integration notes

Quick Start

cp .env.example .env
# Edit .env and set POYO_API_KEY

Run the Node.js example:

cd node
npm start

Keep POYO_API_KEY on the server. Do not expose it in browser code, mobile apps, screenshots, or public logs.

API Flow

Submit a video task:

POST https://api.poyo.ai/api/generate/submit
Authorization: Bearer <POYO_API_KEY>
Content-Type: application/json

Store the returned data.task_id, then poll:

GET https://api.poyo.ai/api/generate/status/{task_id}
Authorization: Bearer <POYO_API_KEY>

For production queues, pass callback_url during submit and use a webhook receiver for terminal task updates.

Generate

{
  "model": "happy-horse",
  "input": {
    "prompt": "A flower blooming and wilting over two weeks, one photo per day. Same vase, same window, same angle. Light changes with weather. Quiet domestic ambience",
    "resolution": "720p",
    "duration": 10,
    "aspect_ratio": "16:9"
  }
}

Image-to-Video Request

Use image_urls when you want Happy Horse to animate a specific product image, character frame, or visual concept.

{
  "model": "happy-horse",
  "callback_url": "https://example.com/api/poyo/webhook",
  "input": {
    "prompt": "Animate the source product image into a short studio clip. Add a slow camera push-in, soft reflections, and subtle natural movement while preserving the product shape",
    "image_urls": [
      "https://example.com/source-frame.png"
    ],
    "resolution": "720p",
    "duration": 10,
    "aspect_ratio": "16:9"
  }
}

Examples

Path	What it covers
curl/generate.md	Copy-paste submit and status requests.
node/	Native Node.js submit and poll flow.
webhooks/express-webhook/	Minimal Express receiver for PoYo callbacks.
docs/prompt-examples.md	Practical prompts for product workflows and creative tests.
docs/production-notes.md	Security and reliability notes before launch.

Expected Submit Response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-example",
    "status": "not_started",
    "created_time": "2026-05-23T08:00:00"
  }
}

Expected Status Response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-example",
    "status": "finished",
    "progress": 100,
    "files": [
      {
        "file_url": "https://storage.poyo.ai/generated/video.mp4",
        "file_type": "video"
      }
    ],
    "error_message": null
  }
}

Production Checklist

• Keep POYO_API_KEY server-side only.
• Validate prompts and source media URLs before submit.
• Store data.task_id before polling or waiting for webhooks.
• Treat finished and failed as terminal states.
• Log task IDs and status transitions, not API keys or private prompts.
• Make webhook handlers idempotent.
• Download returned files before they expire.
• Check current model availability and cost on the PoYo model page.

Run Checks

make check

On Windows:

./scripts/check.ps1

License

MIT