API: задачи Грифеля из ваших программ

По ключу запускаются «Карточка товара», «Фото на чистом фоне» и «Просто картинка» — из вашей программы, таблицы или сервиса автоматизации. Ключ выдаётся на платном тарифе; запуски идут за те же ⚡ и по тем же ценам, что на сайте.

Как начать

1. Выпишите ключ в разделе «API» на странице «Аккаунт». Действующих ключей — до 5; сам ключ показывается один раз, у нас хранится только его отпечаток.
2. Передавайте его в каждом запросе заголовком Authorization: Bearer grf_…
3. Запустите задачу и опрашивайте её состояние раз в несколько секунд, пока не станет done или failed.

Адреса

Корень — https://grifel24.ru/api/v1. Ответы — JSON, кроме самого файла.

Пример: карточка из снимка

Загрузить снимок, запустить задачу, дождаться, скачать.

# 1. Снимок товара
curl -X POST https://grifel24.ru/api/v1/uploads \
  -H "Authorization: Bearer $GRIFEL_KEY" \
  -F "file=@termos.jpg"
# → {"id":"<upload>","width":1200,"height":1600,"bytes":345120}

# 2. Запуск
curl -X POST https://grifel24.ru/api/v1/runs \
  -H "Authorization: Bearer $GRIFEL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{"task":"marketplace","params":{"photo":"<upload>","product":"Термос стальной 500 мл"}}'
# → {"runs":[{"id":"<run>","status":"waiting","url":"https://grifel24.ru/api/v1/runs/<run>"}],"spentZap":12,"photos":1,"variants":1}

# 3. Состояние — раз в несколько секунд
curl https://grifel24.ru/api/v1/runs/<run> -H "Authorization: Bearer $GRIFEL_KEY"
# → {"id":"<run>","status":"done","spentZap":12,"files":[{"id":"<file>","url":"https://grifel24.ru/api/v1/files/<file>","mimeType":"image/png","width":1536,"height":2048}]}

# 4. Файл
curl -L https://grifel24.ru/api/v1/files/<file> -H "Authorization: Bearer $GRIFEL_KEY" -o kartochka.png

Числа в примере условные, кроме цены: 12 ⚡ — столько сейчас стоит карточка по фото с настройками по умолчанию. Точная сумма каждого запуска — в поле spentZap ответа.

Задачи и их поля

Сейчас по ключу открыты 3 задачи. Поля — те же, что в форме на сайте; полный перечень с вариантами отдаёт GET /api/v1/tasks. Поля задачи передаются внутри «params», файл — идентификатором загрузки.

* — обязательное. Помимо полей задачи запрос принимает quality, model, variants, outputFormat и notes (уточнения к генерации).

Деньги

• Цена запуска — та же, что на кнопке формы: считает её одна и та же функция. ⚡ списываются до запуска, сумма — в поле spentZap ответа; не хватает — ответ 402, и ничего не списано.
• Запуск сорвался — по нашей вине или вине нейросети — ⚡ возвращаются сами, состояние станет failed с полем refundedZap.
• Заголовок Idempotency-Key делает повтор запроса безопасным: с тем же значением запуск и списание будут одни, а повтор получит тот же ответ. Ответ помнится 24 часа. Без заголовка каждый запрос — новый запуск.

Ошибки

Вид один: {"error":{"code":"…","message":"…"}} — code для программы, message по-русски для человека.

Пределы

Запусков — до 60 в час, загрузок — до 60 в час: столько же, сколько на сайте, и считаются они вместе с ним. Всех запросов по ключу — до 6000 в час: хватает, чтобы опрашивать состояние десятка работ раз в несколько секунд. Сверх предела — ответ 429 с заголовком Retry-After.

Чего в API нет

• Видео, вектора и редактора: по ключу — только задачи из списка выше.
• Уведомлений о готовности (вебхуков): состояние запуска опрашивают.
• Загрузки по ссылке: файл передаётся телом запроса.
• Вызовов из браузера с чужой страницы: заголовков CORS нет намеренно — ключ в коде страницы видит каждый её посетитель.

Ключ — это пароль

Ключ тратит ваши ⚡, но в кабинет не пускает: оплата, пароль и удаление аккаунта по ключу недоступны. Отозвать ключ можно в «Аккаунте»; «Выйти на всех устройствах» и смена пароля отзывают все ключи разом. Ключей у одного аккаунта — до 5: удобно держать свой на каждую интеграцию и отзывать по одному.

Вопросы и то, чего не хватает, — в поддержку: API первый шаг, и следующий мы выбираем по просьбам.