SDXL API: документация и best practices
SDXL 1.0 — рабочая лошадка production-генерации изображений. Разбираем все параметры API (cfg, steps, sampler), prompt engineering и стоимость.
Обновлено: 2026-05-19
TL;DR
SDXL 1.0 — production-стандарт генерации изображений в 2024–2026. Через API доступен у десятков провайдеров (Stability, Replicate, fal.ai, gpupool, Hostkey, MWS). В этом гайде — общий контракт REST (параметры, schedulers, samplers, LoRA, ControlNet), prompt engineering, оценка стоимости и типичные ошибки.
Что такое SDXL API
SDXL (Stable Diffusion XL) — модель Stability AI на 6.5 GB параметров. Через API она оборачивается в обычный HTTP-эндпоинт с JSON-body:
curl -X POST https://api.example.com/v1/images/generate \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "sdxl-base-1.0",
"prompt": "photo of a red fox in a forest, sunlight, sharp focus",
"width": 1024,
"height": 1024,
"steps": 30,
"cfg": 7.5,
"sampler": "dpmpp_2m",
"scheduler": "karras",
"seed": 12345
}'
Ответ — либо URL результата (managed-API типа Replicate/fal.ai), либо task_id с последующим polling. Формат отличается у каждого провайдера, но смысл одинаковый.
Параметры запроса
prompt и negative_prompt
prompt — описание того, что нужно нарисовать. negative_prompt — чего хочется избежать.
SDXL понимает английский лучше русского. Для русскоязычных задач обычно держат два слоя:
- UI-уровень: пользователь вводит русский запрос.
- Сервер: добавляет prompt-шаблон на английском (через мини-LLM или Set node).
Длина: SDXL технически принимает до 77 токенов на text encoder (на самом деле два — CLIP-G и CLIP-L). Длиннее — токены урезаются. Для длинных промптов используйте «prompt weighting» и (focal: 1.3) синтаксис.
width, height
SDXL обучен на 1024×1024 и стандартных aspect ratio. Лучшие пресеты:
- 1024×1024 (1:1) — квадрат, универсал
- 1152×896 (~4:3) — пейзаж
- 896×1152 (~3:4) — портрет
- 1216×832 (~3:2) — широкий
- 832×1216 (~2:3) — высокий
- 1344×768 (16:9) — wide
- 768×1344 (9:16) — мобайл
Произвольные размеры (например, 1000×1200) работают, но качество хуже. Лучше сгенерить в стандартном размере и потом обрезать.
steps
Количество шагов денойзинга. Стандарт:
- SDXL base: 25-30 (DPM++ 2M Karras)
- SDXL turbo: 4-8 (sgm_uniform scheduler)
- SDXL lightning: 4 steps (lightning-specific scheduler)
- SDXL hyper: 1-8 steps (hyper-specific)
Больше 40 шагов почти никогда не имеет смысла на base. На SDE-семплерах может помочь немного выше (35-50).
cfg (Classifier-Free Guidance scale)
Сила следования промпту. Range 1.0-20.0.
| CFG |
Эффект |
| 1.0-3.0 |
Очень свободно, креативно, иногда «не по теме» |
| 4.0-6.0 |
Баланс, рекомендуется для photo-realistic |
| 7.0-9.0 |
Стандарт, чёткое следование промпту |
| 10.0+ |
Очень буквально, артефакты, «пережатые» цвета |
Default для SDXL: 6.0-7.0. На stylized промптах можно повыше (8-9).
sampler / scheduler
Sampler — алгоритм денойзинга. Scheduler — кривая шагов.
Самые часто используемые:
| Combo |
Шагов |
Качество |
Скорость |
Когда выбирать |
| DPM++ 2M Karras |
25-30 |
Отличное |
Быстро |
Default для production |
| DPM++ 3M SDE Karras |
30-40 |
Топ |
Медленно |
Финальные prod-картинки |
| Euler a |
20-30 |
Хорошо |
Очень быстро |
Превью, batch |
| DDIM |
20-30 |
Среднее |
Быстро |
Когда нужен определённый seed-стиль |
| UniPC |
20 |
Хорошо |
Быстро |
Малое количество шагов |
Если сомневаетесь — берите DPM++ 2M Karras, 30 шагов.
seed
Целое число. Один и тот же seed + prompt + параметры → один и тот же результат (если sampler детерминированный).
Использование:
seed = -1 (или null) — случайный. Дефолт.- Фиксированный seed — для воспроизводимости и LoRA-настройки.
- Возвращайте использованный seed в API-ответе — клиент должен иметь возможность «повторить эту картинку».
LoRA через API
Многие managed-API позволяют подключить LoRA одним из способов:
{
"prompt": "...",
"lora": [
{"name": "product-photo-v3", "weight": 0.8},
{"name": "trigger-style-lora", "weight": 0.4}
]
}
Где LoRA берётся: либо из встроенного каталога API, либо загружается клиентом через отдельный endpoint, либо клонируется из CivitAI URL.
Веса: суммарно держите в районе 1.0-1.5. Больше — модель деградирует. Меньше — эффект LoRA не виден.
Trigger words: для большинства LoRA — это слова, на которые LoRA обучена реагировать. Их нужно вставить в prompt (например, для LoRA «cute anime girl» trigger words могут быть 1girl, anime style).
ControlNet через API
ControlNet даёт точный контроль композиции через reference image. Через API подключается:
{
"prompt": "professional product photo on white background",
"controlnet": [
{
"model": "canny",
"input_image": "https://your.cdn/source.jpg",
"weight": 0.8,
"preprocess": true
}
]
}
preprocess: true — API сам прогонит изображение через canny-edge detector. Если у вас уже готовый control input (preprocessed map), ставьте preprocess: false.
Можно стекать 2-3 ControlNet (depth + openpose, например), но качество начинает деградировать после трёх.
img2img
Та же модель работает и для image-to-image:
{
"prompt": "in cyberpunk style, neon lights",
"init_image": "https://your.cdn/source.jpg",
"denoising_strength": 0.65,
"width": 1024,
"height": 1024
}
denoising_strength (0–1):
- 0.3–0.4 — лёгкая стилизация
- 0.55–0.65 — заметная переработка
- 0.8+ — почти полная регенерация
inpainting
Замена части изображения через маску:
{
"prompt": "wearing a red baseball cap",
"init_image": "https://your.cdn/portrait.jpg",
"mask_image": "https://your.cdn/mask.png",
"denoising_strength": 0.85,
"inpaint_full_res": true
}
Маска: чёрно-белый PNG, белый = область для генерации.
Оценка стоимости
Реалистичные цены на 2026 за одну картинку 1024×1024 SDXL base:
| Провайдер |
Цена за изображение |
| Replicate |
$0.0045–0.0070 |
| fal.ai |
$0.005 |
| gpupool (RU) |
₽1–2 |
| Stability AI (через DreamStudio API) |
$0.012 |
| Self-host RTX 4090 (амортизация) |
₽0.05–0.10 (при 80% утилизации) |
Себестоимость self-host считается только при utilization > 50%. На рваной нагрузке amortized cost пер-картинки растёт в разы.
Производительность
Примерное время одного запроса 1024×1024 30 steps DPM++ 2M Karras:
| GPU |
Без оптимизаций |
С torch.compile + xformers |
| RTX 3090 24GB |
5-7 сек |
3-4 сек |
| RTX 4090 24GB |
2.5-3 сек |
1.5-2 сек |
| A100 40GB |
2.5 сек |
1.5 сек |
| A100 80GB |
2.0 сек |
1.2 сек |
| H100 80GB |
1.2 сек |
0.7 сек |
| L40S |
2.2 сек |
1.3 сек |
Эти числа включают latency через managed-API обычно +100-500 ms (queue + warm-up).
Типичные ошибки
| Код / симптом |
Причина |
Решение |
| HTTP 400 «invalid prompt» |
Слишком длинный prompt или запрещённые токены |
Сократить prompt, проверить terms-blocked-words API |
| HTTP 401 / 403 |
API-ключ не подключён или истёк |
Проверить Credentials, refresh ключ |
| HTTP 429 |
Rate limit |
Уменьшить concurrency, ставить exponential backoff |
safety_filter_triggered |
Safety классификатор API отсек контент |
Переписать prompt, добавить safety_check=false (если поддерживается) |
| Картинка отличается от ожидания |
Сложный prompt, неподходящий sampler/cfg |
Попробовать DPM++ 2M Karras 30 steps, cfg=7.0 |
| Очень медленный ответ |
Cold start или загруженная очередь |
Уточнить SLA провайдера, рассмотреть warm-pool тариф |
| Чёрная или размытая картинка |
Неподходящий scheduler для samplera |
Использовать рекомендованные комбо (DPM++ 2M + Karras) |
Что почитать дальше
Частые вопросы
Какой sampler лучший для SDXL?
DPM++ 2M Karras — универсальный default, отличный баланс качества/скорости. Для maximum quality — DPM++ 3M SDE Karras. Euler a — для быстрого превью.
Сколько шагов (steps) нужно?
SDXL base модель — 25-30 steps хватает. SDXL turbo — 4-8 steps. Lightning — 4 steps. Больше 40 редко имеет смысл.
Что такое CFG scale?
Classifier Free Guidance — сила следования промпту. Низкий (3-5) — более креативно, высокий (8-12) — буквально по промпту. Оптимум для SDXL — 6-8.
Чем отличается SDXL base от refiner?
Base — основная модель генерации. Refiner — мини-модель для финального улучшения деталей. На SDXL 1.0 refiner редко даёт +25% качества, чаще пропускается.