DataEyes HappyHorse Video Editing API Reference

Overview

The DataEyes HappyHorse Video Editing API enables programmatic video editing through AI-driven style transfer, local replacement, and other visual transformations. By combining an input video with optional reference images and a text prompt describing the desired edit, the API produces a new video reflecting the specified modifications.

• Model: happyhorse-1.0-video-edit (fixed; no other models are available for this endpoint)
• Workflow: Asynchronous. Submit a task via POST, then poll for results via GET.
• Output: A single edited video, 3--15 seconds in duration.

---

Base URL

https://platform.dataeyes.ai/ali

---

Authentication

All requests require the following headers:

Header	Value	Required
Content-Type	application/json	Yes
Authorization	Bearer <your_api_key>	Yes
X-DashScope-Async	enable	Yes

Test key (for development and integration testing only):

sk-your-api-key

---

Workflow

1. POST /api/v1/services/aigc/video-generation/video-synthesis
      ↓
   Response contains task_id
      ↓
2. GET /api/v1/tasks/{task_id}    (poll every ~15 seconds)
      ↓
   When status == SUCCEEDED → retrieve output video URL

---

Step 1: Create a Video Editing Task

Endpoint

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

Request Body

{
  "model": "happyhorse-1.0-video-edit",
  "input": {
    "prompt": "Convert to watercolor painting style",
    "media": [
      {
        "type": "video",
        "url": "https://example.com/source-video.mp4"
      },
      {
        "type": "reference_image",
        "url": "https://example.com/style-reference.jpg"
      }
    ]
  },
  "parameters": {
    "resolution": "1080P",
    "watermark": true,
    "audio_setting": "auto",
    "seed": 42
  }
}

Request Fields

Top-Level

Field	Type	Required	Description
model	string	Yes	Must be happyhorse-1.0-video-edit.
input	object	Yes	Contains the prompt and media inputs.
parameters	object	No	Optional generation parameters.

input

Field	Type	Required	Description
prompt	string	Yes	Describes the editing intent (e.g., style conversion, local replacement, color grading).
media	array	Yes	Array of media objects. Must contain exactly 1 video entry and optionally 0--5 reference_image entries.

input.media[]

Field	Type	Required	Description
type	string	Yes	"video" or "reference_image".
url	string	Yes	Publicly accessible URL for the media file. For reference_image, Base64-encoded data is also accepted.

parameters

Field	Type	Default	Description
resolution	string	"1080P"	Output resolution. Accepted values: 720P, 1080P.
watermark	boolean	true	Whether to include a watermark on the output video.
audio_setting	string	"auto"	Audio handling. "auto": the model controls audio output. "origin": preserve the original audio track from the input video.
seed	integer	--	Random seed for reproducibility. Range: [0, 2147483647].

Note: The ratio and duration parameters are not supported for video editing tasks.

Video Constraints (type: "video")

Property	Requirement
Formats	MP4, MOV (H.264 codec recommended)
Duration	3--60 seconds
Long edge	<= 4096 px
Short edge	>= 360 px
Aspect ratio	1:2.5 to 2.5:1
File size	<= 100 MB
Frame rate	> 8 fps
URL	Must be a publicly accessible URL (Base64 not supported for video)

Output duration behavior:

• If the input video is <= 15 seconds, the output video matches the input duration.
• If the input video is > 15 seconds, the system automatically truncates to the first 15 seconds for processing.

Reference Image Constraints (type: "reference_image")

Property	Requirement
Formats	JPEG, JPG, PNG, WEBP
Minimum dimensions	Width >= 300 px, Height >= 300 px
Aspect ratio	1:2.5 to 2.5:1
File size	<= 20 MB
URL	Publicly accessible URL or Base64-encoded data
Max count	5 reference images per request

Supported MIME types:

Format	MIME Type
JPEG / JPG	image/jpeg
PNG	image/png
WEBP	image/webp

Response

{
  "request_id": "req-xxxxxxxxxxxx",
  "output": {
    "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "task_status": "PENDING"
  }
}

Field	Type	Description
request_id	string	Unique identifier for the API request.
output.task_id	string	Task identifier used to poll for results. Valid for 24 hours.
output.task_status	string	Initial status (typically PENDING).

---

Step 2: Query Task Status

Endpoint

GET /api/v1/tasks/{task_id}

Replace {task_id} with the value returned from Step 1.

Response (Succeeded)

