Happyhorse HappyHorse 1.0 Reference to Video API | Pricing & Docs

happyhorse/happyhorse-1.0/reference-to-video

HappyHorse 1.0 Reference to Video fuses up to 9 reference images with a text prompt to generate 3–15s 720P/1080P clips on RunComfy — lock characters, outfits, and props with character1/character2 tags.

1. Get started

Use RunComfy's API to run happyhorse/happyhorse-1.0/reference-to-video. For accepted inputs and outputs, see the model's schema.

curl --request POST \
  --url https://model-api.runcomfy.net/v1/models/happyhorse/happyhorse-1.0/reference-to-video \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <token>" \
  --data '{
    "image_url_1": "https://playgrounds-storage-public.runcomfy.net/tools/7347/media-files/ref-promo-1.png",
    "prompt": "Cinematic medium close-up. The young woman (character1) with natural blonde hair, blue eyes, and light freckles sits in a bright European-style café by a window, warm morning light on her face. She glances up from her book, gives a warm candid smile toward camera, then returns her gaze to the page. Slow dolly-in, shallow depth of field, identity-locked face and freckle pattern from the reference, soft background bokeh, 8K film look."
  }'

2. Authentication

Set the YOUR_API_TOKEN environment variable with your API key (manage keys in your Profile) and include it on every request as a Bearer token via the Authorization header: Authorization: Bearer $YOUR_API_TOKEN.

3. API reference

Submit a request

Submit an asynchronous generation job and immediately receive a request_id plus URLs to check status, fetch results, and cancel.

curl --request POST \
  --url https://model-api.runcomfy.net/v1/models/happyhorse/happyhorse-1.0/reference-to-video \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <token>" \
  --data '{
    "image_url_1": "https://playgrounds-storage-public.runcomfy.net/tools/7347/media-files/ref-promo-1.png",
    "prompt": "Cinematic medium close-up. The young woman (character1) with natural blonde hair, blue eyes, and light freckles sits in a bright European-style café by a window, warm morning light on her face. She glances up from her book, gives a warm candid smile toward camera, then returns her gaze to the page. Slow dolly-in, shallow depth of field, identity-locked face and freckle pattern from the reference, soft background bokeh, 8K film look."
  }'

Monitor request status

Fetch the current state for a request_id ("in_queue", "in_progress", "completed", or "cancelled").

curl --request GET \
  --url https://model-api.runcomfy.net/v1/requests/{request_id}/status \
  --header "Authorization: Bearer <token>"

Retrieve request results

Retrieve the final outputs and metadata for the given request_id; if the job is not complete, the response returns the current state so you can continue polling.

curl --request GET \
  --url https://model-api.runcomfy.net/v1/requests/{request_id}/result \
  --header "Authorization: Bearer <token>"

Cancel a request

Cancel a queued job by request_id; in-progress jobs cannot be cancelled.

curl --request POST \
  --url https://model-api.runcomfy.net/v1/requests/{request_id}/cancel \
  --header "Authorization: Bearer <token>"

4. File inputs

Hosted file (URL)

Provide a publicly reachable HTTPS URL. Ensure the host allows server-side fetches (no login/cookies required) and isn't rate-limited or blocking bots. Recommended limits: images ≤ 50 MB (~4K), videos ≤ 100 MB (~2–5 min @ 720p). Prefer stable or pre-signed URLs for private assets.

5. Schema

Input schema

