Ключевые факты

• done Один GET-запрос → изображение: POST не нужен, тело запроса не нужно.
• done 6 стилей: realistic, illustration, 3d, pixel-art, cyberpunk, anime.
• done CDN-кеш 1 год: SHA256-хеш URL → immutable cache.
• done 500 символов: максимальная длина промпта (обрезается).
• done Seed диапазон: 1–2 147 483 647 → для воспроизводимых результатов.
• done 5 форматов ответа HTTP: 302 (hit), 200 (miss), 400, 401, 429.
• done Rate limit: Free: 5 req/min; Business: 600 req/min.

Что такое URL API?

URL API (URL-based API) — это интерфейс, где все параметры запроса передаются непосредственно в URL-строке, а сервер возвращает готовый ресурс по HTTP GET-запросу. В отличие от стандартного REST API (POST → async job → polling → download), наш URL API можно вставить прямо в HTML, и всю сложную асинхронную работу под капотом выполнит наш сервер. Идеально для статических сайтов (Hugo, Next.js), мета-тегов og:image и email-рассылок.

Как работает запрос (Архитектура)

Path Parameters (обязательные)

Параметры пути передаются непосредственно в структуре URL до знака вопроса ?. Порядок строгий: /{width}x{height}/{background_hex}/{foreground_hex}.

Примечание: Значения размеров вне диапазона «зажимаются» (clamped) без ошибки. Параметры цвета (bg/fg) — это визуальная подсказка для нейросети, а не жесткое правило.

Query Parameters (опциональные)

1. prompt — Текстовое описание

Обязательный параметр (в строке запроса или в slug-пути). Максимум 500 символов (обрезается без ошибки).

• Поведение: Если промпт короткий (1-3 слова), AI автоматически добавляет дескрипторы для улучшения качества. Русский язык (Kandinsky 3.1) поддерживается нативно.
• Кодирование: Обязательно используйте URL-encode (пробелы = %20 или +).

2. style — Художественный стиль

3. seed — Фиксация результата

Тип: integer (1–2 147 483 647). Если не передан — при каждом новом запросе (cache-miss) генерируется уникальное изображение. Если передан — комбинация «тот же prompt + тот же seed» всегда возвращает одну и ту же картинку. Незаменимо для og:image.

function pixinlink_seed(string $slug): int {
    return abs(crc32($slug)) % 2147483647;
}

function getSeed(slug) {
  let hash = 0;
  for (let i=0; i<slug.length; i++) {
    hash = ((hash << 5) - hash) + slug.charCodeAt(i);
  }
  return Math.abs(hash) % 2147483647 || 1;
}

4. format — Формат вывода

// Пример payload на ваш callback URL
{
  "job_id": "job_abc123",
  "status": "done",
  "url": "https://cdn.pixinlink.ru/images/ab/cd/ef123.webp",
  "prompt": "офис разработчиков"
}

Аутентификация

API поддерживает две схемы работы: анонимную (Free-тариф) и авторизованную (Starter+). Для авторизации используется стандартный заголовок Authorization: Bearer.

GET https://pixinlink.ru/800x400/офис
Authorization: Bearer pk_live_вашключ

Коды ответов HTTP

API использует стандартные HTTP-коды. При успешном попадании в кэш возвращается 302 Found, при промахе — 200 OK с временным SVG (и запускается фоновая генерация).

Пример тела ответа (400 Bad Request):

{
  "error": "invalid_parameter",
  "detail": "width must be between 16 and 8192",
  "field": "width"
}

Rate Limits и квоты

Cache hit (302) не считается генерацией — квота не расходуется. Списание происходит только при Cache miss (200).

Полный пример API-запроса

GET https://pixinlink.ru/1200x630/ffffff/000000
?prompt=современный%20офис%20разработчиков%20вечер
&style=realistic
&seed=20260515
&format=webp
&watermark=false
&callback=https%3A%2F%2Fmysite.ru%2Fhook
Authorization: Bearer pk_live_вашключздесь