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

# Happy Horse

> Alibaba Happy Horse text-to-video, image-to-video, reference-to-video, and video-edit workflows

<Tip>
  1. After submission, a `task_id` is returned immediately. If you provide a `callback_url`, Vidgo sends a POST request to that URL when the task reaches `finished` or `failed`.
  2. You can always fetch the latest task result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
</Tip>

# Happy Horse

`happy-horse` supports text-to-video, image-to-video, reference-to-video, and video-edit through one public model ID.

## Available Model

* **happy-horse** - Alibaba Happy Horse 1.0 video generation and editing

## Workflows

### Text to Video

Send a `prompt` without image or video input fields. Use `aspect_ratio`, `resolution`, and `duration` to control the output.

### Image to Video

Send a single-item `image_urls` array. The image is used as the first frame. `prompt` is optional in this workflow.

### Reference to Video

Send `reference_image_urls` with 1-9 images and a required `prompt`. Reference the images in prompt text as `character1`, `character2`, and so on, matching the order of `reference_image_urls`.

Do not combine `reference_image_urls` with `image_urls`.

### Video Edit

Send `video_url` with a required edit `prompt`. Optional `reference_image_urls` can guide the edit; refer to them as `@Image1`, `@Image2`, and so on. `audio_setting` controls whether Happy Horse decides audio handling automatically or preserves the original audio.

The source video must be 3-60 seconds. Video-edit billing uses the probed source video duration according to the current workflow pricing configuration.

## Pricing

Happy Horse billing depends on the selected workflow, output resolution, and billable video duration. Check the Vidgo pricing page or dashboard for the current rate before submitting production traffic.

Text-to-video, image-to-video, and reference-to-video use the requested `duration`. Video-edit uses the probed source video duration, capped at the maximum billable duration for this workflow.

## Required Parameters

* **model**: `happy-horse`
* **input.prompt**: Required for text-to-video, reference-to-video, and video-edit. Optional for image-to-video.
* **input.video\_url**: Required for video-edit.
* **input.reference\_image\_urls**: Required for reference-to-video.

## Optional Parameters

* **image\_urls**: Single-item first-frame image URL array for image-to-video
* **reference\_image\_urls**: 1-9 images for reference-to-video, or up to 5 optional images for video-edit
* **aspect\_ratio**: Text-to-video and reference-to-video only. `16:9`, `9:16`, `1:1`, `4:3`, or `3:4`. Default is `16:9`
* **resolution**: `720p` or `1080p`. Default is `1080p`
* **duration**: Integer seconds from `3` to `15` for text-to-video, image-to-video, and reference-to-video. Ignored for video-edit
* **audio\_setting**: Video-edit only. `auto` or `origin`. Default is `auto`
* **seed**: Optional integer from `0` to `2147483647`
* **enable\_safety\_checker**: Optional boolean

## Notes

* `image_urls` must resolve to exactly one image and is only for image-to-video.
* `reference_image_urls` selects reference-to-video unless `video_url` is present, in which case it is treated as optional video-edit reference imagery.
* For text-to-video and reference-to-video, omit `video_url` and use `aspect_ratio`.
* For video-edit, omit `duration`; the backend probes the source video duration for validation and duration-based billing.


## OpenAPI

````yaml /api-manual/video-series/happy-horse.json POST /api/generate/submit
openapi: 3.0.0
info:
  title: Vidgo API - Happy Horse API
  description: >-
    Alibaba Happy Horse video generation and editing with text-to-video,
    image-to-video, reference-to-video, and video-edit workflows.
  version: 1.0.0
