Документация на метод "aiimages"

Как это работает

• 1 Берём модель из справочника — вызываем метод с models=1. Оттуда же берём допустимые для модели соотношения сторон и разрешения: у каждой нейросети они свои.
• 2 Ставим задачу — POST с промптом, моделью и режимом. В ответ приходит report_id. Лимиты списываются в момент создания задачи.
• 3 Забираем результат — периодически (раз в 5–10 секунд) запрашиваем метод с report_id, пока вместо In progress не придут ссылки на готовые изображения.

1Справочник моделей

/api/aiimages?models=1 — возвращает нейросети, доступные вашему ключу, и их возможности. Задача не создаётся, лимиты не списываются.

Ответ

{
  "models": [
    {
      "name": "Nano Banana Pro",
      "value": "nano-banana-pro",
      "promptLength": 0,
      "aspect_ratios": ["auto", "1:1", "2:3", "3:2", "3:4", "4:3", "9:16", "16:9", "21:9"],
      "resolutions": ["1K", "2K", "4K"],
      "supports_image_input": true,
      "supports_multi_image_input": true,
      "supports_native_lang": true
    },
    {
      "name": "Leonardo",
      "value": "leonardo",
      "promptLength": 1000,
      "aspect_ratios": [],
      "resolutions": [],
      "supports_image_input": false,
      "supports_multi_image_input": false,
      "supports_native_lang": false
    }
  ],
  "default": "leonardo"
}

2Постановка задачи

POST /api/aiimages — параметры передаются телом запроса.

Ответ

{
  "report_id": 18452301
}

Требования к изображению для обработки фона и апскейла

3Получение результата

GET /api/aiimages?report_id={id} — вызывается, пока задача не завершится. Повторные запросы бесплатны.

Задача ещё выполняется

{
  "error": "In progress",
  "code": 50,
  "progress": 40,
  "time": "2026-02-11 14:32:07"
}

Пример результата

{
  "request": {
    "modelName": "nano-banana-pro",
    "request_field": "Витрина пекарни, тёплый утренний свет",
    "part": "chat_bot",
    "aspect_ratio": "16:9",
    "resolution": "2K"
  },
  "response": {
    "data": [
      {
        "url": "https://tools.pixelplus.ru/storage/ai-images/img_65f2c1a9.png",
        "errors": ""
      }
    ],
    "errors": "",
    "errorType": null
  },
  "time": "2026-02-11 14:33:12",
  "cost": 450
}

Тарификация

У каждой модели своя цена генерации, у remove_background и upscale — собственные фиксированные цены. Часть моделей тарифицируется за запрос, часть — за изображение, у моделей с выбором разрешения цена растёт вместе с resolution. Актуальные цены показаны в интерфейсе инструмента, а фактическое списание всегда возвращается в поле cost вместе с результатом.

Если доступных лимитов не хватает, задача не создаётся: в ответе придут код ошибки и точные значения available / need.

Коды ошибок

Основные сообщения валидации в details

• Ошибка - неправильно выбранная модель нейросети! — модель не из справочника;
• Ошибка — неправильно выбранная вкладка! — недопустимое значение part;
• Ошибка — неправильно выбрано соотношение сторон! / …выбрано качество! — значение вне списка модели;
• Введите, пожалуйста, запрос. и Уменьшите размер запроса до {N} символов. — проблемы с промптом;
• Ошибка, уберите, пожалуйста, из запроса параметры… и …из запроса ссылки.;
• Исправьте, пожалуйста, запрос — фильтр 18+.;
• Исправьте, пожалуйста, URL — некорректный URL или недопустимый формат…, …локальные пути или localhost не поддерживаются., …указанный ресурс недоступен.;
• Исправьте, пожалуйста, параметр референса для изображения. Допустимые значения: img, cref, sref.;
• Данный метод доступен только платным тарифам!.

Примеры

cURL

# 1. Справочник моделей
curl 'https://tools.pixelplus.ru/api/aiimages?key={ключ-api}&models=1'

# 2. Постановка задачи
curl -X POST 'https://tools.pixelplus.ru/api/aiimages?key={ключ-api}' \
  -d 'modelName=nano-banana-pro' \
  -d 'part=chat_bot' \
  -d 'aspect_ratio=16:9' \
  -d 'resolution=2K' \
  --data-urlencode 'request_field=Витрина пекарни, тёплый утренний свет'

