Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runflow.io/llms.txt

Use this file to discover all available pages before exploring further.

Pricing: $0.14/second. Endpoint: POST /v1/models/alibaba/happy-horse/reference-to-video/runs.
Generate 1080p video with synchronized native audio from a text prompt and references. Aspect ratios: 16:9, 9:16, 1:1, 4:3, 3:4. Duration: 3–15s.

​
Overview

​
Pricing

  • Base price: $0.14/second
  • Note: Per second of generated video (720p baseline)

​
Happy Horse Reference-to-Video API

Endpoint: POST /v1/models/alibaba/happy-horse/reference-to-video/runs

​
Run the model

​
Python

import requests

response = requests.post(
    "https://api.runflow.io/v1/models/alibaba/happy-horse/reference-to-video/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "character1 walks confidently down a neon-lit Tokyo street at night, cinematic lighting, smooth tracking shot",
            "duration": 5,
            "image_urls": [
                "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=1024&q=80"
            ],
            "resolution": "720p",
            "aspect_ratio": "16:9"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)

​
Node.js

const response = await fetch(
  "https://api.runflow.io/v1/models/alibaba/happy-horse/reference-to-video/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "character1 walks confidently down a neon-lit Tokyo street at night, cinematic lighting, smooth tracking shot",
            "duration": 5,
            "image_urls": [
                "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=1024&q=80"
            ],
            "resolution": "720p",
            "aspect_ratio": "16:9"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);

​
cURL

curl -X POST https://api.runflow.io/v1/models/alibaba/happy-horse/reference-to-video/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "character1 walks confidently down a neon-lit Tokyo street at night, cinematic lighting, smooth tracking shot",
        "duration": 5,
        "image_urls": [
            "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=1024&q=80"
        ],
        "resolution": "720p",
        "aspect_ratio": "16:9"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON

​
Request parameters

ParameterTypeRequiredDescription
inputobjectrequiredModel input parameters. See “Input schema” below.
callback_urlstring | nulloptionalWebhook URL - POSTed when the run reaches a terminal state.
metadataobject | nulloptionalArbitrary key-value pairs attached to the run.

​
Input schema

FieldTypeRequiredAllowed valuesDescription
promptstringrequiredAnyText prompt describing the desired video. Reference subjects from your images using character1, character2, … up to character9 (the order matches the order of image_urls). Max 2500 characters.
image_urlsimage_listrequiredAnyReference images for subject consistency (1-9 images). Formats: JPEG, JPG, PNG, WEBP. Shortest side must be at least 400 px (720P or higher recommended). Max 10 MB each.
aspect_ratiostringoptional16:9, 9:16, 1:1, 4:3, 3:4Aspect ratio of the generated video.
durationintegeroptionalAnyOutput video duration in seconds (3-15).
enable_safety_checkerbooleanoptionalAnyEnable content moderation for input and output.
resolutionstringoptional720p, 1080pOutput video resolution tier.
seedintegeroptionalAnyRandom seed for reproducibility (0-2147483647).

​
Output schema

FieldTypeDescription
outputsjsonUnified output array - one entry per generated artifact with url/type/width/height/duration/etc.
seedjsonDeterministic seed used for generation, or null if the provider doesn’t return one.
timingjsonProvider timing info (inference_ms etc.), or null.
nsfw_detectedjsontrue if the provider flagged output as NSFW, false if cleared, null if not checked.

​
Callback payload

When you provide a callback_url, Runflow POSTs to it once the run reaches a terminal state.
FieldTypeDescription
eventstringEvent type: “run.completed”, “run.failed”, or “run.cancelled”.
run_idstringThe unique identifier of the run.
statusstringTerminal status: “succeeded”, “failed”, or “cancelled”.
outputobject | nullThe run output. Null if the run failed or was cancelled.
duration_msnumber | nullTotal run duration in milliseconds.
created_atstring | nullISO 8601 timestamp when the run was created.
completed_atstring | nullISO 8601 timestamp when the run reached terminal state.
metadataobject | nullThe metadata object passed at run creation, if any.
  • Retries: 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
  • Headers: Runflow-Request-Id is always sent. Runflow-Signature is sent if a signing secret is configured.

​
Additional Resources

Browse all models

Browse the catalog.

Run lifecycle

Callbacks, polling, statuses.

Callbacks

Handle async results.

Pricing

How requests bill out.