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

# Получить статус задачи изображения

> Запрос статуса и результатов задачи генерации изображений

> [!NOTE]
>
> **Для пользователей из материкового Китая:** используйте `https://toapis.cn` в качестве эндпоинта (Base URL). Замените `https://toapis.com` на `https://toapis.cn` во всех примерах этого документа.

* Запрос статуса выполнения и результатов асинхронной задачи генерации изображений
* Обновление статуса и отслеживание прогресса в реальном времени
* Получение сгенерированных изображений при завершении задачи
* Поддержка многоязычности (zh/en/ko/ja)

Все задачи генерации изображений выполняются асинхронно. После отправки задачи необходимо запросить статус и результаты через API запроса.

Обычные задачи изображений и видео также доступны через `GET /v1/tasks/{task_id}` с теми же определениями `usage` и `billing`. Эта страница описывает ответ пути запроса генерации, указанного в начале.

Примеры показывают поля, а не текущие цены модели или постоянный способ тарификации. Используйте поля и суммы, возвращённые для конкретной задачи.

## Авторизация

**Authorization** `string` *required*

Все эндпоинты требуют аутентификации Bearer Token

Получить API ключ:

Посетите [Страницу управления API ключами](https://toapis.com/console/token) для получения API ключа

Добавьте в заголовок запроса:

```
Authorization: Bearer YOUR_API_KEY
```

## Параметры пути

**task\_id** `string` *required*

ID задачи, возвращенный API генерации изображений

```bash cURL theme={null}
curl --request GET \
  --url 'https://toapis.com/v1/images/generations/task_01KA040M0HP1GJWBJYZMKX1XS1' \
  --header 'Authorization: Bearer <token>'
```

```python Python theme={null}
import requests
import time

API_BASE = 'https://toapis.com'
API_KEY = 'sk-xxxxxxxxxxxxxxxxxxxxxx'

headers = {
    'Authorization': f'Bearer {API_KEY}'
}

def get_image_status(task_id):
    response = requests.get(f'{API_BASE}/v1/images/generations/{task_id}', headers=headers)
    return response.json()

def wait_for_image(task_id, max_attempts=60, interval=3):
    for _ in range(max_attempts):
        result = get_image_status(task_id)
        status = result.get('status')
        
        print(f"Статус: {status}")
        
        if status == 'completed':
            return result
        elif status == 'failed':
            raise Exception(f"Задача не выполнена: {result}")
        
        time.sleep(interval)
    
    raise Exception("Таймаут задачи")

# Пример использования
task_id = "task_01KA040M0HP1GJWBJYZMKX1XS1"
result = wait_for_image(task_id)
print(f"URL изображения: {result['url']}")
```

```javascript JavaScript theme={null}
const API_BASE = 'https://toapis.com';
const API_KEY = 'sk-xxxxxxxxxxxxxxxxxxxxxx';

async function getImageStatus(taskId) {
  const response = await fetch(`${API_BASE}/v1/images/generations/${taskId}`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });
  return response.json();
}

async function waitForImage(taskId, maxAttempts = 60, interval = 3000) {
  for (let i = 0; i < maxAttempts; i++) {
    const result = await getImageStatus(taskId);
    const status = result.status;
    
    console.log(`Статус: ${status}`);
    
    if (status === 'completed') {
      return result;
    } else if (status === 'failed') {
      throw new Error(`Задача не выполнена: ${JSON.stringify(result)}`);
    }
    
    await new Promise(r => setTimeout(r, interval));
  }
  
  throw new Error('Таймаут задачи');
}

// Пример использования
const taskId = 'task_01KA040M0HP1GJWBJYZMKX1XS1';
waitForImage(taskId).then(result => {
  console.log('URL изображения:', result.url);
});
```

```go Go theme={null}
package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
    "time"
)

func getImageStatus(taskId string) (map[string]interface{}, error) {
    url := fmt.Sprintf("https://toapis.com/v1/images/generations/%s", taskId)

    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("Authorization", "Bearer <token>")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    
    var result map[string]interface{}
    json.Unmarshal(body, &result)
    
    return result, nil
}

func main() {
    taskId := "task_01KA040M0HP1GJWBJYZMKX1XS1"
    
    for i := 0; i < 60; i++ {
        result, _ := getImageStatus(taskId)
        status := result["status"].(string)
        
        fmt.Printf("Статус: %s\n", status)
        
        if status == "completed" {
            fmt.Println("Генерация изображения завершена!")
            fmt.Println("URL изображения:", result["url"])
            break
        }
        
        time.Sleep(3 * time.Second)
    }
}
```

```json 200 - Обрабатывается theme={null}
{
  "id": "img_5b8b19afe5c24ab3a92df996f1a33931",
  "object": "generation.task",
  "model": "gemini-3-pro-image-preview",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1768381010,
  "billing": {
    "status": "pending"
  }
}
```

```json 200 - Завершено theme={null}
{
  "id": "img_5b8b19afe5c24ab3a92df996f1a33931",
  "object": "generation.task",
  "model": "gemini-3-pro-image-preview",
  "status": "completed",
  "progress": 100,
  "created_at": 1768381010,
  "finished_at": 1768381063,
  "completed_at": 1768381063,
  "expires_at": 1768467463,
  "result": {
    "type": "image",
    "data": [
      {
        "url": "https://files.toapis.com/generated/1768381061_c55c1bbb.jpg"
      }
    ]
  },
  "usage": {
    "charge_type": "per_request",
    "requests": 1
  },
  "billing": {
    "status": "settled",
    "credits": "100",
    "cost_usd": "0.5"
  }
}
```

```json 200 - Ошибка theme={null}
{
  "id": "img_73c450923a9a43e4aabf426e1c681d64",
  "object": "generation.task",
  "model": "gemini-3-pro-image-preview",
  "status": "failed",
  "progress": 0,
  "created_at": 1768215312,
  "billing": {
    "status": "refunded",
    "credits": "0",
    "cost_usd": "0"
  },
  "error": {
    "code": "generation_failed",
    "message": "вызов upstream API не удался: upstream вернул статус 422"
  }
}
```

```json 200 - Завершено - Бесплатная задача с токенами theme={null}
{
  "id": "tsk_img_example",
  "object": "generation.task",
  "model": "gpt-image-2.5-flare-official",
  "status": "completed",
  "progress": 100,
  "created_at": 1789099098,
  "finished_at": 1789099158,
  "completed_at": 1789099158,
  "expires_at": 1789185558,
  "result": {
    "type": "image",
    "data": [
      {
        "url": "https://files.toapis.com/generated/example.png"
      }
    ]
  },
  "usage": {
    "charge_type": "per_token",
    "billed_tokens": 1000,
    "input_tokens": 100,
    "output_tokens": 900,
    "total_tokens": 1000,
    "input_tokens_details": {
      "text_tokens": 20,
      "image_tokens": 80,
      "cached_tokens": 30,
      "cached_tokens_details": {
        "text_tokens": 10,
        "image_tokens": 20
      }
    },
    "output_tokens_details": {
      "text_tokens": 0,
      "image_tokens": 900
    }
  },
  "billing": {
    "status": "settled",
    "credits": "10",
    "cost_usd": "0.05"
  }
}
```

```json 404 theme={null}
{
  "error": {
    "code": 404,
    "message": "Задача не найдена",
    "type": "not_found_error"
  }
}
```

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "message": "Ошибка аутентификации, проверьте ваш API ключ",
    "type": "authentication_error"
  }
}
```

## Ответ

**id** `string`

Уникальный идентификатор задачи

**client\_business\_id** `string`

Необязательный бизнес-ID клиента, возвращается только при передаче `client_business_id` во время создания задачи.

**object** `string`

Тип объекта, всегда `generation.task`

**status** `string`

Статус задачи

* `queued` - Отправлена, ожидает обработки
* `in_progress` - Обрабатывается
* `completed` - Успешно завершено
* `failed` - Ошибка

**progress** `integer`

Целочисленный процент выполнения от 0 до 100.

**model** `string`

Используемая модель генерации изображений

**created\_at** `integer`

Время создания задачи (Unix timestamp)

**finished\_at** `integer`

Время окончания задачи, Unix timestamp. Этот путь запроса возвращает его для успешных и неуспешных задач, если время окончания сохранено.

**completed\_at** `integer`

Время завершения задачи (Unix timestamp, возвращается только при завершении)

**expires\_at** `integer`

Время истечения URL изображения (Unix timestamp)

**result** `object`

Результат успешной задачи. URL изображения находится в `result.data[].url`.

**Свойства**

**type** `string`

Тип результата, всегда `image`.

**data** `array`

Массив изображений с полем `url` в каждом элементе.

**billing** `object`

Необязательные сведения об оплате задачи генерации изображения. Статус оплаты не зависит от статуса генерации: `completed` не гарантирует завершение расчёта. Если данные оплаты нельзя подтвердить, поле `billing` целиком отсутствует, а не возвращается как `null`. Отсутствие поля не означает бесплатную задачу.

**Свойства**

**status** `string`

`pending` означает, что расчёт или возврат ещё не подтверждён; суммы отсутствуют. `settled` означает подтверждённую итоговую сумму. `refunded` означает подтверждённый возврат или отсутствие итогового списания после ошибки, включая ошибку до первого списания.

**credits** `string`

Кредиты, фактически списанные платформой с клиента, в виде десятичной строки. Возвращаются только при `settled` или `refunded`.

**cost\_usd** `string`

Сумма в USD, фактически списанная платформой с клиента, в виде десятичной строки. Включает скидки и коэффициенты, применённые при расчёте задачи, и не является себестоимостью провайдера.

**usage** `object`

Необязательные оплачиваемые количества, детализация токенов изображения и счётчики инструментов. Поля `charge_type`, `requests`, `billed_tokens` и другие описаны в разделе [Поля использования задачи](https://docs.toapis.com/docs/ru/api-reference/account/pricing.md). Детализация токенов возвращается, только если `billing.status` равен `settled`, а сохранённые данные корректны и соответствуют окончательному списанию. Неподтверждённые части опускаются; подтверждённые суммы и изображения остаются доступны.

| Поле | Тип | Описание |
| - | - | - |
| `input_tokens` | integer | Всего входных токенов, включая текст и изображения |
| `output_tokens` | integer | Всего выходных токенов |
| `total_tokens` | integer | `input_tokens + output_tokens` |
| `input_tokens_details.text_tokens` | integer | Входные текстовые токены |
| `input_tokens_details.image_tokens` | integer | Входные токены изображений |
| `input_tokens_details.cached_tokens` | integer | Кэшированные входные токены, уже включённые в общее число входных |
| `input_tokens_details.cached_tokens_details.text_tokens` | integer | Кэшированные входные текстовые токены |
| `input_tokens_details.cached_tokens_details.image_tokens` | integer | Кэшированные входные токены изображений |
| `output_tokens_details.text_tokens` | integer | Выходные текстовые токены; только при наличии детализации выхода |
| `output_tokens_details.image_tokens` | integer | Выходные токены изображений; только при наличии детализации выхода |
| `output_tokens_details.text_or_reasoning_tokens` | integer | Выходные токены, когда текст и рассуждение тарифицируются по одной цене и не разделены; не входят в `text_tokens`; возвращаются только при наличии |
| `charge_type` | string | Способ тарификации: `per_request` - за запрос, `per_token` - за токены |
| `requests` | integer | Количество оплачиваемых запросов, возвращается для `per_request`. Параметр запроса `n` напрямую не умножается |
| `billed_tokens` | integer | Токены, использованные для расчёта цены, возвращаются для `per_token` |
| `input_images` | integer | Оплачиваемые входные изображения после вычета бесплатной квоты; при нуле пропускается |
| `tool_usage.web_search`, `tool_usage.image_search`, `tool_usage.grounding_queries` | integer | Количество веб-поисков, поисков изображений и запросов Grounding; возвращается при фактическом использовании |

`charge_type`, `requests`, `billed_tokens` и `input_images` - это оплачиваемые количества, они возвращаются только вместе с `billing.status=settled`. Задачи с оплатой за запрос, списанной целиком при отправке, также возвращают `settled` и фактическую сумму. Все счётчики токенов являются неотрицательными целыми числами JSON. Кэшированные токены входят во входные токены и не должны прибавляться повторно. При отсутствии детализации поле `output_tokens_details` целиком пропускается. `usage.tool_usage.web_search` может возвращаться отдельно или вместе с токенами изображения.

**error** `object`

Информация об ошибке (только при неудаче)

**Свойства**

**code** `string`

Код ошибки

**message** `string`

Описание ошибки

## Статус оплаты и учёт расходов

Эти правила применяются к запросам статуса задач генерации изображений для любых моделей и каналов. Варианты Sunburst и Flare VIP / Official семейства GPT-Image-2.5 поддерживают статистику токенов; для других моделей её наличие зависит от сохранённых данных расчёта. Суммы в примере показывают формат ответа, а не фиксированную цену.

| billing.status | Значение | Суммы и токены изображения |
| - | - | - |
| `pending` | Генерация, расчёт или подтверждение возврата ещё не завершены | Суммы и токены изображения отсутствуют; предварительное списание не является итоговым расходом |
| `settled` | Итоговая сумма подтверждена | Суммы возвращаются, токены изображения включаются при наличии корректных данных. Бесплатная задача также может вернуть `"0"` |
| `refunded` | Подтверждён возврат или отсутствие итогового списания после ошибки | `credits` и `cost_usd` равны `"0"`; токены изображения отсутствуют |

* Суммы отражают подтверждённое итоговое списание по задаче. Запрос не выполняет списание, доплату, возврат или пересчёт по текущим ценам моделей. Для учёта используйте возвращённые суммы, а не произведение токенов на текущую цену.
* Обновляйте сумму по уникальному `id` задачи, не прибавляя одно и то же списание при каждом опросе. Используйте десятичную арифметику. `pending` или отсутствие поля означают неизвестный расход, а не ноль.
* Суммы передаются десятичными строками без фиксированного количества знаков после точки.
* При отсутствии или несогласованности данных оплаты поле `billing` может отсутствовать. Если изображение ещё нельзя выдать и задача временно отображается как `in_progress`, оба поля `billing` и `usage` также могут отсутствовать.
* Успешный Webhook использует для `data.usage` и `data.billing` те же условия подтверждения и значения полей, что и этот эндпоинт. Webhook - это снимок на момент создания события; если поле отсутствует, используйте этот эндпоинт как резерв. См. [Цены и фактические списания](https://docs.toapis.com/docs/ru/api-reference/account/pricing.md).

## Справка по статусам задач

| Статус | Описание | Финальный | Рекомендуемое действие |
| - | - | - | - |
| `queued` | Задача отправлена, ожидает обработки | ❌ | Подождите не менее 5-10 секунд с jitter |
| `in_progress` | Задача обрабатывается | ❌ | Подождите не менее 5–10 секунд с jitter |
| `completed` | Задача успешно завершена | ✅ | Получите изображение из поля url |
| `failed` | Обработка задачи не удалась | ✅ | Проверьте информацию об ошибке |

## Стратегия опроса

```
Начальное ожидание: 5 секунд
Интервал опроса: не менее 5–10 секунд с random jitter
Максимальное ожидание: 120 секунд
Типичное время: 5-30 секунд
```

### Пример опроса на Python

```python theme={null}
import time
import random
import requests