# 3. Результат
curl 'https://tools.pixelplus.ru/api/aiimages?key={ключ-api}&report_id=18452301'

PHP

<?php

$key = '{ключ-api}';
$base = 'https://tools.pixelplus.ru/api';

function apiRequest(string $url, array $data = null): array
{
    $curl = curl_init();
    $options = [
        CURLOPT_URL => $url,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 120,
    ];
    if ($data !== null) {
        $options[CURLOPT_POST] = true;
        $options[CURLOPT_POSTFIELDS] = $data;
    }
    curl_setopt_array($curl, $options);
    $response = curl_exec($curl);
    curl_close($curl);

    return json_decode($response, true) ?: [];
}

// 1. Ищем модель, которая умеет 16:9
$catalog = apiRequest("{$base}/aiimages?key={$key}&models=1");

$model = null;
foreach ($catalog['models'] as $item) {
    if (empty($item['aspect_ratios']) || in_array('16:9', $item['aspect_ratios'], true)) {
        $model = $item;
        break;
    }
}

$fields = [
    'modelName'     => $model['value'] ?? $catalog['default'],
    'part'          => 'chat_bot',
    'request_field' => 'Витрина пекарни, тёплый утренний свет',
    'aspect_ratio'  => '16:9',
];

// resolution передаём только если модель его поддерживает
if (!empty($model['resolutions'])) {
    $fields['resolution'] = end($model['resolutions']);
}

// 2. Ставим задачу
$task = apiRequest("{$base}/aiimages?key={$key}", $fields);

if (empty($task['report_id'])) {
    exit('Ошибка: ' . json_encode($task, JSON_UNESCAPED_UNICODE));
}

// 3. Ждём результат
do {
    sleep(10);
    $result = apiRequest("{$base}/aiimages?key={$key}&report_id={$task['report_id']}");
} while (($result['code'] ?? null) === 50);

print_r($result['response']['data']);

Python

import time
import requests

KEY = '{ключ-api}'
BASE = 'https://tools.pixelplus.ru/api'

catalog = requests.get(f'{BASE}/aiimages', params={'key': KEY, 'models': 1}).json()

# Модель, принимающая референс
model = next(
    (m for m in catalog['models'] if m['supports_image_input']),
    None,
)

task = requests.post(
    f'{BASE}/aiimages',
    params={'key': KEY},
    data={
        'modelName': model['value'] if model else catalog['default'],
        'part': 'chat_bot',
        'request_field': 'Тот же интерьер, но вечернее освещение',
        'image_url': 'https://example.com/reference.png',
    },
).json()

while True:
    result = requests.get(
        f'{BASE}/aiimages',
        params={'key': KEY, 'report_id': task['report_id']},
    ).json()
    if result.get('code') != 50:
        break
    time.sleep(10)

print(result['response']['data'])
print('Списано лимитов:', result['cost'])

Удаление фона и апскейл

# Промпт не нужен, обязателен image_url
curl -X POST 'https://tools.pixelplus.ru/api/aiimages?key={ключ-api}' \
  -d 'part=remove_background' \
  -d 'modelName=stableDiffusion3' \
  -d 'image_url=https://example.com/photo.png'

curl -X POST 'https://tools.pixelplus.ru/api/aiimages?key={ключ-api}' \
  -d 'part=upscale' \
  -d 'modelName=stableDiffusion3' \
  -d 'image_url=https://example.com/photo.png'

Ограничения и рекомендации

• Модель, соотношения сторон и разрешения берите из справочника models=1: списки зависят от тарифа ключа и меняются с релизами инструмента.
• Опрашивайте результат не чаще одного раза в 5 секунд — генерация занимает от десятков секунд до нескольких минут.
• Не больше 5 одновременно выполняющихся задач на пользователя.
• Загрузка файла изображения через API не поддерживается — передавайте публичную ссылку в image_url; ресурс проверяется запросом на доступность.
• Промпт автоматически переводится на английский для моделей с supports_native_lang=false — пишите его так, чтобы перевод не терял смысл.
• Готовый результат хранится в истории инструмента: один и тот же report_id можно запрашивать сколько угодно раз бесплатно.
• Ссылки на сгенерированные изображения не вечны — скачивайте файлы сразу после получения результата.