Документация Corporate API

REST API работает асинхронно. Базовый URL: https://corp.aitale.ru/api/v1. Создайте ключ в личном кабинете и передавайте его только в Bearer-заголовке. Машиночитаемая спецификация: OpenAPI 3.1 JSON.

Быстрый старт

1. Загрузите референс

curl -X POST https://corp.aitale.ru/api/v1/files \
  -H "Authorization: Bearer $AITALE_CORP_KEY" \
  -F "file=@reference.jpg"

Используется только multipart/form-data. Один запрос загружает один JPG, PNG или WEBP до 8 МиБ (8 388 608 байт). Для одной генерации можно указать до пяти upload_id. Base64 и внешние URL не принимаются. Upload хранится 12 часов.

2. Создайте задание

curl -X POST https://corp.aitale.ru/api/v1/images/generations \
  -H "Authorization: Bearer $AITALE_CORP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8472-image-1" \
  -H "X-Request-Id: my-trace-8472" \
  -d '{
    "model": "nano-banana-2",
    "quality": "2k",
    "aspect_ratio": "4:5",
    "prompt": "Создай рекламный портрет продукта",
    "upload_ids": ["UUID_FROM_UPLOAD"]
  }'

Заголовок Idempotency-Key обязателен. Повтор с тем же ключом и телом возвращает исходное задание; тот же ключ с другими параметрами дает 409 idempotency_conflict.

{
  "data": {
    "id": "f01d6d17-...",
    "object": "image_generation",
    "status": "queued",
    "model": "nano-banana-2",
    "quality": "2K",
    "cost_tokens": "4.00",
    "result": null,
    "error": null
  }
}

3. Опрашивайте статус

curl https://corp.aitale.ru/api/v1/images/generations/f01d6d17-... \
  -H "Authorization: Bearer $AITALE_CORP_KEY"

Соблюдайте Retry-After (обычно 2 секунды). После succeeded скачайте URL из result.url с тем же Bearer-ключом. Результат удаляется через 12 часов.

Статусы

HTTP-коды, ошибки и fallback

Полный пример на Python

import os, time, uuid, requests

BASE = "https://corp.aitale.ru/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['AITALE_CORP_KEY']}"}

with open("reference.jpg", "rb") as image:
    uploaded = requests.post(
        f"{BASE}/files", headers=HEADERS,
        files={"file": ("reference.jpg", image, "image/jpeg")}, timeout=30,
    ).json()["data"]

response = requests.post(
    f"{BASE}/images/generations",
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json={
        "model": "nano-banana-pro", "quality": "4k",
        "aspect_ratio": "1:1", "prompt": "Product photo",
        "upload_ids": [uploaded["id"]],
    }, timeout=15,
)
if response.status_code == 503:
    use_your_fallback(response.json())
response.raise_for_status()
job = response.json()["data"]

while job["status"] in ("queued", "processing"):
    time.sleep(int(response.headers.get("Retry-After", "2")))
    response = requests.get(f"{BASE}/images/generations/{job['id']}", headers=HEADERS, timeout=15)
    response.raise_for_status()
    job = response.json()["data"]

if job["status"] == "succeeded":
    content = requests.get(job["result"]["url"], headers=HEADERS, timeout=60)
    content.raise_for_status()
    open("result.png", "wb").write(content.content)
else:
    use_your_fallback(job["error"])

Лимиты и дополнительные методы

Базовый лимит — 300 API-запросов в минуту на ключ; создание заданий и загрузка файлов дополнительно ограничены 60 запросами в минуту на каждый тип. JSON создания задания — до 64 КиБ. При 429 соблюдайте Retry-After. Лимиты могут снижаться для защиты сервиса.

GET /models возвращает модели и текущие цены. GET /balance — общий, зарезервированный и доступный баланс. X-Request-Id из ответа сохраните для обращения в поддержку. Не передавайте API-ключ в query string и не публикуйте его в frontend-коде.