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

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

1. Зарегистрируйтесь и войдите в профиль, откройте «Для разработчиков» → «Ключи API и баланс» и создайте ключ. Ключ показывается один раз.
2. Проверьте источник оплаты генерации: сначала расходуется квота тарифа, затем общий баланс. Подключение, ключи и служебные запросы бесплатны; при «Бесплатном доступе» (гранте) бесплатны и генерации.
3. Загрузите файл, создайте заказ, дождитесь статуса completed и скачайте результат.

# 1. загрузка файла (тело запроса — сам файл)
curl -X POST "https://anycon.online/api/public/v1/uploads?file_name=photo.jpg" \
  -H "Authorization: Bearer $ANYCON_API_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg

# 2. заказ (Idempotency-Key обязателен)
curl -X POST "https://anycon.online/api/public/v1/orders" \
  -H "Authorization: Bearer $ANYCON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"upload_id":"<upload_id>","copies":2,"options":{"mode":"clean"}}'

# 3. статус
curl "https://anycon.online/api/public/v1/orders/<order_id>" -H "Authorization: Bearer $ANYCON_API_KEY"

# 4. результат: список файлов с временными ссылками
curl "https://anycon.online/api/public/v1/orders/<order_id>/results" -H "Authorization: Bearer $ANYCON_API_KEY"

Авторизация и ключи

Каждый запрос содержит заголовок Authorization: Bearer uk_live_<префикс>_<секрет>. Ключ создаётся в разделе «Профиль → Для разработчиков → Ключи API и баланс» (нужно повторно ввести пароль). До пяти действующих ключей на аккаунт. Мы храним только необратимую подпись ключа: потерянный ключ восстановить нельзя — отзовите его и создайте новый.

• Ключ даёт доступ только к вашим данным и вашему балансу. Не храните его в публичном коде и мобильных приложениях.
• Отозванный ключ перестаёт работать сразу. Ключи заблокированного аккаунта не работают.
• Браузерные запросы с другого сайта (CORS) не разрешены: вызывайте API с вашего сервера.

Квота, общий баланс и оплата

Подключение, ключи и служебные запросы API бесплатны, отдельный баланс API не создаётся. Оплачивается только генерация: сначала расходуется квота действующего тарифа, а после её исчерпания — общий баланс аккаунта. При «Бесплатном доступе» (гранте) генерации бесплатны. Баланс пополняется в кабинете в рублях через ЮKassa; деньги зачисляются после подтверждения платежа. Все суммы в API — целое число копеек в строке ("11000" = 110 ₽).

curl "https://anycon.online/api/public/v1/balance" -H "Authorization: Bearer $ANYCON_API_KEY"
# {"balance_minor":"89000","currency":"RUB"}

curl "https://anycon.online/api/public/v1/pricing" -H "Authorization: Bearer $ANYCON_API_KEY"

curl -X POST "https://anycon.online/api/public/v1/quote" \
  -H "Authorization: Bearer $ANYCON_API_KEY" -H "Content-Type: application/json" \
  -d '{"media_kind":"video","duration_seconds":61,"copies":2}'
# {"amount_minor":"41000","currency":"RUB"}

Если доступные генерации использованы и средств на общем балансе не хватает, заказ не создаётся: ответ 402 с кодом E_INSUFFICIENT_FUNDS. Пополните баланс и повторите запрос с тем же Idempotency-Key.

Методы

Параметры заказа (options)

Режим "mode":"version" принимает группы: variation — geometry, color, audio, overlay (невидимые полупрозрачные элементы поверх изображения, фото и видео), pulse (Динамичное изменение кадра (изменение геометрии), только видео, по умолчанию в API выключено: случайные плавные сегменты 4–12 с с паузами 0–6 с, амплитуда до 0,3–1,2% с ограничением скорости 0,25%/с и суммарного кадрирования; до восьми сегментов подгоняются под длину ролика, размер и временные метки сохраняются), audioTone (микросдвиг тона и тихий фоновый шум, только видео); encoding — {"randomize": true} (только видео: у каждой копии свои допустимые настройки кодера и упаковки MP4); substitute; video. Для каждой копии значения выбираются случайно в заданных пределах. Цена от этих параметров не зависит. Результат зависит от исходного файла; мы не обещаем, как поведут себя сторонние сервисы с готовыми файлами.

