HappyHorse 1.0

HappyHorse 1.0 is Alibaba's video generation and editing model. It supports text-to-video, first-frame image-to-video, reference-to-video, and video editing.

Models

Pricing

Billed per second × resolution:

Video edit billing: (input video duration + output video duration) × resolution rate.

Create Task

POST https://api.aivideoapi.ai/v1/videos/generations

Request Body

Common Input

Text-to-Video Input

Image-to-Video Input

Image-to-video does not support aspect_ratio; output aspect ratio follows the first-frame image.

First-frame image limits: public HTTP(S) URLs only; Base64 is not supported. Supported formats: JPEG, JPG, PNG, WEBP. Width and height must both be at least 300px. Aspect ratio must be between 1:2.5 and 2.5:1. File size must not exceed 20MB.

Reference-to-Video Input

Use [Image 1], [Image 2], etc. in prompt to refer to images in image_urls by order.

Reference image limits: public HTTP(S) URLs only; Base64 is not supported. Supported formats: JPEG, JPG, PNG, WEBP. The short side must be at least 400px; 720P or clearer images are recommended. File size must not exceed 20MB. Avoid very small, blurry, or heavily compressed images because they can reduce generation quality.

Video Edit Input

Video editing does not accept duration. The input video must be 3-60 seconds; output duration follows the input video and is capped at the first 15 seconds. Billing formula: (input video duration + output video duration) × resolution rate.

Source video limits: public HTTP(S) URLs only. Supported formats: MP4 and MOV; H.264 encoding is recommended. Duration must be 3-60 seconds. The long side must be at most 2160px and the short side must be at least 320px. Aspect ratio must be between 1:2.5 and 2.5:1. File size must not exceed 100MB. Frame rate must be greater than 8fps.

Reference image limits: public HTTP(S) URLs only; Base64 is not supported. Supported formats: JPEG, JPG, PNG, WEBP. Width and height must both be at least 300px. Aspect ratio must be between 1:2.5 and 2.5:1. File size must not exceed 20MB.

Examples

Text-to-Video

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-text-to-video",
    "input": {
      "prompt": "A cinematic tracking shot through a rainy neon street at night",
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "duration": 5
    }
  }'

Image-to-Video

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-image-to-video",
    "input": {
      "prompt": "The girl slowly turns her head and the camera gently pushes in",
      "image_urls": ["https://example.com/portrait.png"],
      "resolution": "1080p",
      "duration": 5
    }
  }'

Reference-to-Video

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-reference-to-video",
    "input": {
      "prompt": "[Image 1] picks up the folding fan from [Image 2], camera slowly pushes in",
      "image_urls": [
        "https://example.com/person.jpg",
        "https://example.com/fan.jpg"
      ],
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "duration": 5
    }
  }'

Video Edit

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-video-edit",
    "input": {
      "prompt": "Make the character in the video wear the striped sweater from the reference image",
      "video_urls": ["https://example.com/input.mp4"],
      "image_urls": ["https://example.com/sweater.png"],
      "resolution": "720p",
      "audio_setting": "auto"
    }
  }'

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "8b6a5162-5c91-4a42-8e80-4c8ef5486f24"
  }
}

Query Task

curl https://api.aivideoapi.ai/v1/tasks/{taskId} \
  -H "Authorization: Bearer sk-your-api-key"

Status transitions: pending -> processing -> completed or failed.

When a task fails, pre-charged credits are automatically refunded.

Error Codes

When a request fails, the API returns a JSON error response:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

Error Reference

Common Scenarios

invalid_request (400)

Returned when required fields are missing or invalid.

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

Your balance is too low. Check your balance with GET /v1/credits and top up in Dashboard > Billing.

invalid_api_key (401)

Possible causes:

• The key does not start with sk-
• The key has been disabled or deleted
• The user account has been banned

upstream_error (503)

The upstream AI provider returned an error. This may happen when:

• The input contains sensitive or prohibited content
• The provider is temporarily unavailable
• The request parameters are not supported by the provider

Credits are automatically refunded when a task fails due to upstream errors.