def poll_image_task(task_id, api_key, max_wait=120):
    """Опрос задачи генерации изображения до завершения или таймаута"""
    start_time = time.time()
    interval = 5
    
    while time.time() - start_time < max_wait:
        response = requests.get(
            f'https://toapis.com/v1/images/generations/{task_id}',
            headers={'Authorization': f'Bearer {api_key}'}
        )
        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', interval))
            time.sleep(retry_after + random.uniform(0, 1))
            interval = min(interval * 2, 60)
            continue
        response.raise_for_status()
        data = response.json()
        
        if data['status'] == 'completed':
            return data['url']
        elif data['status'] == 'failed':
            raise Exception(f"Генерация не удалась: {data['error']['message']}")
        
        time.sleep(interval + random.uniform(0, 1))
    
    raise TimeoutError("Таймаут задачи")
```

## Срок действия ресурсов

> [!WARNING]
>
> URL сгенерированных изображений действительны **24 часа**
>
> * Загрузите и сохраните изображения в течение срока действия
> * Поле `expires_at` указывает время истечения изображения (Unix timestamp)
> * После истечения срока изображения недоступны; для повторного получения отправьте новую задачу

## Ошибки и причины сбоя

Ошибки запросов, причины сбоя задач и восстановление описаны в [справочнике ошибок](https://docs.toapis.com/docs/ru/api-reference/errors.md). После успешной проверки учитывайте статус задачи; HTTP-статус не является бизнес-кодом ошибки.

> [!NOTE]
>
> Используйте единый [Task Webhook](https://docs.toapis.com/docs/ru/api-reference/webhooks/task-webhooks.md), polling оставьте резервом. Интервал не менее 5–10 секунд с jitter; при `429` соблюдайте `Retry-After`. Batch — максимум 100 задач. См. [лимиты](https://docs.toapis.com/docs/ru/api-reference/rate-limits/async-tasks.md).


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