HappyHorse Reference-to-Video

POST /api/v1/services/aigc/video-generation/video-synthesis — blend multiple reference images into one video

The HappyHorse reference-to-video model takes several reference images and a text prompt, and blends the subjects in those images into one coherent video.

Models

Model	Notes
`happyhorse-1.1-r2v`	Generation 1.1
`happyhorse-1.0-r2v`	Generation 1.0
`happyhorse-1.0-r2v-20260618`	Generation 1.0, 20260618 snapshot

Create a job

POST/api/v1/services/aigc/video-generation/video-synthesis

curl https://api.modelsite.ai/api/v1/services/aigc/video-generation/video-synthesis \
  -H "Authorization: Bearer $MODELSITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1-r2v",
    "input": {
      "prompt": "The woman in the red cheongsam from [Image 1] turns around and opens the folding fan from [Image 2]; her earrings sway as she moves",
      "media": [
        { "type": "reference_image", "url": "https://example.com/girl.jpg" },
        { "type": "reference_image", "url": "https://example.com/fan.jpg" }
      ]
    },
    "parameters": { "resolution": "720P", "ratio": "16:9", "duration": 5 }
  }'

Request body

Field	Type	Notes
`model`	string (required)	See the table above
`input.prompt`	string (required)	Scene description. Refer to entries of `media` as `[Image 1]`, `[Image 2]` (1-based, in array order), and name the concrete subject in each image. CJK counts as 2, everything else as 1, budget 5000
`input.media`	array (required)	1–9 `reference_image` entries: `{"type": "reference_image", "url": "..."}`. Array order defines the `[Image N]` numbering
`parameters`	object (optional)	Generation knobs, below

parameters

Parameter	Type	Notes
`resolution`	string	`480P` / `720P` / `1080P` (default). Sellable tiers follow the price configuration
`ratio`	string	`16:9` (default) / `9:16` / `3:4` / `4:3` / `4:5` / `5:4` / `1:1` / `9:21` / `21:9`
`duration`	integer	`[3, 15]`, default 5
`watermark`	boolean	Defaults to `true`; pass `false` explicitly to opt out
`seed`	integer	`[0, 2147483647]`
`negative_prompt`	string	Negative prompt

Reference image requirements: JPEG / JPG / PNG / WEBP, short side ≥400px (crisp 720P+ recommended), ≤20MB. When a reference depicts a person/animal/object, a single subject per image works best.

Polling and result

GET/api/v1/tasks/{task_id}

curl "https://api.modelsite.ai/api/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $MODELSITE_API_KEY"

Response fields

Field	Meaning
`output.task_id`	Job ID (same value returned at creation)
`output.task_status`	`PENDING` queued / `RUNNING` processing / `SUCCEEDED` done / `FAILED` failed
`output.video_url`	The generated video URL — only on `SUCCEEDED`; download promptly
`output.code` / `output.message`	Present only on failure, with the reason
`usage`	Usage stats (duration, resolution tier, …); counted only on success
`request_id`	Unique request ID — include it when reporting issues

Status flow: PENDING → RUNNING → SUCCEEDED / FAILED.

Billing

Billed by actual generated seconds; the resolution tier affects the rate; failed jobs are not billed. Rates on the Models page.

Error handling

Creation-time errors return {"code": "...", "message": "..."}; mid-job failures surface through the poll's output.code / output.message. General error codes: Errors.