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

# HappyHorse Tasks API Integration and Usage

> HappyHorse Video integration guide - Ace Data Cloud

The HappyHorse Tasks API is used to query the video generation or editing tasks created by the HappyHorse Videos API.

## Application Process

To use the HappyHorse Videos API, first obtain your API Token from the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) for future reference.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in, after which you will be automatically returned to the current page.

**One API Token is sufficient to call all services on the platform, and there is no need to apply separately for each service.** The first application will grant a free quota for a trial experience; when the quota is insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin).

> 📘 Complete Documentation: [HappyHorse Videos API →](https://platform.acedata.cloud/documents/happyhorse-videos)

## Request Example

The HappyHorse Tasks API can be used to query the results of the HappyHorse Videos API.

### Setting Request Headers and Request Body

**Request Headers** include:

* `accept`: Specifies that the response result should be in JSON format, set to `application/json`.
* `authorization`: The key to call the API, which can be selected directly after application.

**Request Body** includes:

* `id`: The task ID to query.
* `action`: The operation method for the task, set to `retrieve` for a single query.

### CURL Code Example

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/happyhorse/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
  "action": "retrieve"
}'
```

### Response Example

Upon a successful request, the API will return the details of the task. The `request` field contains the request body when the task was created, and the `response` field contains the response body returned after the task is completed, for example:

```json theme={null}
{
  "id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
  "started_at": 1769262721.823,
  "finished_at": 1769262774.423,
  "elapsed": 52.6,
  "request": {
    "action": "generate",
    "model": "happyhorse-1.1-t2v",
    "prompt": "A cinematic shot of a white horse running across a moonlit beach",
    "resolution": "720P",
    "duration": 5
  },
  "type": "videos",
  "response": {
    "success": true,
    "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
    "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2",
    "data": [
      {
        "id": "1469cfc3-3004-4d9e-ab10-xxxxxx",
        "video_url": "https://cdn.acedata.cloud/happyhorse/c8cbf53aa0.mp4",
        "state": "succeeded",
        "duration": 5,
        "resolution": "720P",
        "ratio": "16:9"
      }
    ]
  }
}
```

Field descriptions are as follows:

* `id`: The ID of the generated task, used to uniquely identify this generation task.
* `request`: The request information when the task was created.
* `response`: The current or final return information of the task.
* `created_at`: The task creation time, Unix timestamp (seconds, float).
* `started_at`: The time when the task started executing, Unix timestamp (seconds, float).
* `finished_at`: The time when the task was completed, Unix timestamp (seconds, float). This field is not returned if the task is not completed.
* `elapsed`: The time taken for task execution, in seconds (float, rounded to 3 decimal places). This field is not returned if the task is not completed.

## Batch Query Operation

When querying task details for multiple task IDs, set the `action` to `retrieve_batch` and pass the task ID array through `ids`:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/happyhorse/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["b8976e18-32dc-4718-9ed8-1ea090fcb6ea"],
  "action": "retrieve_batch"
}'
```

The returned result will include the `items` and `count` fields, where `items` is the array of task details, and `count` is the number of tasks matched in this query.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.