Синхронный запрос — `POST /run`

Один HTTP-запрос, один ответ. Подходит для image-генераций ≤ 30 секунд и любых запросов, где не нужен реалтайм-прогресс.

Локальный таймаут HTTP-клиента должен быть больше 5 минут — иначе соединение оборвётся раньше, чем сервис успеет отдать результат.

Минимальный пример

curl

run.sh


curl -X POST https://api.neuroartist.ru/run/flux/dev \
  -H "Authorization: Bearer na_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  --max-time 320 \
  -d '{
    "prompt": "editorial portrait, monochrome",
    "image_size": "portrait_4_3",
    "num_inference_steps": 28
  }'

JavaScript

generate.ts


const NA_API_KEY = process.env.NA_API_KEY
 
export async function generate(modelId: string, input: object) {
  const resp = await fetch(`https://api.neuroartist.ru/run/${modelId}`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${NA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(input),
    signal: AbortSignal.timeout(320_000)
  })
  const body = await resp.json().catch(() => ({}))
  if (!resp.ok) {
    throw Object.assign(new Error(body.message ?? resp.statusText), {
      error: body.error,
      status: resp.status,
      retryAfter: Number(resp.headers.get('Retry-After')) || undefined
    })
  }
  return body
}
 
const result = await generate('flux/dev', {
  prompt: 'editorial portrait, monochrome',
  image_size: 'portrait_4_3'
})
console.log(result.images[0].url)

Python

generate.py


import os
import requests
 
NA_API_KEY = os.environ["NA_API_KEY"]
 
 
def generate(model_id: str, payload: dict) -> dict:
    resp = requests.post(
        f"https://api.neuroartist.ru/run/{model_id}",
        headers={"Authorization": f"Bearer {NA_API_KEY}"},
        json=payload,
        timeout=320,
    )
    resp.raise_for_status()
    return resp.json()
 
 
result = generate("flux/dev", {
    "prompt": "editorial portrait, monochrome",
    "image_size": "portrait_4_3",
})
print(result["images"][0]["url"])

Ответ:


{
  "images": [
    { "url": "https://s3.cloud.ru/neuroartist/.../result.webp", "width": 768, "height": 1024 }
  ],
  "seed": 12345,
  "timings": { "inference": 4.21 }
}

URL ведёт в наш S3 — живёт пока вы его не удалите.

Параметры

modelId поддерживает слеши — передавайте как есть, flux/dev. URL-кодировать не нужно.

Тело запроса — input модели по её JSON Schema. Получить схему:


curl https://api.neuroartist.ru/models/flux/dev | jq .schema

?passthrough=1 — оригинальные внутренние URL без re-host в наш S3. Используйте только для отладки: ссылки протухают через ~24 часа.

Если за 5 минут не управились

Сервер вернёт 202 Accepted:


{
  "error": "timeout",
  "message": "Generation still in progress. Use GET /queue/{modelId}/requests/{requestId} to poll.",
  "requestId": "req_abc"
}

Это не ошибка — генерация продолжается асинхронно. Подключитесь по requestId:

Polling


curl https://api.neuroartist.ru/queue/flux/dev/requests/req_abc/status \
  -H "Authorization: Bearer na_live_xxxxxxxxxxxxxxxx"

Подробнее — Асинхронная очередь и SSE.

Обработка ошибок

Все ошибки приходят с полем error — стабильный machine-readable код. Ветвите по нему:


try {
  const result = await generate('flux/dev', input)
} catch (e) {
  switch (e.error) {
    case 'insufficient_balance':
      return showTopupModal({ required: e.required })
    case 'rate_limited':
      return retryAfter(e.retryAfter)
    case 'invalid_body':
      return showValidationErrors(e.issues)
    case 'provider_error':
      return retryAfter(e.retryAfter ?? 30)
    default:
      throw e
  }
}

Полный список — Коды ошибок.

Оценка стоимости перед запуском


curl -X POST https://api.neuroartist.ru/models/flux/dev/estimate \
  -H "Authorization: Bearer na_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"…","num_inference_steps":28}'


{ "estimatedCostRub": 8, "priceUnit": "image", "quantity": 1 }

Когда переходить на async

Признак	Решение
Часто > 60 секунд	Асинхронная очередь и SSE
Reverse-proxy режет соединения	Webhook
Хотите параллельные запросы	`/queue`

Дальше

Асинхронная очередь и SSE — для генераций, не помещающихся в HTTP-таймауты.
Каталог моделей — получить JSON Schema перед вызовом.
/run в справочнике — статусы, ошибки и ?passthrough=1.

Синхронный запрос — POST /run