servers:
  - url: https://api.vidgo.ai
    description: Production server
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - Happy Horse
      summary: Submit Happy Horse Video Task
      description: >-
        Generate or edit videos with Happy Horse through the unified submit
        endpoint. Billing depends on the selected workflow, output resolution,
        and billable video duration; check the Vidgo pricing page or dashboard
        for the current rate.
      operationId: submitHappyHorseTask
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitRequest'
            examples:
              text-to-video:
                summary: Text to Video
                value:
                  model: happy-horse
                  callback_url: https://your-domain.com/callback
                  input:
                    prompt: >-
                      A cinematic tracking shot through a neon city street after
                      rain, reflective pavement, soft ambient audio, realistic
                      motion.
                    resolution: 1080p
                    duration: 5
                    aspect_ratio: '16:9'
                    seed: 42
                    enable_safety_checker: true
              image-to-video:
                summary: Image to Video
                value:
                  model: happy-horse
                  input:
                    image_urls:
                      - https://example.com/first-frame.png
                    prompt: >-
                      Animate the scene with a slow push-in camera move and
                      natural wind motion.
                    resolution: 1080p
                    duration: 5
              reference-to-video:
                summary: Reference to Video
                value:
                  model: happy-horse
                  input:
                    prompt: >-
                      character1 and character2 walk through a bright studio
                      set, keeping identity and outfit details consistent.
                    reference_image_urls:
                      - https://example.com/character1.png
                      - https://example.com/character2.png
                    resolution: 720p
                    duration: 6
                    aspect_ratio: '9:16'
              video-edit:
                summary: Video Edit
                value:
                  model: happy-horse
                  callback_url: https://your-domain.com/callback
                  input:
                    prompt: >-
                      Change the background into a cyberpunk street while
                      preserving the subject movement and camera timing.
                    video_url: https://example.com/source-video.mp4
                    reference_image_urls:
                      - https://example.com/style-reference.png
                    resolution: 1080p
                    audio_setting: auto
      responses:
        '200':
          description: Task submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
components:
  schemas:
    SubmitRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          description: Happy Horse model identifier.
          enum:
            - happy-horse
        callback_url:
          type: string
          format: uri
          description: Optional webhook callback URL for result notifications.
          example: https://your-domain.com/callback
        input:
          type: object
          description: >-
            Input parameters for Happy Horse. Workflow is selected from the
            supplied media fields.
          properties:
            prompt:
              type: string
              description: >-
                Generation or edit prompt. Required for text-to-video,
                reference-to-video, and video-edit; optional for image-to-video.
              example: A cinematic street scene with realistic character motion.
            image_urls:
              type: array
              items:
                type: string
                format: uri
              maxItems: 1
              description: >-
                Single first-frame image URL for image-to-video. Do not combine
                with reference_image_urls or video_url.
            reference_image_urls:
              type: array
              items:
                type: string
                format: uri
              description: >-
                Reference images. Use 1-9 images for reference-to-video, or up
                to 5 optional images for video-edit.
            video_url:
              type: string
              format: uri
              description: >-
                Source video URL for video-edit. Source video must be 3-60
                seconds.
            aspect_ratio:
              type: string
              description: Output aspect ratio for text-to-video and reference-to-video.
              enum:
                - '16:9'
                - '9:16'
                - '1:1'
                - '4:3'
                - '3:4'
              default: '16:9'
              example: '16:9'
            resolution:
              type: string
              description: >-
                Output resolution. Billing may vary by resolution and workflow;
                check the Vidgo pricing page or dashboard for the current rate.
              enum:
                - 720p
                - 1080p
              default: 1080p
              example: 1080p
            duration:
              type: integer
              minimum: 3
              maximum: 15
              description: >-
                Duration in seconds for text-to-video, image-to-video, and
                reference-to-video. Ignored for video-edit, where source video
                duration is probed and capped at the maximum billable duration
                for this workflow.
              default: 5
              example: 5
            audio_setting:
              type: string
              description: Video-edit audio handling mode.
              enum:
                - auto
                - origin
              default: auto
              example: auto
            seed:
              type: integer
              minimum: 0
              maximum: 2147483647
              description: Optional integer seed for repeatable generation.
              example: 42
            enable_safety_checker:
              type: boolean
              description: Optional safety checker toggle.
              example: true
    SubmitResponse:
      type: object
      required:
        - code
        - data
      properties:
        code:
          type: integer
          example: 200
          description: HTTP status code
        data:
          type: object
          required:
            - task_id
            - status
            - created_time
          properties:
            task_id:
              type: string
              example: task-unified-1757165031-uyujaw3d
              description: Unique task identifier for status tracking
            status:
              type: string
              enum:
                - not_started
              example: not_started
              description: Initial task status
            created_time:
              type: string
              format: date-time
              example: '2026-05-11T10:30:00'
              description: ISO 8601 timestamp when the task was created
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        All API endpoints require Bearer Token authentication


        Get your API Key:


        Visit the [API Key Management
        Page](https://vidgo.ai/apis/dashboard/api-key) to get your API Key


        Add it to the request header:


        ```

        Authorization: Bearer YOUR_API_KEY

        ```

````