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

# Suno: общие соглашения и запрос задачи

>  - Общее описание музыкальных интерфейсов Suno: аутентификация, жизненный цикл асинхронной задачи, model / version, ссылка на исходную аудиодорожку
- Запрос задачи: GET /v1/music/tasks/:task_id, опрос до completed / failed 

<Info>
  Эта страница описывает общие соглашения для всех музыкальных интерфейсов Suno и используется вместе с отдельной документацией по каждому эндпоинту. Все интерфейсы генерации / редактирования являются **асинхронными задачами**: при отправке вы получаете `task_id`, а затем опрашиваете интерфейс запроса с этой страницы, чтобы получить результат.
</Info>

## Аутентификация

Все запросы должны содержать в заголовках:

```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

Перейдите на [страницу управления API Key](https://apimart.ai/keys), чтобы получить API Key.

## Жизненный цикл задачи (все интерфейсы асинхронные)

<Steps>
  <Step title="Отправка">
    `POST /v1/music/generations/<операция>` → сразу возвращает наш `task_id`:

    ```json theme={null}
    { "code": 200, "data": [ { "status": "submitted", "task_id": "task_xxx" } ] }
    ```
  </Step>

  <Step title="Опрос">
    `GET /v1/music/tasks/:task_id` до тех пор, пока `status` не станет `completed` или `failed`. Во время генерации `status` равен `pending`, а `progress` проходит: в очереди `10` → готово `50` → завершено `100`. Рекомендуемый интервал опроса 3–5 с; генерация музыки обычно занимает 30–120 с.
  </Step>

  <Step title="Получение результата">
    После завершения возьмите `audio_url` / `image_url` / `video_url` и др. из `data.result.music[]`.
  </Step>
</Steps>

Переходы состояний задачи: `submitted` → `pending` → `completed` / `failed`. **При неудаче `data.error.message` содержит причину, а предварительно списанная квота возвращается автоматически.**

## Версия version

`v3.5` / `v4` / `v4.5` / `v4.5+` / `v4.5-all` / `v5` / `v5.5`, влияет на качество звука и тарификацию; если не передавать, используется значение по умолчанию. Доступные версии и значения по умолчанию различаются в зависимости от эндпоинта — некоторые поддерживают лишь часть версий, а у некоторых измерение версии отсутствует вовсе; см. документацию каждого эндпоинта.

## Ссылка на исходную аудиодорожку: task\_id + audio\_index

Операции на основе уже существующей песни (продолжение / кавер / разделение дорожек / добавление вокала / обрезка…) **не требуют** запоминать какие-либо вышестоящие id, передаётся только:

* `task_id`: наш `task_id` той задачи, которая создала исходную аудиодорожку
* `audio_index`: номер песни в результате `music[]` этой задачи (нумерация с 1, по умолчанию `1`; за одну генерацию обычно создаётся 2 песни: 1 и 2)

<Warning>
  Если исходную дорожку не удаётся разрешить (задача не завершена / индекс вне диапазона / `task_id` не найден), при отправке возвращается `400`.
</Warning>

## Запрос задачи: GET /v1/music/tasks/:task\_id

<ParamField path="task_id" type="string" required>
  Наш `task_id`, возвращённый интерфейсом отправки.
</ParamField>

Опрашивайте этот интерфейс, пока `status` не станет `completed` или `failed`. После завершения возьмите результат из `data.result.music[]`.

## Response

<ResponseField name="task_id" type="string">
  Уникальный идентификатор задачи
</ResponseField>

<ResponseField name="status" type="string">
  Состояние задачи: `submitted` / `pending` / `completed` / `failed`
</ResponseField>

<ResponseField name="progress" type="integer">
  Прогресс: в очереди `10` → готово `50` → завершено `100`
</ResponseField>

<ResponseField name="data" type="object">
  Данные результата

  <Expandable title="Свойства">
    <ResponseField name="result" type="object">
      Присутствует, когда `status` равен `completed`

      <Expandable title="Свойства result">
        <ResponseField name="music" type="array">
          Список результатов (за одну генерацию обычно 2 песни)

          <Expandable title="Свойства music[]">
            <ResponseField name="audio_id" type="string">
              id аудиодорожки, используется для последующих операций через `audio_index`
            </ResponseField>

            <ResponseField name="title" type="string">
              Заголовок
            </ResponseField>

            <ResponseField name="duration" type="number">
              Длительность (секунды)
            </ResponseField>

            <ResponseField name="lyrics" type="string">
              Текст песни
            </ResponseField>

            <ResponseField name="tags" type="string">
              Теги стиля
            </ResponseField>

            <ResponseField name="audio_url" type="string">
              URL аудиофайла
            </ResponseField>

            <ResponseField name="image_url" type="string">
              URL обложки
            </ResponseField>

            <ResponseField name="image_large_url" type="string">
              URL обложки в большом размере
            </ResponseField>

            <ResponseField name="video_url" type="string">
              URL видео MV (если уже сгенерировано)
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="error" type="object">
      Присутствует, когда `status` равен `failed`

      <Expandable title="Свойства error">
        <ResponseField name="message" type="string">
          Причина неудачи (предварительно списанная квота возвращается автоматически)
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json completed theme={null}
  {
    "task_id": "task_01ABC...",
    "status": "completed",
    "progress": 100,
    "data": {
      "result": {
        "music": [
          {
            "audio_id": "<track id, used with audio_index to locate it for subsequent operations>",
            "title": "Summer Breeze",
            "duration": 128.5,
            "lyrics": "……",
            "tags": "electronic, upbeat",
            "audio_url": "https://.../xxx.mp3",
            "image_url": "https://.../cover.png",
            "image_large_url": "https://.../cover_large.png",
            "video_url": "https://.../mv.mp4"
          }
        ]
      }
    }
  }
  ```

  ```json failed theme={null}
  {
    "task_id": "task_01ABC...",
    "status": "failed",
    "progress": 100,
    "data": {
      "error": {
        "message": "generation failed"
      }
    }
  }
  ```
</ResponseExample>