> ## 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.

# Development Dreamina Tasks

> Dreamina API guide - Ace Data Cloud

## Integracja i użycie API Dreamina Tasks

API Dreamina Tasks służy do zapytania o wyniki wykonania zadań wideo stworzonych przez [Dreamina Video Generation API](https://platform.acedata.cloud/documents/dreamina-videos-integration). Gdy w interfejsie generowania przekażesz `callback_url` lub `async: true`, interfejs natychmiast zwróci `task_id`, który możesz wykorzystać do sprawdzania statusu zadania oraz ostatecznego adresu wideo za pomocą tego interfejsu, używając `task_id` lub `trace_id`. **Ten interfejs jest darmowy.**

## Proces aplikacji

Aby korzystać z serii API Dreamina, najpierw przejdź do [konsoli Ace Data Cloud](https://platform.acedata.cloud/console/applications), aby uzyskać swój token API, który należy zachować na przyszłość.

Jeśli nie jesteś zalogowany lub zarejestrowany, automatycznie zostaniesz przekierowany na stronę logowania, aby zarejestrować się i zalogować, a po zakończeniu zostaniesz automatycznie przekierowany z powrotem na bieżącą stronę.

**Jeden token API wystarczy do korzystania ze wszystkich usług platformy, nie ma potrzeby składania osobnych wniosków dla każdej usługi.** Przy pierwszym wniosku otrzymasz darmowy limit, aby móc skorzystać z doświadczenia; gdy limit się wyczerpie, możesz doładować saldo ogólne w [konsoli](https://platform.acedata.cloud/console/coin).

## Parametry żądania

**Nagłówki żądania**

* `accept`: określa, że oczekujesz odpowiedzi w formacie JSON, wpisz `application/json`.
* `authorization`: klucz do wywołania API, w formacie `Bearer {token}`.
* `content-type`: wpisz `application/json`.

**Treść żądania**

| Parametr | Typ | Wymagane | Opis |
| - | - | - | - |
| `action` | string | Nie | Typ operacji, `retrieve` (domyślnie, zapytanie pojedyncze) lub `retrieve_batch` (zapytanie zbiorcze) |
| `id` | string | Nie | ID zadania do zapytania (zwrotny `task_id` przy tworzeniu wideo) |
| `trace_id` | string | Nie | ID śledzenia zadania do zapytania, może zastąpić `id` |
| `ids` | string\[] | Nie | Lista ID zadań do zapytania zbiorczego, używana z `retrieve_batch` |

> Przy zapytaniu o pojedyncze zadanie, przynajmniej jedno z `id` lub `trace_id` musi być podane.

## Zapytanie o pojedyncze zadanie

### CURL

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/dreamina/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve",
  "id": "362b4fed-67bd-11f1-ad11-00163e57d510"
}'
```

### Python

```python theme={null}
import requests

url = "https://api.acedata.cloud/dreamina/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "retrieve",
    "id": "362b4fed-67bd-11f1-ad11-00163e57d510"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

### Przykład odpowiedzi

Po pomyślnym żądaniu, API zwraca szczegóły tego zadania. `request` to treść żądania przy tworzeniu zadania, `response` to treść odpowiedzi po zakończeniu zadania, w której `data.video_url` to adres wygenerowanego wideo:

```json theme={null}
{
  "id": "362b4fed-67bd-11f1-ad11-00163e57d510",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "request": {
    "model": "omnihuman-1.5",
    "image_url": "https://cdn.acedata.cloud/4hfydw.jpg",
    "audio_url": "https://cdn.acedata.cloud/6f7d62b18b.wav"
  },
  "response": {
    "success": true,
    "data": {
      "task_id": "362b4fed67bd11f1ad1100163e57d510",
      "status": "done",
      "video_url": "https://cdn.acedata.cloud/634d760216.mp4",
      "image_url": "https://cdn.acedata.cloud/4hfydw.jpg",
      "audio_url": "https://cdn.acedata.cloud/6f7d62b18b.wav"
    }
  }
}
```

Opis pól:

* `id`: unikalne ID zadania generowania wideo.
* `trace_id`: ID śledzenia tego żądania, używane do rozwiązywania problemów.
* `request`: treść żądania złożonego przy tworzeniu zadania.
* `response`: treść odpowiedzi zwrócona po zakończeniu zadania. Gdy `response.data.status` jest `done`, `response.data.video_url` to ostateczny adres wideo.
* `created_at`: czas utworzenia zadania, znacznik czasu Unix (sekundy, liczba zmiennoprzecinkowa).
* `started_at`: czas rozpoczęcia wykonania zadania, znacznik czasu Unix (sekundy, liczba zmiennoprzecinkowa).
* `finished_at`: czas zakończenia zadania, znacznik czasu Unix (sekundy, liczba zmiennoprzecinkowa). To pole nie jest zwracane, gdy zadanie nie jest zakończone.
* `elapsed`: czas wykonania zadania, jednostka to sekundy (liczba zmiennoprzecinkowa, z 3 miejscami po przecinku). To pole nie jest zwracane, gdy zadanie nie jest zakończone.

> Jeśli zadanie nie jest jeszcze zakończone, `status` może być w stanie innym niż `done`; jeśli zadanie nie istnieje lub nie wygenerowano jeszcze wyników, interfejs zwróci pusty obiekt `{}`, spróbuj ponownie później.

## Zapytanie zbiorcze o zadania

Ustaw `action` na `retrieve_batch` i przekaż tablicę `ids`:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/dreamina/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve_batch",
  "ids": [
    "362b4fed-67bd-11f1-ad11-00163e57d510",
    "0c0b4d3a-2f1e-4a6b-9c2d-2b3c4d5e6f70"
  ]
}'
```

W zwróconym wyniku `items` to tablica szczegółów zadań zbiorczych (każdy element ma format zgodny z wynikiem zapytania pojedynczego), `count` to liczba zadań zwróconych w tej odpowiedzi.

## Obsługa błędów

W przypadku wystąpienia błędu podczas wywoływania API, zwrócone zostaną odpowiednie kody błędów i informacje:

* `400 bad_request`: błąd żądania, mogą brakować niezbędne parametry, takie jak `id` / `trace_id`.
* `401 invalid_token`: brak autoryzacji, token autoryzacyjny jest nieprawidłowy lub brakujący.
* `429 too_many_requests`: zbyt wiele żądań, przekroczono limit szybkości.
* `500 api_error`: wewnętrzny błąd serwera.

### Przykład odpowiedzi błędu

```json theme={null}
{
  "error": {
    "code": "bad_request",
    "message": "id or trace_id is required to retrieve a task"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Wnioski

Dzięki temu dokumentowi zrozumiałeś, jak korzystać z API Dreamina Tasks do zapytania o wyniki pojedynczych lub zbiorczych zadań wideo. W połączeniu z interfejsem generowania w trybie asynchronicznym `callback_url` / `async`, można zrealizować stabilne zapytania. W razie jakichkolwiek pytań, skontaktuj się z naszym zespołem wsparcia technicznego.


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