Быстрый старт
Запустите первую генерацию изображения через Clipia API за четыре шага — от получения ключа до готового результата.
Чтобы сгенерировать первое изображение через Clipia API, выполните четыре шага: получите API-ключ в личном кабинете, отправьте генерацию через POST /v1/models/{model}, дождитесь завершения (через вебхук или опрос статуса) и заберите готовый результат. Базовый URL — https://api.clipia.ai, все запросы асинхронные (очередь).
Получите API-ключ
Создайте ключ в личном кабинете clipia.ai: раздел Консоль разработчика (/developer) → вкладка API-ключи → Создать ключ. Полный ключ показывается один раз — сохраните его сразу в надёжном месте.
export CLIPIA_KEY=clipia_live_xxxxxxxxxxxxxxxxxxxxxxКлюч — это серверный секрет
Не размещайте ключ в браузере, мобильных приложениях или публичных репозиториях. Используйте его только из защищённого серверного окружения.
Поставьте генерацию
Отправьте POST /v1/models/{model} с телом input. Slug модели берите из GET /v1/models. Заголовок Idempotency-Key (UUID v4) делает повторные отправки при сетевых сбоях безопасными.
curl -X POST https://api.clipia.ai/v1/models/nano-banana-2 \
-H "Authorization: Bearer $CLIPIA_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 8f3a1c7e-2b41-4d2a-9c0e-1200304cf45b" \
-d '{
"input": { "prompt": "a sunset over mountains, cinematic" },
"webhook_url": "https://your-server.com/clipia/webhook"
}'import { Clipia } from "clipia-ai";
const clipia = new Clipia({ apiKey: process.env.CLIPIA_KEY });
const request = await clipia.models.submit("nano-banana-2", {
input: { prompt: "a sunset over mountains, cinematic" },
webhookUrl: "https://your-server.com/clipia/webhook",
});
console.log(request.requestId, request.status);import os
from clipia import Clipia
clipia = Clipia(api_key=os.environ["CLIPIA_API_KEY"])
request = clipia.models.submit(
"nano-banana-2",
input={"prompt": "a sunset over mountains, cinematic"},
webhook_url="https://your-server.com/clipia/webhook",
)
print(request.request_id, request.status)Ответ содержит request_id и ссылки для опроса:
{
"request_id": "764cabcf-b745-4b3e-ae38-1200304cf45b",
"status": "IN_QUEUE",
"queue_position": 0,
"status_url": "https://api.clipia.ai/v1/requests/764cabcf-.../status",
"response_url": "https://api.clipia.ai/v1/requests/764cabcf-...",
"cost": 12
}Поле cost — фиксированная цена операции в кредитах, известная заранее. Кредиты резервируются при отправке и окончательно списываются только при успехе; при ошибке возвращаются полностью.
Дождитесь завершения
Есть два способа узнать, что генерация готова.
Вариант A — вебхук (рекомендуется). Если при отправке передан webhook_url, Clipia сам пришлёт POST на ваш сервер по завершении — опрашивать ничего не нужно. Доставка подписана HMAC-SHA256.
Вариант B — опрос статуса. Периодически запрашивайте status_url:
curl https://api.clipia.ai/v1/requests/764cabcf-.../status \
-H "Authorization: Bearer $CLIPIA_KEY"const result = await clipia.requests.wait(request.requestId);
console.log(result.status); // "COMPLETED"result = clipia.requests.wait(request.request_id)
print(result.status) # "COMPLETED"{ "request_id": "764cabcf-...", "status": "IN_PROGRESS", "progress": 45 }| Статус | Что значит |
|---|---|
IN_QUEUE | в очереди |
IN_PROGRESS | выполняется (progress 0–100) |
COMPLETED | готово — забирайте результат |
FAILED | ошибка, кредиты возвращены |
CANCELED | отменено вне публичного API (терминальный статус) |
Заберите результат
Когда status == COMPLETED, запросите результат через response_url:
curl https://api.clipia.ai/v1/requests/764cabcf-... \
-H "Authorization: Bearer $CLIPIA_KEY"{
"request_id": "764cabcf-...",
"status": "COMPLETED",
"model": "nano-banana-2",
"output": {
"images": [
{ "url": "https://media.clipia.ai/works/....png", "width": 1024, "height": 1024 }
]
},
"cost": 12,
"created_at": "2026-06-01T12:00:00Z",
"completed_at": "2026-06-01T12:00:18Z"
}Для видео-моделей output содержит video: { url, width, height, duration }. Все медиа-URL ведут на CDN media.clipia.ai.
Дальше
Хотите проверить интеграцию без списания кредитов? Используйте тестовый ключ clipia_test_* — см. страницу «Тестовый режим». Перед боевым запуском пройдитесь по разделу «Рекомендации».