{
  "type": "object",
  "title": "Input schema",
  "required": [
    "image_url_1",
    "prompt"
  ],
  "properties": {
    "image_url_1": {
      "title": "Reference Image 1 (character1)",
      "description": "First reference image. Tag this subject in the prompt as character1. Format: JPEG, JPG, PNG, or WEBP. Short side ≥ 400px, recommended 720P or higher, max 10MB.",
      "type": "string",
      "default": "https://playgrounds-storage-public.runcomfy.net/tools/7347/media-files/ref-promo-1.png"
    },
    "image_url_2": {
      "title": "Reference Image 2 (character2)",
      "description": "Optional second reference image. Tag this subject in the prompt as character2. Format: JPEG, JPG, PNG, or WEBP. Leave blank to skip.",
      "type": "string"
    },
    "image_url_3": {
      "title": "Reference Image 3 (character3)",
      "description": "Optional third reference image. Tag this subject in the prompt as character3. Format: JPEG, JPG, PNG, or WEBP. Leave blank to skip.",
      "type": "string"
    },
    "image_url_4": {
      "title": "Reference Image 4 (character4)",
      "description": "Optional fourth reference image. Tag this subject in the prompt as character4. Leave blank to skip.",
      "type": "string"
    },
    "image_url_5": {
      "title": "Reference Image 5 (character5)",
      "description": "Optional fifth reference image. Tag this subject in the prompt as character5. Leave blank to skip.",
      "type": "string"
    },
    "image_url_6": {
      "title": "Reference Image 6 (character6)",
      "description": "Optional sixth reference image. Tag this subject in the prompt as character6. Leave blank to skip.",
      "type": "string"
    },
    "image_url_7": {
      "title": "Reference Image 7 (character7)",
      "description": "Optional seventh reference image. Tag this subject in the prompt as character7. Leave blank to skip.",
      "type": "string"
    },
    "image_url_8": {
      "title": "Reference Image 8 (character8)",
      "description": "Optional eighth reference image. Tag this subject in the prompt as character8. Leave blank to skip.",
      "type": "string"
    },
    "image_url_9": {
      "title": "Reference Image 9 (character9)",
      "description": "Optional ninth reference image. Tag this subject in the prompt as character9. Leave blank to skip.",
      "type": "string"
    },
    "prompt": {
      "title": "Prompt",
      "description": "Describe the scene, motion, camera, and lighting. Refer to each reference image with character1, character2, character3 … in the order they appear above. Max 2500 Chinese / 5000 non-Chinese characters.",
      "type": "string",
      "default": "Cinematic medium close-up. The young woman (character1) with natural blonde hair, blue eyes, and light freckles sits in a bright European-style café by a window, warm morning light on her face. She glances up from her book, gives a warm candid smile toward camera, then returns her gaze to the page. Slow dolly-in, shallow depth of field, identity-locked face and freckle pattern from the reference, soft background bokeh, 8K film look.",
      "maxLength": 5000
    },
    "aspect_ratio": {
      "title": "Aspect Ratio (W:H)",
      "description": "Output video aspect ratio.",
      "type": "string",
      "enum": [
        "16:9",
        "9:16",
        "1:1",
        "4:3",
        "3:4"
      ],
      "default": "16:9"
    },
    "resolution": {
      "title": "Resolution",
      "description": "Output video resolution. The model supports 720P or 1080P.",
      "type": "string",
      "enum": [
        "720P",
        "1080P"
      ],
      "default": "1080P"
    },
    "duration": {
      "title": "Duration",
      "description": "Output video duration in seconds. Allowed values: 3–15.",
      "type": "integer",
      "enum": [
        3,
        4,
        5,
        6,
        7,
        8,
        9,
        10,
        11,
        12,
        13,
        14,
        15
      ],
      "default": 5
    },
    "seed": {
      "title": "Seed",
      "description": "Optional seed for reproducible generations. Use 0 to let the provider randomize.",
      "type": "integer",
      "minimum": 0,
      "maximum": 2147483647,
      "default": 0
    },
    "watermark": {
      "title": "Watermark",
      "description": "Whether to keep the provider watermark on the generated video.",
      "type": "boolean",
      "default": false
    }
  }
}

Output schema

{
  "output": {
    "type": "object",
    "properties": {
      "image": {
        "type": "string",
        "format": "uri",
        "description": "single image URL"
      },
      "video": {
        "type": "string",
        "format": "uri",
        "description": "single video URL"
      },
      "images": {
        "type": "array",
        "description": "multiple image URLs",
        "items": {
          "type": "string",
          "format": "uri"
        }
      },
      "videos": {
        "type": "array",
        "description": "multiple video URLs",
        "items": {
          "type": "string",
          "format": "uri"
        }
      }
    }
  }
}

RunComfy

RunComfy is the premier ComfyUI platform, offering ComfyUI online environment and services, along with ComfyUI workflows featuring stunning visuals. RunComfy also provides AI Models, enabling artists to harness the latest AI tools to create incredible art.

1. Get started

Use RunComfy's API to run happyhorse/happyhorse-1.0/reference-to-video. For accepted inputs and outputs, see the model's schema.

