# Картинки · Image API — neuraldeep.ru API

> Раздел машиночитаемой справки. Все разделы: https://neuraldeep.ru/llms.txt · всё одним файлом: https://neuraldeep.ru/llms-full.txt

Base URL: `https://api.neuraldeep.ru/v1`
Auth: `Authorization: Bearer $YOUR_KEY`

Генерация и обработка картинок тем же ключом, ручки под `/v1/images/*`. Генерирует и правит модель Qwen-Image на наших GPU в РФ, она понимает русский промпт без перевода. Апскейл, удаление фона, улучшение и аватар идут отдельными операциями.

Своя квота у каждой группы: генерация и правка считаются отдельно от обработки готовых картинок. Остаток видно в `GET /v1/images/quota`. Квота списывается, только когда картинка готова. Задача, которая упала, квоту возвращает.

**Как устроено.** Всё асинхронно, формат свой, не OpenAI. `POST` создаёт задачу и сразу отвечает `{"task_uid": "...", "queue_position": N, "eta_sec": N}`. Дальше опрашиваете `GET /v1/images/tasks/{uid}`, пока `status` не станет `finished` (другие значения: `queued`, `processing`, `failed`). Картинку забираете файлом через `GET /v1/images/tasks/{uid}/result`, пока она не готова, эта ручка отвечает `202` с пустым телом. Ссылок на хранилище наружу не отдаём.

| ручка | вход | квота |
|---|---|---|
| `POST /v1/images/generate` | JSON `{prompt, options}` | генерация |
| `POST /v1/images/edit` | multipart `images[]`, `prompt` | генерация |
| `POST /v1/images/upscale` | multipart `image` | обработка |
| `POST /v1/images/background/remove` | multipart `image` | обработка |
| `POST /v1/images/enhance` | multipart `image` | обработка |
| `POST /v1/images/avatar` | multipart `photo`, `gender`, `style` | обработка |
| `GET /v1/images/queue` | | очередь сейчас |

**Параметры генерации**, поле `options`: `width` и `height` (оба вместе), либо `aspect_ratio` (`1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `square`), `negative_prompt`, `steps`, `true_cfg_scale`, `seed`, `num_images`, `transparent` (прозрачный фон). Без размера рисуется квадрат 1312×1312. У правки те же поля, кроме размера: пропорции берутся с первой картинки.

**Ограничения на вход.**

- Размер результата: не больше 1,5 Мпикс. Запрос крупнее не отклоняется, а уменьшается с сохранением пропорций, стороны округляются вниз до кратных 32. Каждая сторона до 2752 px, иначе `422`.
- `num_images` от 1 до 4, `steps` от 1 до 50, `true_cfg_scale` от 1 до 10, `prompt` до 4000 символов, `negative_prompt` до 2000.
- Правка: до 10 картинок в запросе и до 25 МБ на все файлы вместе.
- Обработка: один файл до 25 МБ и до 4 Мпикс. Форматы PNG, JPEG, WebP.
- Очередь: у одного аккаунта ограничено число задач, которые ждут или рисуются одновременно. Сверх этого придёт `429`, дождитесь своих задач.

```bash
uid=$(curl -s https://api.neuraldeep.ru/v1/images/generate \
  -H "Authorization: Bearer $YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"кот-космонавт, неон","options":{"width":1024,"height":1024}}' | jq -r .task_uid)

curl https://api.neuraldeep.ru/v1/images/tasks/$uid \
  -H "Authorization: Bearer $YOUR_KEY"

curl https://api.neuraldeep.ru/v1/images/tasks/$uid/result \
  -H "Authorization: Bearer $YOUR_KEY" -o out.png
```

```bash
# правка словами, до 10 исходных картинок
curl https://api.neuraldeep.ru/v1/images/edit \
  -H "Authorization: Bearer $YOUR_KEY" \
  -F "images[]=@photo.jpg" -F "prompt=замени фон на морской берег"

# апскейл готовой картинки
curl https://api.neuraldeep.ru/v1/images/upscale \
  -H "Authorization: Bearer $YOUR_KEY" -F "image=@photo.jpg"
```

```python
import time, httpx

H = {"Authorization": "Bearer $YOUR_KEY"}
job = httpx.post(
    "https://api.neuraldeep.ru/v1/images/generate",
    headers=H, json={"prompt": "космический кот в неоне", "options": {"aspect_ratio": "1:1"}},
).json()
uid = job["task_uid"]

# в очереди бывает несколько задач, держите таймаут на поллинге
for _ in range(300):
    st = httpx.get(f"https://api.neuraldeep.ru/v1/images/tasks/{uid}", headers=H).json()
    if st["status"] in ("finished", "failed"):
        break
    time.sleep(2)

img = httpx.get(f"https://api.neuraldeep.ru/v1/images/tasks/{uid}/result", headers=H).content
open("out.png", "wb").write(img)
```

**Ошибки.**

- `400`: пустой промпт.
- `402`: на кошельке не хватает денег для операции.
- `404`: результат устарел или нет картинки с таким номером.
- `413`: файл больше предела.
- `422`: параметр вне границ, неизвестный `aspect_ratio`, больше 10 картинок в правке, файл не картинка.
- `429`: кончилась квота (тело `quota_exceeded`, см. [начало](https://neuraldeep.ru/docs/start.md)) или слишком много ваших задач в очереди.
- `503`: генерация или обработка временно недоступны, повторите позже.