> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magnific.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Happy Horse 1.1 - Create video from reference images

> Generate a high-quality AI video guided by 1 to 9 reference images that define characters, objects or scenes using Happy Horse 1.1, Alibaba's reference-to-video model.

**How to use references:**
- Provide 1 to 9 reference images via `image_urls`
- Reference each image in the prompt by its 1-based positional index (`character1`, `character2`, ...)
- The order of `image_urls` matches the character index in the prompt

**Key features:**
- 720P and 1080P resolution support
- 9 aspect ratio options
- Duration range: 3-15 seconds
- Optional bottom-right "Happy Horse" watermark
- Prompt up to 5000 characters


<Note>
  `image_urls` is an array of **objects**, each with a `url` field — not an array of plain strings. Passing strings returns `400 Bad Request`.
</Note>

**Example request body**

```json theme={null}
{
  "prompt": "character1 and character2 walk together through a sunlit forest path",
  "image_urls": [
    { "url": "https://example.com/character1.jpg" },
    { "url": "https://example.com/character2.jpg" }
  ],
  "aspect_ratio": "16:9",
  "resolution": "1080P",
  "duration": 5
}
```

The array position sets the character index used in the prompt: the 1st item is `character1`, the 2nd is `character2`, and so on up to `character9`.


## OpenAPI

````yaml post /v1/ai/reference-to-video/happy-horse-1-1
openapi: 3.0.0
info:
  description: >-
    The Magnific API is your gateway to a vast collection of high-quality
    digital resources for your applications and projects. As a leading platform,
    it offers a wide range of graphics, including vectors, photos,
    illustrations, icons, PSD templates, and more, all curated by talented
    designers from around the world.
  title: Magnific API
  version: 1.0.0
servers:
  - description: B2B API Production V1
    url: https://api.magnific.com
security:
  - magnificApiKey: []
paths:
  /v1/ai/reference-to-video/happy-horse-1-1:
    post:
      tags:
        - reference-to-video
      summary: Happy Horse 1.1 - Create video from reference images
      description: >
        Generate a high-quality AI video guided by 1 to 9 reference images that
        define characters, objects or scenes using Happy Horse 1.1, Alibaba's
        reference-to-video model.


        **How to use references:**

        - Provide 1 to 9 reference images via `image_urls`

        - Reference each image in the prompt by its 1-based positional index
        (`character1`, `character2`, ...)

        - The order of `image_urls` matches the character index in the prompt


        **Key features:**

        - 720P and 1080P resolution support

        - 9 aspect ratio options

        - Duration range: 3-15 seconds

        - Optional bottom-right "Happy Horse" watermark

        - Prompt up to 5000 characters
      operationId: create_video_happy_horse_1_1_r2v
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/r2v-request_2'
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                success - created task:
                  $ref: '#/components/examples/200-task-created'
                success - in progress task:
                  $ref: '#/components/examples/200-task-in-progress'
                success - completed task:
                  $ref: '#/components/examples/200-task-completed'
                success - failed task:
                  $ref: '#/components/examples/200-task-failed'
              schema:
                $ref: >-
                  #/components/schemas/_v1_ai_text_to_image_hyperflux_post_200_response
          description: OK - The task exists and the status is returned
        '400':
          content:
            application/json:
              examples:
                invalid_page:
                  summary: Parameter 'page' is not valid
                  value:
                    message: Parameter 'page' must be greater than 0
                invalid_query:
                  summary: Parameter 'query' is not valid
                  value:
                    message: Parameter 'query' must not be empty
                invalid_filter:
                  summary: Parameter 'filter' is not valid
                  value:
                    message: Parameter 'filter' is not valid
                generic_bad_request:
                  summary: Bad Request
                  value:
                    message: Parameter ':attribute' is not valid
              schema:
                $ref: '#/components/schemas/get_all_style_transfer_tasks_400_response'
            application/problem+json:
              examples:
                invalid_page:
                  summary: Parameter 'page' is not valid
                  value:
                    message: Your request parameters didn't validate.
                    invalid_params:
                      - name: page
                        reason: Parameter 'page' must be greater than 0
                      - name: per_page
                        reason: Parameter 'per_page' must be greater than 0
              schema:
                $ref: >-
                  #/components/schemas/get_all_style_transfer_tasks_400_response_1
          description: >-
            Bad Request - The server could not understand the request due to
            invalid syntax.
        '401':
          content:
            application/json:
              examples:
                invalid_api_key:
                  summary: API key is not valid
                  value:
                    message: Invalid API key
                missing_api_key:
                  summary: API key is not provided
                  value:
                    message: Missing API key
              schema:
                $ref: '#/components/schemas/get_all_style_transfer_tasks_400_response'
          description: >-
            Unauthorized - The client must authenticate itself to get the
            requested response.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_all_style_transfer_tasks_500_response'
          description: >-
            Internal Server Error - The server has encountered a situation it
            doesn't know how to handle.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_all_style_transfer_tasks_503_response'
          description: Service Unavailable