curl --request POST \
  --url https://model-api.runcomfy.net/v1/models/happyhorse/happyhorse-1.0/reference-to-video \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <token>" \
  --data '{
    "image_url_1": "https://playgrounds-storage-public.runcomfy.net/tools/7347/media-files/ref-promo-1.png",
    "prompt": "Cinematic medium close-up. The young woman (character1) with natural blonde hair, blue eyes, and light freckles sits in a bright European-style café by a window, warm morning light on her face. She glances up from her book, gives a warm candid smile toward camera, then returns her gaze to the page. Slow dolly-in, shallow depth of field, identity-locked face and freckle pattern from the reference, soft background bokeh, 8K film look."
  }'

3. API reference

Submit a request

Submit an asynchronous generation job and immediately receive a request_id plus URLs to check status, fetch results, and cancel.

curl --request POST \
  --url https://model-api.runcomfy.net/v1/models/happyhorse/happyhorse-1.0/reference-to-video \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <token>" \
  --data '{
    "image_url_1": "https://playgrounds-storage-public.runcomfy.net/tools/7347/media-files/ref-promo-1.png",
    "prompt": "Cinematic medium close-up. The young woman (character1) with natural blonde hair, blue eyes, and light freckles sits in a bright European-style café by a window, warm morning light on her face. She glances up from her book, gives a warm candid smile toward camera, then returns her gaze to the page. Slow dolly-in, shallow depth of field, identity-locked face and freckle pattern from the reference, soft background bokeh, 8K film look."
  }'

Monitor request status

Fetch the current state for a request_id ("in_queue", "in_progress", "completed", or "cancelled").

curl --request GET \
  --url https://model-api.runcomfy.net/v1/requests/{request_id}/status \
  --header "Authorization: Bearer <token>"

Retrieve request results

Retrieve the final outputs and metadata for the given request_id; if the job is not complete, the response returns the current state so you can continue polling.

curl --request GET \
  --url https://model-api.runcomfy.net/v1/requests/{request_id}/result \
  --header "Authorization: Bearer <token>"

Cancel a request

Cancel a queued job by request_id; in-progress jobs cannot be cancelled.

curl --request POST \
  --url https://model-api.runcomfy.net/v1/requests/{request_id}/cancel \
  --header "Authorization: Bearer <token>"

4. File inputs

Hosted file (URL)

5. Schema

Input schema

{
  "type": "object",
  "title": "Input schema",
  "required": [
    "image_url_1",
    "prompt"
  ],
  "properties": {
    "image_url_1": {
      "title": "Reference Image 1 (character1)",
      "description": "First reference image. Tag this subject in the prompt as character1. Format: JPEG, JPG, PNG, or WEBP. Short side ≥ 400px, recommended 720P or higher, max 10MB.",
      "type": "string",
      "default": "https://playgrounds-storage-public.runcomfy.net/tools/7347/media-files/ref-promo-1.png"
    },
    "image_url_2": {
      "title": "Reference Image 2 (character2)",
      "description": "Optional second reference image. Tag this subject in the prompt as character2. Format: JPEG, JPG, PNG, or WEBP. Leave blank to skip.",
      "type": "string"
    },
    "image_url_3": {
      "title": "Reference Image 3 (character3)",
      "description": "Optional third reference image. Tag this subject in the prompt as character3. Format: JPEG, JPG, PNG, or WEBP. Leave blank to skip.",
      "type": "string"
    },
    "image_url_4": {
      "title": "Reference Image 4 (character4)",
      "description": "Optional fourth reference image. Tag this subject in the prompt as character4. Leave blank to skip.",
      "type": "string"
    },
    "image_url_5": {
      "title": "Reference Image 5 (character5)",
      "description": "Optional fifth reference image. Tag this subject in the prompt as character5. Leave blank to skip.",
      "type": "string"
    },
    "image_url_6": {
      "title": "Reference Image 6 (character6)",
      "description": "Optional sixth reference image. Tag this subject in the prompt as character6. Leave blank to skip.",
      "type": "string"
    },
    "image_url_7": {
      "title": "Reference Image 7 (character7)",
      "description": "Optional seventh reference image. Tag this subject in the prompt as character7. Leave blank to skip.",
      "type": "string"
    },
    "image_url_8": {
      "title": "Reference Image 8 (character8)",
      "description": "Optional eighth reference image. Tag this subject in the prompt as character8. Leave blank to skip.",
      "type": "string"
    },
    "image_url_9": {
      "title": "Reference Image 9 (character9)",
      "description": "Optional ninth reference image. Tag this subject in the prompt as character9. Leave blank to skip.",
      "type": "string"
    },
    "prompt": {
      "title": "Prompt",
      "description": "Describe the scene, motion, camera, and lighting. Refer to each reference image with character1, character2, character3 … in the order they appear above. Max 2500 Chinese / 5000 non-Chinese characters.",
      "type": "string",
      "default": "Cinematic medium close-up. The young woman (character1) with natural blonde hair, blue eyes, and light freckles sits in a bright European-style café by a window, warm morning light on her face. She glances up from her book, gives a warm candid smile toward camera, then returns her gaze to the page. Slow dolly-in, shallow depth of field, identity-locked face and freckle pattern from the reference, soft background bokeh, 8K film look.",
      "maxLength": 5000
    },
    "aspect_ratio": {
      "title": "Aspect Ratio (W:H)",
      "description": "Output video aspect ratio.",
      "type": "string",
      "enum": [
        "16:9",
        "9:16",
        "1:1",
        "4:3",
        "3:4"
      ],
      "default": "16:9"
    },
    "resolution": {
      "title": "Resolution",
      "description": "Output video resolution. The model supports 720P or 1080P.",
      "type": "string",
      "enum": [
        "720P",
        "1080P"
      ],
      "default": "1080P"
    },
    "duration": {
      "title": "Duration",
      "description": "Output video duration in seconds. Allowed values: 3–15.",
      "type": "integer",
      "enum": [
        3,
        4,
        5,
        6,
        7,
        8,
        9,
        10,
        11,
        12,
        13,
        14,
        15
      ],
      "default": 5
    },
    "seed": {
      "title": "Seed",
      "description": "Optional seed for reproducible generations. Use 0 to let the provider randomize.",
      "type": "integer",
      "minimum": 0,
      "maximum": 2147483647,
      "default": 0
    },
    "watermark": {
      "title": "Watermark",
      "description": "Whether to keep the provider watermark on the generated video.",
      "type": "boolean",
      "default": false
    }
  }
}