Статусы заказа

queued — в очереди, processing — обрабатывается, completed — готов, failed — ошибка обработки (источник оплаты восстановлен), cancelled — отменён (источник оплаты восстановлен), review — требует проверки поддержкой.

Idempotency-Key

Придумайте уникальный ключ (например, UUID) на каждый заказ и повторяйте его при повторной отправке того же запроса — при обрыве связи, таймауте и т. п. Тот же ключ с тем же телом вернёт тот же заказ (200 и заголовок Idempotent-Replay: true) и не спишет деньги второй раз. Тот же ключ с другим телом — ошибка 409 E_IDEMPOTENCY_CONFLICT. Ключи помнятся 7 суток.

Скачивание результата

В ответе /results у каждого файла есть download_url — временная ссылка (действует около 15 минут, при необходимости запросите список заново). Ссылка не требует заголовка авторизации:

curl -L -o copy-01.jpg "<download_url>"

Готовые файлы хранятся 7 дней после готовности. Размер и SHA-256 каждого файла указаны в ответе — сверяйте их после скачивания.

Возвраты

• Ошибка обработки, превышение срока обработки: использованная генерация возвращается в тариф, а списанная сумма — на общий баланс аккаунта (один раз).
• Отмена через POST /orders/{id}/cancel до начала обработки: источник оплаты восстанавливается. Позже — 409 E_CANCEL_TOO_LATE.
• После того как результат готов, автоматического возврата нет; по вопросам обращайтесь в поддержку.

Лимиты

• Частота: 60 запросов в минуту на ключ. При превышении — 429 E_RATE_LIMITED и заголовок Retry-After (секунды).
• Одновременно в работе — до N заказов по тарифу (N указан в его условиях) и до 5 заказов, оплаченных с баланса: сверх этого 429 E_QUOTA_EXCEEDED (повторите позже).
• Размер файла, длительность видео, разрешение и число копий — как в кабинете (GET /pricing, поле limits).

Ошибки

Ошибка — всегда JSON с кодом и кратким текстом:

{"requestId":"...","error":{"code":"E_INSUFFICIENT_FUNDS","message":"Insufficient balance","retryable":false,
 "details":[{"field":"/balance","issue":"required 11000 kopecks, available 500"}]}}

Уведомления (вебхуки)

Необязательно. Укажите публичный адрес https в разделе «Профиль → Для разработчиков → Ключи API и баланс» — мы отправим POST, когда заказ стал order.completed или order.failed. Адреса внутренних сетей запрещены. При ответе не 2xx доставка повторяется (через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч). Событие может прийти повторно — получатель обязан отсеивать повторы по заголовку X-Anycon-Delivery (он же поле id). События: order.completed, order.failed, order.cancelled (только для оплаченных заказов), order.review. Повторы доставки аккаунтного адреса всегда идут на ТЕКУЩИЙ адрес: смена адреса в кабинете переводит на новый и ожидающие события. Адрес заказа (webhook_url) принимает порты 80 и 443; последний переданный при повторе запроса адрес заменяет прежний, но только для ещё не доставленных событий: если событие уже доставлено (sent), новый адрес его не получит — используйте опрос GET /orders/{id}.

POST https://your.server/anycon-webhook
Content-Type: application/json
X-Anycon-Event: order.completed
X-Anycon-Delivery: <id>
X-Anycon-Signature: t=1760000000,v1=<hex>

{"id":"...","event":"order.completed","created_at":"...","data":{"order":{ ...как в GET /orders/{id}... }}}

Подпись: v1 = HMAC-SHA256(секрет, t + "." + тело_запроса) в шестнадцатеричном виде. Секрет (whsec_…) показывается в кабинете при создании вебхука. Сравнивайте подпись за постоянное время и отклоняйте запросы со слишком старым t.

import hmac, hashlib
def verify(secret: str, header: str, body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    mac = hmac.new(secret.encode(), parts["t"].encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, parts["v1"])