curl --request GET \
--url 'https://toapis.com/v1/images/generations/task_01KA040M0HP1GJWBJYZMKX1XS1' \
--header 'Authorization: Bearer <token>'
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']}")
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);
});
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)
}
}
{
"id": "img_5b8b19afe5c24ab3a92df996f1a33931",
"object": "generation.task",
"model": "gemini-3-pro-image-preview",
"status": "in_progress",
"progress": 50,
"created_at": 1768381010,
"billing": {
"status": "pending"
}
}
{
"id": "img_5b8b19afe5c24ab3a92df996f1a33931",
"object": "generation.task",
"model": "gemini-3-pro-image-preview",
"status": "completed",
"progress": 100,
"created_at": 1768381010,
"completed_at": 1768381063,
"expires_at": 1768467463,
"result": {
"type": "image",
"data": [
{
"url": "https://files.toapis.com/generated/1768381061_c55c1bbb.jpg"
}
]
}
}
{
"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"
}
}
{
"id": "tsk_img_example",
"object": "generation.task",
"model": "gpt-image-2.5-flare-official",
"status": "completed",
"progress": 100,
"created_at": 1789099098,
"completed_at": 1789099158,
"expires_at": 1789185558,
"result": {
"type": "image",
"data": [
{
"url": "https://files.toapis.com/generated/example.png"
}
]
},
"usage": {
"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": "0",
"cost_usd": "0"
}
}
{
"error": {
"code": 404,
"message": "Задача не найдена",
"type": "not_found_error"
}
}
{
"error": {
"code": 401,
"message": "Ошибка аутентификации, проверьте ваш API ключ",
"type": "authentication_error"
}
}
Управление задачами
Получить статус задачи изображения
Запрос статуса и результатов задачи генерации изображений
GET
/
v1
/
images
/
generations
/
{task_id}
curl --request GET \
--url 'https://toapis.com/v1/images/generations/task_01KA040M0HP1GJWBJYZMKX1XS1' \
--header 'Authorization: Bearer <token>'
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']}")
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);
});
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)
}
}
{
"id": "img_5b8b19afe5c24ab3a92df996f1a33931",
"object": "generation.task",
"model": "gemini-3-pro-image-preview",
"status": "in_progress",
"progress": 50,
"created_at": 1768381010,
"billing": {
"status": "pending"
}
}
{
"id": "img_5b8b19afe5c24ab3a92df996f1a33931",
"object": "generation.task",
"model": "gemini-3-pro-image-preview",
"status": "completed",
"progress": 100,
"created_at": 1768381010,
"completed_at": 1768381063,
"expires_at": 1768467463,
"result": {
"type": "image",
"data": [
{
"url": "https://files.toapis.com/generated/1768381061_c55c1bbb.jpg"
}
]
}
}
{
"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"
}
}
{
"id": "tsk_img_example",
"object": "generation.task",
"model": "gpt-image-2.5-flare-official",
"status": "completed",
"progress": 100,
"created_at": 1789099098,
"completed_at": 1789099158,
"expires_at": 1789185558,
"result": {
"type": "image",
"data": [
{
"url": "https://files.toapis.com/generated/example.png"
}
]
},
"usage": {
"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": "0",
"cost_usd": "0"
}
}
{
"error": {
"code": 404,
"message": "Задача не найдена",
"type": "not_found_error"
}
}
{
"error": {
"code": 401,
"message": "Ошибка аутентификации, проверьте ваш API ключ",
"type": "authentication_error"
}
}
Для пользователей из материкового Китая: используйте
https://toapis.cn в качестве эндпоинта (Base URL). Замените https://toapis.com на https://toapis.cn во всех примерах этого документа.- Запрос статуса выполнения и результатов асинхронной задачи генерации изображений
- Обновление статуса и отслеживание прогресса в реальном времени
- Получение сгенерированных изображений при завершении задачи
- Поддержка многоязычности (zh/en/ko/ja)
Авторизация
string
обязательно
Все эндпоинты требуют аутентификации Bearer TokenПолучить API ключ:Посетите Страницу управления API ключами для получения API ключаДобавьте в заголовок запроса:
Authorization: Bearer YOUR_API_KEY
Параметры пути
string
обязательно
ID задачи, возвращенный API генерации изображений
curl --request GET \
--url 'https://toapis.com/v1/images/generations/task_01KA040M0HP1GJWBJYZMKX1XS1' \
--header 'Authorization: Bearer <token>'
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']}")
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);
});
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)
}
}
{
"id": "img_5b8b19afe5c24ab3a92df996f1a33931",
"object": "generation.task",
"model": "gemini-3-pro-image-preview",
"status": "in_progress",
"progress": 50,
"created_at": 1768381010,
"billing": {
"status": "pending"
}
}
{
"id": "img_5b8b19afe5c24ab3a92df996f1a33931",
"object": "generation.task",
"model": "gemini-3-pro-image-preview",
"status": "completed",
"progress": 100,
"created_at": 1768381010,
"completed_at": 1768381063,
"expires_at": 1768467463,
"result": {
"type": "image",
"data": [
{
"url": "https://files.toapis.com/generated/1768381061_c55c1bbb.jpg"
}
]
}
}
{
"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"
}
}
{
"id": "tsk_img_example",
"object": "generation.task",
"model": "gpt-image-2.5-flare-official",
"status": "completed",
"progress": 100,
"created_at": 1789099098,
"completed_at": 1789099158,
"expires_at": 1789185558,
"result": {
"type": "image",
"data": [
{
"url": "https://files.toapis.com/generated/example.png"
}
]
},
"usage": {
"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": "0",
"cost_usd": "0"
}
}
{
"error": {
"code": 404,
"message": "Задача не найдена",
"type": "not_found_error"
}
}
{
"error": {
"code": 401,
"message": "Ошибка аутентификации, проверьте ваш API ключ",
"type": "authentication_error"
}
}
Ответ
string
Уникальный идентификатор задачи
string
Тип объекта, всегда
generation.taskstring
Статус задачи
submitted- Отправлена, ожидает обработкиin_progress- Обрабатываетсяcompleted- Успешно завершеноfailed- Ошибка
string
Используемая модель генерации изображений
integer
Время создания задачи (Unix timestamp)
integer
Время завершения задачи (Unix timestamp, возвращается только при завершении)
string
URL сгенерированного изображения (возвращается только при успехе)
string
Оптимизированный промпт (поддерживается некоторыми моделями)
integer
Время истечения URL изображения (Unix timestamp)
object
Необязательные сведения об оплате задачи генерации изображения. Статус оплаты не зависит от статуса генерации:
completed не гарантирует завершение расчёта. Если данные оплаты нельзя подтвердить, поле billing целиком отсутствует, а не возвращается как null. Отсутствие поля не означает бесплатную задачу.Показать Свойства
Показать Свойства
string
pending означает, что расчёт или возврат ещё не подтверждён; суммы отсутствуют. settled означает подтверждённую итоговую сумму. refunded означает подтверждённый возврат или отсутствие итогового списания после ошибки, включая ошибку до первого списания.string
Кредиты, фактически списанные платформой с клиента, в виде десятичной строки. Возвращаются только при
settled или refunded.string
Сумма в USD, фактически списанная платформой с клиента, в виде десятичной строки. Включает скидки и коэффициенты, применённые при расчёте задачи, и не является себестоимостью провайдера.
object
Необязательная статистика токенов изображения после расчёта. Поля токенов возвращаются только при
Все счётчики токенов являются неотрицательными целыми числами JSON. Кэшированные токены входят во входные токены и не должны прибавляться повторно. При отсутствии детализации поле
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 целиком пропускается. usage.tool_usage.web_search может возвращаться отдельно или вместе с токенами изображения.object
Статус оплаты и учёт расходов
Эти правила применяются к запросам статуса задач генерации изображений для любых моделей и каналов. Варианты 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. Если одно из полей отсутствует, используйте этот эндпоинт как резерв. См. Цены и фактические списания.
Справка по статусам задач
| Статус | Описание | Финальный | Рекомендуемое действие |
|---|---|---|---|
submitted | Задача отправлена, ожидает обработки | ❌ | Подождите не менее 5–10 секунд с jitter |
in_progress | Задача обрабатывается | ❌ | Подождите не менее 5–10 секунд с jitter |
completed | Задача успешно завершена | ✅ | Получите изображение из поля url |
failed | Обработка задачи не удалась | ✅ | Проверьте информацию об ошибке |
Стратегия опроса
Начальное ожидание: 5 секунд
Интервал опроса: не менее 5–10 секунд с random jitter
Максимальное ожидание: 120 секунд
Типичное время: 5-30 секунд
Пример опроса на Python
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("Таймаут задачи")
Срок действия ресурсов
URL сгенерированных изображений действительны 24 часа
- Загрузите и сохраните изображения в течение срока действия
- Поле
expires_atуказывает время истечения изображения (Unix timestamp) - После истечения срока изображения недоступны; для повторного получения отправьте новую задачу
Коды ошибок
| HTTP код | Тип ошибки | Описание |
|---|---|---|
| 400 | invalid_request | Неверные параметры запроса |
| 401 | unauthorized | Ошибка аутентификации, проверьте API Key |
| 402 | insufficient_quota | Недостаточно средств |
| 404 | task_not_found | Задача не найдена |
| 422 | content_policy_violation | Нарушение политики контента |
| 429 | rate_limit_exceeded | Превышен лимит запросов |
| 500 | internal_error | Внутренняя ошибка сервера |
Используйте единый Task Webhook, polling оставьте резервом. Интервал не менее 5–10 секунд с jitter; при
429 соблюдайте Retry-After. Batch — максимум 100 задач. См. лимиты.