Output schema

{
  "output": {
    "type": "object",
    "properties": {
      "image": {
        "type": "string",
        "format": "uri",
        "description": "single image URL"
      },
      "video": {
        "type": "string",
        "format": "uri",
        "description": "single video URL"
      },
      "images": {
        "type": "array",
        "description": "multiple image URLs",
        "items": {
          "type": "string",
          "format": "uri"
        }
      },
      "videos": {
        "type": "array",
        "description": "multiple video URLs",
        "items": {
          "type": "string",
          "format": "uri"
        }
      }
    }
  }
}

HappyHorse 1.0 Reference to Video fuses up to 9 reference images with a text prompt to generate 3–15s 720P/1080P clips on RunComfy — lock characters, outfits, and props with character1/character2 tags.

Table of contents

1. Get started

2. Authentication

3. API reference

Submit a request

Monitor request status

Retrieve request results

Cancel a request

4. File inputs

Hosted file (URL)

5. Schema

Input schema

Output schema

HappyHorse 1.0 Reference to Video fuses up to 9 reference images with a text prompt to generate 3–15s 720P/1080P clips on RunComfy — lock characters, outfits, and props with character1/character2 tags.

Table of contents

1. Get started

2. Authentication

3. API reference

Submit a request

Monitor request status

Retrieve request results

Cancel a request

4. File inputs

Hosted file (URL)

5. Schema

Input schema

Output schema

HappyHorse 1.0 Reference to Video: Multi-Image Subject-to-Video AI Model | RunComfy

HappyHorse 1.0 Reference to Video fuses up to 9 reference images with a text prompt to generate 3–15s 720P/1080P clips on RunComfy — lock characters, outfits, and props with character1/character2 tags.

Table of contents

1. Get started

2. Authentication

3. API reference

Submit a request

Monitor request status

Retrieve request results

Cancel a request

4. File inputs

Hosted file (URL)

5. Schema

Input schema

Output schema

HappyHorse 1.0 Reference to Video: Multi-Image Subject-to-Video AI Model | RunComfy

HappyHorse 1.0 Reference to Video fuses up to 9 reference images with a text prompt to generate 3–15s 720P/1080P clips on RunComfy — lock characters, outfits, and props with character1/character2 tags.

Table of contents

1. Get started

2. Authentication

3. API reference

Submit a request

Monitor request status

Retrieve request results

Cancel a request

4. File inputs

Hosted file (URL)

5. Schema

Input schema

Output schema