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

# Жизненный цикл задачи

> Скачивание, архивирование, удаление и восстановление медиа-задач

Операции над уже созданной задачей, которые не относятся ни к созданию, ни к чтению состояния.

Здесь же — `POST .../lyrics/timestamped`, единственный эндпоинт, который работает с содержимым результата, а не с самим результатом.

## Скачать результат

`GET /api/v1/async/media/tasks/{task_id}/download`

| Результатов | Что вернётся |
| - | - |
| Один | Сам файл, потоком, с `Content-Type` и `Content-Disposition: attachment` |
| Несколько | ZIP-архив без сжатия, потоком, `application/zip`, имя `task_<task_id>.zip` |

<Note>
  Это потоковая отдача, а не JSON и не редирект. У архива нет `Content-Length` — он собирается на лету, поэтому не ждите заголовка размера.
</Note>

```bash cURL theme={null} theme={null}
curl -L -o result.zip "https://speshu.ai/api/v1/async/media/tasks/$TASK_ID/download" \
  -H "Authorization: Bearer $SPESHU_API_KEY"
```

Если у задачи нет ни одного сохранённого результата, придёт `404` — даже если задача ещё не завершена. Скачать можно и незавершённую задачу, у которой результат уже появился.

## Архивировать

`PATCH /api/v1/async/media/tasks/{task_id}/archive`

Тело — `{"archive": <bool>}`; поле необязательное, так что `{}` означает `false`. Ответ — `204` с пустым телом.

Задача переезжает между активным и архивным списком: результат, файлы и сама задача не меняются, архивная задача по-прежнему доступна по `GET` по идентификатору.

<Warning>
  Операция **не идемпотентна**. Повторный вызов с тем же значением `archive` вернёт `404`, потому что задача уже в нужном состоянии. Перед вызовом узнавайте текущее состояние или игнорируйте `404` в сценарии, где состояние не важно.
</Warning>

## Удалить

`DELETE /api/v1/async/media/tasks/{task_id}` — без тела, ответ `204`.

Задача помечается удалённой вместе с созданными ею файлами — одним действием. Сами байты в объектном хранилище при этом не трогаются, а запись восстанавливается отдельным запросом.

Операция идемпотентна: повторный вызов снова вернёт `204`. После удаления задача пропадает из [списка](/docs/api-reference/media/list), а `GET` по ней отдаёт `404`.

## Восстановить

`POST /api/v1/async/media/tasks/{task_id}/restore` — без тела, ответ `204`.

Снимает отметку удаления и возвращает задачу и удалённые вместе с ней файлы. Файлы, которые вы удалили по отдельности через `DELETE /api/v1/storage/{id}`, **не** восстанавливаются.

<Warning>
  Восстановление снимает флаг удаления, но не флаг архива. Задача, которая была архивной до удаления, вернётся архивной — снимите флаг архива отдельным запросом `PATCH .../archive {"archive": false}`.
</Warning>

## Текст песни с таймкодами

`POST /api/v1/async/media/tasks/{task_id}/lyrics/timestamped`

Тело — `{"audioId": "<идентификатор дорожки>"}`, где `audioId` берётся из `resultJson`: это поле `tracks[].id` музыкальной задачи. Ответ содержит слова с таймкодами, амплитудную дорожку и оценку качества распознавания.

```json theme={null} theme={null}
{
  "code": 200,
  "msg": "success",
  "data": {
    "alignedWords": [
      { "word": "Привет", "success": true, "startS": 1.36, "endS": 1.79, "palign": 0 }
    ],
    "waveformData": [0.12, 0.44, 0.9],
    "hootCer": 0.38,
    "isStreamed": false
  }
}
```

Доступно только для музыкальных задач. Для остальных моделей придёт `400`.

## Сводка

| Операция | Метод и путь | Тело | Ответ | Идемпотентна |
| - | - | - | - | - |
| Скачать | `GET .../download` | — | Файл или ZIP | Да |
| Архивировать | `PATCH .../archive` | `{"archive": bool}` | `204` | **Нет** |
| Удалить | `DELETE .../{task_id}` | — | `204` | Да |
| Восстановить | `POST .../restore` | — | `204` | Да |
| Таймкоды слов | `POST .../lyrics/timestamped` | `{"audioId": str}` | `200` + конверт | Да |

Здесь `...` — `/api/v1/async/media/tasks/{task_id}`.

Ошибки общие для медиа-эндпоинтов: `400`, `401`, `402`, `403`, `404`, `409`, `422`, `429`, `499`, `500`, `502`, `503`, `504`. Разбор — на странице [Ошибки](/docs/errors).

<CardGroup cols={2}>
  <Card title="Создать задачу" icon="plus" href="/docs/api-reference/media/create">
    Запуск генерации
  </Card>

  <Card title="Статус задачи" icon="magnifying-glass" href="/docs/api-reference/media/status">
    Поля объекта и состояния
  </Card>

  <Card title="Список задач" icon="list" href="/docs/api-reference/media/list">
    Фильтры и пагинация
  </Card>

  <Card title="Хранилище" icon="folder" href="/docs/api-reference/storage/list">
    Файлы, созданные задачами
  </Card>
</CardGroup>


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