{
  "request_id": "req-xxxxxxxxxxxx",
  "output": {
    "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "task_status": "SUCCEEDED",
    "video_url": "https://cdn.example.com/output-video.mp4"
  },
  "usage": {
    "duration": 10.5,
    "input_video_duration": 10.5,
    "output_video_duration": 10.5,
    "video_count": 1,
    "SR": 0
  }
}

Response (Failed)

{
  "request_id": "req-xxxxxxxxxxxx",
  "output": {
    "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "task_status": "FAILED",
    "message": "Description of the failure reason"
  }
}

Usage Fields

Field	Type	Description
duration	float	Total billed duration in seconds.
input_video_duration	float	Duration of the input video segment processed, in seconds.
output_video_duration	float	Duration of the generated output video, in seconds.
video_count	integer	Number of output videos (always 1).
SR	integer	Super-resolution flag.

---

Task Status Values

Status	Description
PENDING	Task has been accepted and is queued for processing.
RUNNING	Task is actively being processed.
SUCCEEDED	Task completed successfully. Output video URL is available.
FAILED	Task failed. Check the message field for details.
CANCELED	Task was canceled.
UNKNOWN	Task status could not be determined.

---

Python Example

import requests
import time

BASE_URL = "https://platform.dataeyes.ai/ali"
API_KEY = "sk-your-api-key"

HEADERS = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}",
    "X-DashScope-Async": "enable",
    "User-Agent": "dataeyes-python/1.0",
}

# Step 1: Create video editing task
payload = {
    "model": "happyhorse-1.0-video-edit",
    "input": {
        "prompt": "Convert to anime style with vibrant colors",
        "media": [
            {
                "type": "video",
                "url": "https://example.com/source-video.mp4",
            },
            {
                "type": "reference_image",
                "url": "https://example.com/anime-style-ref.jpg",
            },
        ],
    },
    "parameters": {
        "resolution": "1080P",
        "watermark": False,
        "audio_setting": "origin",
    },
}

response = requests.post(
    f"{BASE_URL}/api/v1/services/aigc/video-generation/video-synthesis",
    headers=HEADERS,
    json=payload,
)
response.raise_for_status()
result = response.json()

task_id = result["output"]["task_id"]
print(f"Task created: {task_id}")

# Step 2: Poll for results
while True:
    time.sleep(15)

    poll_response = requests.get(
        f"{BASE_URL}/api/v1/tasks/{task_id}",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "User-Agent": "dataeyes-python/1.0",
        },
    )
    poll_response.raise_for_status()
    status_result = poll_response.json()

    task_status = status_result["output"]["task_status"]
    print(f"Status: {task_status}")

    if task_status == "SUCCEEDED":
        video_url = status_result["output"]["video_url"]
        print(f"Output video: {video_url}")
        break
    elif task_status in ("FAILED", "CANCELED", "UNKNOWN"):
        message = status_result["output"].get("message", "No details provided")
        print(f"Task ended with status {task_status}: {message}")
        break

---

Notes

1. Audio handling: Use audio_setting: "origin" to preserve the original audio track from the input video. The default value "auto" allows the model to decide how to handle audio, which may result in modified or removed audio.

2. Duration truncation: Input videos longer than 15 seconds are automatically truncated to the first 15 seconds. The output video duration will be at most 15 seconds. Plan your input accordingly if precise segment selection is required.

3. Polling cadence: Poll the task status endpoint approximately every 15 seconds. The query endpoint has a rate limit of 20 requests per second. Excessive polling may result in throttling.

4. Asset expiration: Both task_id and the output video_url are valid for 24 hours after task creation. Download or persist the output video within this window.

5. URL accessibility: Video URLs must be publicly accessible. The API does not support authenticated or signed URLs. For reference images, both public URLs and Base64-encoded data are accepted.

6. No ratio or duration parameters: Unlike video generation endpoints, the video editing endpoint does not accept ratio or duration parameters. The output dimensions and duration are derived from the input video.

---

Error Codes

Error Code	HTTP Status	Description	Resolution
InvalidApiKey	401	The API key is missing, malformed, or revoked.	Verify the API key in the Authorization header.
InvalidParameter	400	One or more request parameters are invalid (e.g., unsupported format, missing required field, constraint violation).	Review the request body against the field and constraint specifications above.
Throttling	429	Request rate limit exceeded.	Reduce request frequency and implement exponential backoff.

---

DataEyes HappyHorse Video Editing API -- Reference Documentation