components:
  schemas:
    r2v-request_2:
      description: >
        Generate video guided by 1 to 9 reference images that define characters,
        objects or scenes using Happy Horse 1.1. In the prompt, reference each
        image by its 1-based positional index (`character1`, `character2`, ...).
        The order matches the array order.
      properties:
        webhook_url:
          description: >
            Optional callback URL that will receive asynchronous notifications
            whenever the task changes status. The payload sent to this URL is
            the same as the corresponding GET endpoint response, but without the
            data field.
          example: https://www.example.com/webhook
          format: uri
          type: string
        prompt:
          description: >
            Text prompt describing the desired elements and visual style of the
            generated video. Supports any language. Requests with prompts longer
            than 5000 characters are rejected by validation; the upstream
            provider further treats 5000 non-Chinese characters or 2500 Chinese
            characters as the effective ceiling.


            Use `character1`, `character2`, ... in the prompt to reference the
            corresponding image in the `image_urls` array; the order matches the
            array order.


            **Example:** "character1 and character2 walk together through a
            sunlit forest path"
          example: character1 and character2 walk together through a sunlit forest path
          maxLength: 5000
          minLength: 1
          type: string
        image_urls:
          description: >
            Ordered array of reference images. Array position determines the
            character reference number in the prompt (1st item → `character1`,
            2nd → `character2`, etc.).


            **Supported formats:** JPEG, JPG, PNG, WEBP

            **Recommended resolution:** shortest side at least 400 px (720P or
            higher recommended)

            **Maximum file size:** 10 MB per image
          items:
            $ref: '#/components/schemas/reference-image'
          maxItems: 9
          minItems: 1
          type: array
        aspect_ratio:
          $ref: '#/components/schemas/aspect-ratio_1'
        resolution:
          $ref: '#/components/schemas/resolution'
        duration:
          default: 5
          description: Duration of the generated video in seconds.
          example: 5
          maximum: 15
          minimum: 3
          type: integer
        watermark:
          default: false
          description: >-
            Whether to add a watermark to the generated video. The watermark
            appears in the bottom-right corner with the fixed text "Happy
            Horse".
          example: false
          type: boolean
        seed:
          description: >-
            Random seed for reproducibility. Use the same seed with identical
            parameters to improve reproducibility (does not guarantee identical
            results). Leave unset for a random seed.
          example: 12345
          maximum: 2147483647
          minimum: 0
          type: integer
      required:
        - image_urls
        - prompt
      title: Reference to Video - Happy Horse 1.1
      type: object
    _v1_ai_text_to_image_hyperflux_post_200_response:
      example:
        data:
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: CREATED
          generated:
            - https://openapi-generator.tech
            - https://openapi-generator.tech
      properties:
        data:
          $ref: '#/components/schemas/task-detail_1'
      required:
        - data
      type: object
    get_all_style_transfer_tasks_400_response:
      example:
        message: message
      properties:
        message:
          type: string
      type: object
    get_all_style_transfer_tasks_400_response_1:
      properties:
        problem:
          $ref: >-
            #/components/schemas/get_all_style_transfer_tasks_400_response_1_problem
      type: object
    get_all_style_transfer_tasks_500_response:
      example:
        message: Internal Server Error
      properties:
        message:
          example: Internal Server Error
          type: string
      type: object
    get_all_style_transfer_tasks_503_response:
      example:
        message: Service Unavailable. Please try again later.
      properties:
        message:
          example: Service Unavailable. Please try again later.
          type: string
      type: object
    reference-image:
      description: A reference image used to guide reference-to-video generation.
      properties:
        url:
          description: >
            Publicly accessible URL of the reference image.


            **Supported formats:** JPEG, JPG, PNG, WEBP

            **Recommended resolution:** shortest side at least 400 px (720P or
            higher recommended)

            **Maximum file size:** 10 MB
          example: https://example.com/character1.jpg
          format: uri
          type: string
      required:
        - url
      type: object
    aspect-ratio_1:
      default: '16:9'
      description: |
        Output video aspect ratio:
        - `16:9`: Landscape (widescreen)
        - `9:16`: Portrait (vertical, mobile-optimized)
        - `1:1`: Square
        - `4:3`: Standard landscape
        - `3:4`: Standard portrait
        - `21:9`: Ultra-wide cinematic
        - `9:21`: Ultra-tall vertical
        - `5:4`: Classic landscape
        - `4:5`: Classic portrait
      enum:
        - '16:9'
        - '9:16'
        - '1:1'
        - '4:3'
        - '3:4'
        - '21:9'
        - '9:21'
        - '5:4'
        - '4:5'
      type: string
    resolution:
      default: 1080P
      description: |
        Output video resolution:
        - `720P`: 720p HD (1280x720)
        - `1080P`: 1080p Full HD (1920x1080)
      enum:
        - 720P
        - 1080P
      type: string
    task-detail_1:
      allOf:
        - $ref: '#/components/schemas/task'
        - properties:
            generated:
              items:
                description: URL of the generated image
                format: uri
                type: string
              type: array
          required:
            - generated
          type: object
      example:
        task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        status: CREATED
        generated:
          - https://openapi-generator.tech
          - https://openapi-generator.tech
    get_all_style_transfer_tasks_400_response_1_problem:
      properties:
        message:
          example: Your request parameters didn't validate.
          type: string
        invalid_params:
          items:
            $ref: >-
              #/components/schemas/get_all_style_transfer_tasks_400_response_1_problem_invalid_params_inner
          type: array
      required:
        - invalid_params
        - message
      type: object
    task:
      example:
        task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        status: CREATED
      properties:
        task_id:
          description: Task identifier
          format: uuid
          type: string
        status:
          description: Task status
          enum:
            - CREATED
            - IN_PROGRESS
            - COMPLETED
            - FAILED
          type: string
      required:
        - status
        - task_id
      type: object
    get_all_style_transfer_tasks_400_response_1_problem_invalid_params_inner:
      properties:
        name:
          example: page
          type: string
        reason:
          example: Parameter 'page' must be greater than 0
          type: string
      required:
        - name
        - reason
      type: object
  examples:
    200-task-created:
      summary: Success - Task created
      value:
        data:
          generated: []
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: CREATED
    200-task-in-progress:
      summary: Success - Task in progress
      value:
        data:
          generated: []
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: IN_PROGRESS
    200-task-completed:
      summary: Success - Task completed
      value:
        data:
          generated:
            - https://ai-statics.freepik.com/completed_task_image.jpg
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: COMPLETED
    200-task-failed:
      summary: Success - Task failed
      value:
        data:
          generated: []
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: FAILED
  securitySchemes:
    magnificApiKey:
      description: >
        Your Magnific API key. Required for authentication. [Learn how to obtain
        an API key](https://docs.magnific.com/quickstart)
      in: header
      name: x-magnific-api-key
      type: apiKey

````