# Список, цена, модели

`GET /v1/tasks`

Свои задачи, по новым: `{ "data": [задача, …], "next_cursor": "…" }`. Следующая страница по `next_cursor` в параметре `cursor`; на последней странице `next_cursor` нет. Неизвестный параметр или параметр дважды: 400.

- `kind` (string) — Точный, например `image/generate`, или группа `image/*`
- `status` (string) — `queued`, `in_progress`, `completed` или `failed`
- `created_after`, `created_before` (string) — Границы по времени создания, RFC 3339 от 2020 года до завтра; `+` в смещении пишите как `%2B` или берите `Z`. Обе исключающие и сравниваются с точностью до микросекунд, а `at` в событиях до секунды: `created_after`, равный `at` задачи, её не исключит
- `metadata[ключ]` (string) — Значение из `metadata` задачи. Несколько таких параметров: должны совпасть все
- `limit` (integer) — Размер страницы, от 1 до 100, по умолчанию 20
- `cursor` (string) — `next_cursor` прошлой страницы

**Пример запроса**

```bash
# список: задачи с изображениями, по новым
curl 'https://api.polyapi.ru/v1/tasks?kind=image/*&limit=20' \
  -H "Authorization: Bearer $POLYAPI_KEY"

# цена и проверка запроса без создания задачи
curl https://api.polyapi.ru/v1/tasks/quote \
  -H "Authorization: Bearer $POLYAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "image/generate",
    "model": "google/gemini-3-pro-image",
    "input": {"prompt": "Рыжий кот на подоконнике, акварель", "aspect_ratio": "16:9", "resolution": "2K"}
  }'

# модели задач с полями, значениями и ценами
curl 'https://api.polyapi.ru/v1/tasks/models?kind=image/*' \
  -H "Authorization: Bearer $POLYAPI_KEY"
```

**Ответ списка**

```json
{
  "data": [
    {
      "id": "0f6e4c1a-8a7b-4d2e-9c55-3b1f2a7d9e10",
      "kind": "image/generate",
      "model": "google/gemini-3-pro-image",
      "status": "completed",
      "events": [
        {
          "type": "task.queued",
          "at": "2026-11-07T12:00:00Z"
        },
        {
          "type": "attempt.started",
          "at": "2026-11-07T12:00:00Z",
          "attempt": 1
        },
        {
          "type": "task.completed",
          "at": "2026-11-07T12:00:34Z"
        }
      ],
      "output": [
        {
          "type": "image",
          "url": "https://storage.yandexcloud.net/…/0f6e4c1a-8a7b-4d2e-9c55-3b1f2a7d9e10/0.png?X-Amz-Expires=7200&X-Amz-Signature=…",
          "expires_at": "2026-11-07T14:00:00Z",
          "media_type": "image/png",
          "retained_until": "2026-12-07T12:00:34Z",
          "width": 2752,
          "height": 1536,
          "bytes": 6214533
        }
      ],
      "usage": {
        "cost": {
          "amount": "17.18",
          "currency": "rub"
        }
      }
    }
  ]
}
```

`POST /v1/tasks/quote`

Цена и проверка запроса без создания задачи. Тело то же, что у создания; `id` и `wait` не нужны, но проверяется их форма; занят ли id, не проверяется. Ответ: `{ "cost": {…}, "balance": {…}, "sufficient": true }`. Запрос с ошибкой даёт тот же 400 или 404 с `param`, что дало бы создание. Задачу не создаёт, денег не трогает, 402 не возвращает. `sufficient` сравнивает цену только со свободным балансом аккаунта: лимит трат ключа, лимиты частоты и доступность модели он не проверяет, поэтому при `sufficient: true` создание всё равно может ответить 402 `key_limit_reached`, 429 `rate_limited` или 503 `capacity_exceeded`. Сама оценка, в отличие от чтения, расходует лимит запросов ключа в минуту: она тоже может ответить 429 `rate_limited` или 503 `upstream_unavailable`. Цена справочная, не обещание: задача списывается по каталогу на момент создания.

`GET /v1/tasks/models`

Модели задач: `{ "data": [модель, …] }`, фильтр `kind` как в списке. Провайдеры и маршруты не показываются.

- `id`, `name`, `kind` (string) — Имя для поля `model`, название, вид задачи
- `input` (object) — Поля, которые принимает эта модель, с допустимыми значениями: `type`, `values` (у `format` и `quality`), `max_length`, `min`, `max`, `max_items`, `max_bytes`, `media_types`, и `default` там, где он есть
- `variants` (array) — Допустимые сочетания кадра: у каждого варианта есть `aspect_ratio`, `resolution` и `size`. В запросе присылайте либо пару, либо `size`. У варианта по умолчанию `"default": true`
- `price` (object) — Цена за одно изображение: `currency`, `per` (пока только `image`), `depends_on` и `rows`. `depends_on` перечисляет, от чего зависит цена: `resolution`, `quality`, `variant` (значение вида `1:1/2K`), `references` (число референсов строкой, `"0"`, `"1"`…). Пустой: одна строка на всё. Каждая строка: эти значения и `amount`. Строк цены может быть меньше, чем вариантов кадра. Цена конкретной задачи: `quote`

Источник: https://polyapi.ru/docs/tasks-more