Queue API
Асинхронная очередь: submit ставит задачу и сразу отдаёт request_id. Результат забираете опросом status_url или сразу через вебхук.
Генерация изображений и видео по API: асинхронная очередь, подписанные вебхуки, SDK на TypeScript и Python, CLI и оплата кредитами. Те же модели, что и в приложении.
Production-ready интеграция за пять минут — без сюрпризов в проде.
Асинхронная очередь: submit ставит задачу и сразу отдаёт request_id. Результат забираете опросом status_url или сразу через вебхук.
Официальные клиенты для TypeScript и Python с высокоуровневым subscribe, плюс CLI для скриптов и быстрых проверок.
Тестовый ключ clipia_test_ возвращает фиксированный результат мгновенно — отлаживайте разбор ответа, polling и вебхуки без списания кредитов.
По готовности Clipia шлёт POST с HMAC-SHA256 подписью. Проверяйте подпись на сыром теле — SDK дают готовый хелпер.
Заголовок Idempotency-Key делает повторную отправку безопасной: тот же ключ — тот же request_id, без дублей и двойного списания.
Лимиты по ключу: запросов в минуту и параллельных генераций. Текущее состояние — в заголовках RateLimit-* каждого ответа.
Одна задача text-to-image — тремя способами. Сначала положите ключ в переменную окружения.
export CLIPIA_KEY="clipia_live_xxxxxxxxxxxxxxxxxxxxxx"# Submit a text-to-image job
curl -X POST https://api.clipia.ai/v1/models/nano-banana-2 \
-H "Authorization: Key $CLIPIA_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "input": { "prompt": "a sunset over mountains, cinematic" } }'
# Poll the request until status == COMPLETED, then read the result
curl https://api.clipia.ai/v1/requests/<request_id> \
-H "Authorization: Key $CLIPIA_KEY"SDK по умолчанию генерируют Idempotency-Key (UUID v4) на каждый submit, поэтому повторы безопасны из коробки.
Высокоуровневый subscribe сам ставит задачу в очередь и опрашивает до готового результата.
npm i @clipia/clientpip install clipianpx @clipia/client accountИмена пакетов финальные; публикация в npm и PyPI — на этапе запуска.
Передавайте API-ключ в заголовке Authorization со схемой Key.
Authorization: Key clipia_live_xxxxxxxxxxxxxxxxxxxxxxЭто эквивалент пароля к балансу кредитов. Делайте вызовы только со своего сервера, храните ключ в переменной окружения или менеджере секретов. Не размещайте в браузере, мобильных приложениях или публичных репозиториях.
Боевой ключ показывается один раз при создании. Позже в списке виден только префикс.
Все ошибки приходят в едином JSON-формате. SDK бросают типизированную ошибку с полями .status и .code.
| HTTP | Код | Когда | Ретрай |
|---|---|---|---|
| 400 | invalid_request | Невалидное тело или параметры | Не ретраить |
| 401 | invalid_api_key | Ключ отсутствует, неверный или отозван | Не ретраить |
| 402 | insufficient_credits | Недостаточно кредитов на балансе | Не ретраить |
| 403 | insufficient_scope | У ключа нет нужного scope | Не ретраить |
| 404 | not_found | Неизвестный request_id или модель | Не ретраить |
| 409 | idempotency_key_reuse | Конфликт идемпотентности | Не ретраить |
| 422 | model_input_invalid | Параметры не подходят модели | Не ретраить |
| 429 | rate_limit_exceeded | Превышен лимит запросов | С backoff |
| 5xx | internal_error | Внутренняя ошибка или временная недоступность | С backoff |
Для продакшена передайте webhook_url при submit — Clipia пришлёт результат сразу по готовности.
Каждая доставка подписана HMAC-SHA256 в заголовке X-Clipia-Signature. Проверяйте подпись на сыром теле запроса до JSON-парсинга — SDK дают готовый verify-хелпер.
Ответьте 2xx в течение 10 секунд. При сбое — ретраи с экспоненциальной задержкой. Одно событие может прийти повторно, поэтому обрабатывайте вебхуки идемпотентно по request_id.
Clipia MCP позволяет генерировать изображения и видео прямо из Claude Code, Cursor и любого MCP-клиента. Endpoint: https://api.clipia.ai/mcp, авторизация — API-ключ. Гайд по всем агентам: claude.ai, ChatGPT, Cursor и другие
https://api.clipia.ai/mcpclaude mcp add --transport http clipia https://api.clipia.ai/mcp --header "Authorization: Bearer ВАШ_КЛЮЧ"{
"mcpServers": {
"clipia": {
"url": "https://api.clipia.ai/mcp",
"headers": { "Authorization": "Bearer ВАШ_КЛЮЧ" }
}
}
}| Инструмент | Что делает |
|---|---|
generate_image | Поставить задачу генерации изображения |
generate_video | Поставить задачу генерации видео |
wait_generation | Дождаться завершения генерации |
get_generation | Статус и результат генерации по ID |
list_models | Список доступных моделей и цены в кредитах |
get_model | Параметры и цена конкретной модели |
get_balance | Текущий баланс кредитов |
search_templates | Поиск по библиотеке шаблонов промптов |
Ключи с префиксом clipia_test_ работают в песочнице — мгновенные mock-ответы без списания кредитов.
Ключ создаётся в Настройках → «API-ключи».
Готовы к интеграции — получите ключ. Нужны детали контракта — скачайте полную спецификацию.