Начало работы с Creative API (важно)

Добро пожаловать в Creative API. Здесь собрано главное, что нужно знать перед подключением: модели, цены, ключи, порядок запросов, лимиты и поддержка.

Прочитайте страницу целиком до выхода в продакшен: она короткая и экономит время на ошибках.

1. Модели и каталог

Все модели — в каталоге на сайте: Модели.

• Новые модели добавляются в каталог и в эту документацию, как только они стабильно работают.
• На странице модели — описание, параметры, цена, примеры результатов и доля успешных задач за 24 часа.
• В документации у каждой модели своя страница с параметрами запроса и примерами кода: меню слева, разделы по типам.

2. Цены

Полный и актуальный список цен: Цены.

• Цены — в рублях, их видно до запроса. Те же цены отдаёт список моделей через API.
• Подписки нет: деньги списываются только за выполненные задачи. Пополнение — в кабинете: 500, 2 000, 5 000 или 10 000 ₽.
• При создании задачи её цена резервируется на балансе. Если генерация не удалась, резерв возвращается полностью.
• Чтобы задача не стоила дороже ожидаемого, передайте maxPrice — предел цены в рублях.

3. Создание и защита ключа API

Ключ создаётся в кабинете, раздел «API-ключи», и показывается один раз. Мы храним только его хеш и восстановить ключ не можем: если он потерян, создайте новый.

• На аккаунт — до 10 активных ключей. Удобно держать отдельный ключ на каждое приложение и окружение.
• Ключ можно ограничить: срок действия (1, 7, 30, 90 дней или бессрочно), белый список IP (до 10 адресов IPv4 / IPv6 или подсетей CIDR), список моделей и лимит трат за всё время ключа в рублях. Изменения и отзыв действуют в течение 5 секунд.
• Ключ даёт доступ к балансу: не публикуйте его в браузерном коде и репозиториях. Если ключ утёк — отзовите его в кабинете и создайте новый.

4. Обязательные заголовки

Каждый запрос несёт ключ:

Authorization: Bearer YOUR_API_KEY

Запросы POST с телом JSON — ещё и тип:

Content-Type: application/json

Необязательный Idempotency-Key (1–255 символов, например UUID) защищает от двойной оплаты при повторе: тот же ключ с тем же телом вернёт тот же taskId. Тот же ключ с другим телом — ошибка 422. Ключ помнится не меньше 7 дней.

Ответы /api/v1/* приходят с HTTP 200, итог — в поле code тела. Языковые модели (/creative/v1/*) отвечают в формате OpenAI с настоящим HTTP-статусом. Все коды — Коды ошибок.

5. Логи и детали задачи

• В кабинете, раздел «Логи», — каждая задача: модель, ключ, статус, цена, превью результата и параметры. Фильтры по статусу, модели, ключу и ID; callback можно отправить повторно.
• Через API детали задачи отдаёт Статус задачи: состояние, ссылки на результат, код ошибки и списанная сумма.

6. Хранение данных

Скачайте результаты к себе, если они нужны дольше.

7. Асинхронная модель задач

Изображения, видео и музыка создаются задачами:

1. POST /api/v1/jobs/createTask — модель и её параметры в поле input. В ответ сразу приходит taskId, цена резервируется.

curl -X POST "https://api.cr-api.ru/api/v1/jobs/createTask" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "seedream/5-pro-text-to-image",
  "input": {
    "prompt": "A red fox sitting in fresh snow, morning light, photorealistic",
    "aspect_ratio": "1:1",
    "quality": "basic"
  }
}'

const res = await fetch("https://api.cr-api.ru/api/v1/jobs/createTask", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "seedream/5-pro-text-to-image",
    "input": {
      "prompt": "A red fox sitting in fresh snow, morning light, photorealistic",
      "aspect_ratio": "1:1",
      "quality": "basic"
    }
  }),
});
const result = await res.json();
console.log(JSON.stringify(result, null, 2)); // data.taskId — идентификатор задачи

import requests

response = requests.post(
    "https://api.cr-api.ru/api/v1/jobs/createTask",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "model": "seedream/5-pro-text-to-image",
        "input": {
            "prompt": "A red fox sitting in fresh snow, morning light, photorealistic",
            "aspect_ratio": "1:1",
            "quality": "basic",
        },
    },
)
print(response.json())  # data.taskId — идентификатор задачи

2. Результат: передайте callBackUrl — и после завершения мы сами пришлём его POST-запросом (Callback и проверка подписи). Или спрашивайте статус по taskId, пока state не станет success или fail:

curl "https://api.cr-api.ru/api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch("https://api.cr-api.ru/api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
const result = await res.json();
console.log(JSON.stringify(result, null, 2)); // data.state, data.resultJson

import requests

response = requests.get(
    "https://api.cr-api.ru/api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())  # data.state, data.resultJson

3. Ссылки на файлы — в resultJson.resultUrls, списанная сумма — в creditsConsumed.

Задача должна завершиться за 3 часа, иначе она закрывается с ошибкой и резерв возвращается. Языковые модели работают без задач — запрос и ответ в формате OpenAI, см. раздел «Чат-модели».

8. Лимиты и параллельность

• 20 новых запросов (задачи и запросы к языковым моделям) за 10 секунд на аккаунт.
• Не больше 100 незавершённых задач одновременно.
• Сверх лимита — code 429 и заголовок Retry-After: запрос не ставится в очередь, повторите его позже.
• Чтение статуса не входит в лимит 20 запросов, но ограничено отдельно: 50 запросов в секунду на аккаунт. Спрашивайте статус раз в 3–5 секунд или используйте callback.

9. Поддержка

Если что-то не работает или непонятно, напишите нам — приложите taskId и время запроса:

• Telegram
• ВКонтакте
• Почта: support@cr-api.ru

10. Стабильность

• Генерацию выполняют внешние модели: часть задач может завершиться ошибкой. Такие задачи не оплачиваются — резерв возвращается. Обрабатывайте state: fail и повторяйте запрос.
• Повторяйте с Idempotency-Key, если не уверены, дошёл ли первый запрос: так вторая задача не создастся.
• Модель на паузе не принимает новые задачи (code 455). Доля успешных задач за 24 часа видна на странице модели в каталоге.
• Callback доставляется «хотя бы один раз» с повторами в течение 24 часов: отличайте повтор по data.taskId.