Introduction
HappyHorse 1.1 Reference to video builds one shot from one to nine reference images, sent in reference_image_urls in the order the prompt refers to them. It returns 3 to 15 whole seconds at 720p or 1080p in any of nine aspect ratios, with a generated soundtrack. References are images only; no video or audio reference is accepted.
Choose a HappyHorse 1.1 mode by starting material
| What you have at the start | Mode |
|---|---|
| a written scene or script | HappyHorse 1.1 Text to video |
| an approved opening image | HappyHorse 1.1 Image to video |
| one to nine reference images | HappyHorse 1.1 Reference to video |
Key features & highlights
Nine ordered slots
With up to nine images, one request can pin a character, costume pieces, a vehicle, a location and props. The rider-jacket-bike-station example uses three stills to keep the rider, the open jacket, the motorcycle and the filling station the same from take to take, in 3:4 at 720p, so the prompt only has to name the action and the light.
Face, prop and location in one take
The three-plate-corridor example gives each image a different job: the woman, the cherry-red guitar she carries and the neon motel corridor. The prompt says which image is which, then asks for one backward-tracking take in which face, prop and location all have to survive together.
Nine frame shapes on this endpoint
aspect_ratio offers nine values with 16:9 as the default, including 1:1, 4:5 and 5:4. The product-in-place example is square at 1080p: a candle jar from one image placed on a marble shelf from another, lit to match the shelf's window light.
Request parameters
| Parameter | Required | Description |
|---|---|---|
prompt | Yes | Name each reference as [Image 1], [Image 2] and so on, in upload order and with the square brackets, say what it contributes, then describe the shot they should produce. at least 1 characters · at most 2500 characters |
reference_image_urls | Yes | Required, one to nine images in the order the prompt names them. One job per image. at least 1 items · at most 9 items |
aspect_ratio | No | Nine values, default 16:9. Available here but not on image-to-video. |
resolution | No | 720p or 1080p. |
duration_seconds | No | Whole seconds, 3 to 15. |
seed | No | Integer from 0 to 2147483647 for the random start; leave it out and every run draws its own. |
Pricing
| Specification | Price |
|---|---|
| $0.14 / second |
| $0.18 / second |
Use cases
A product in its setting
Send the product and the location as separate images and describe how they interact. In product-in-place the camera pushes in slowly as the wick lights and a thread of smoke rises, and the flame's glow adds a second, warm light onto the marble and the linen.
A consistent cast and wardrobe across a series
Reuse the same reference set for every shot so the performer, the costume and the vehicle stay the same from take to take, and change only the action line of the prompt. Keep the images in the same order each time so the positional references still point at the right picture.
Uncensored or styled character work
Like image-to-video, this path follows the images it is given, so uncensored character work that text-to-video would reject can start from a reference set, with the cast, wardrobe and location each pinned by its own image.
Prompt guide & pro tips
Refer to images by position
Say what each image contributes before describing the shot. The published examples use two positional styles: "Use the woman from the first image exactly as she appears" and "Place the candle jar from [Image 1] into the empty centre of the marble shelf in [Image 2]". Upload the files in the same order the prompt names them.
One job per image
Nine slots is a ceiling, not a target. Several views of the same subject get averaged rather than reconciled, so give each image a distinct job such as identity, garment, prop or location. Each image needs a shortest side of at least 400 px and a file size of up to 20 MB.
Spend the prompt on action and light
Once identity is settled by the references, the prompt says what the subject does, not what they look like: "he swings a leg over the tank and settles, the overhead light pressing down from directly above, moths in the beam". Keep lighting instructions consistent with the location image, as product-in-place does by matching the shelf's light direction and colour temperature.
API quick start
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "alibaba/happyhorse-1.1/reference-to-video",
"input": {
"aspect_ratio": "16:9",
"duration_seconds": 5,
"prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
"reference_image_urls": [
"https://example.com/reference.png"
],
"resolution": "720p"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
See the API reference for authentication, the complete schema, polling, and error handling.
