Submit a generation
POST /v1/models/{model} — enqueue a generation and send the request interactively.
Enqueue an image or video generation. Fill in the parameters below and send the request with your key.
Playground
API-ключ в заголовке Authorization со схемой Key:
Authorization: Key clipia_live_xxxxxxxxxxxxxxxxxxxxxxПередавайте полную строку, включая префикс схемы Key и пробел.
Ключ создаётся в личном кабинете (Настройки → API-ключи) и показывается
один раз. Формат: clipia_live_… (боевой), clipia_test_… (песочница).
Sandbox / тестовый режим. Ключ с префиксом clipia_test_… работает в
песочнице: submit не списывает кредиты и не запускает реальную
генерацию — он мгновенно возвращает status: COMPLETED с детерминированным
mock-результатом (фиксированный sample-ассет на media.clipia.ai). Поле
cost показывает расчётную стоимость, но она не списывается. Вебхуки
приходят тем же подписанным механизмом (HMAC-SHA256). Режим предназначен
для отладки интеграции до подключения боевого ключа.
In: header
Path Parameters
Slug модели, напр. nano-banana-2, seedance-2-fast-i2v. Список — GET /v1/models.
Header Parameters
UUID v4 для безопасных ретраев POST. Тот же ключ с теми же параметрами
вернёт тот же request_id (без повторного списания). Срок хранения — 24 часа.
Тот же ключ с другими параметрами → 409.
uuidПараметры генерации. Состав зависит от модели — точную схему смотрите в
GET /v1/models/{model} (input_schema). Распространённые ключи:
prompt, image_url, image_urls, aspect_ratio, duration,
resolution.
Empty Object
URL для POST-уведомления о завершении генерации (опционально).
uriResponse Body
curl -X POST "https://api.clipia.ai/v1/models/nano-banana-2" \ -H "Idempotency-Key: 8f3a1c7e-2b4d-4e6f-9a01-23456789abcd" \ -H "Content-Type: application/json" \ -d '{ "input": { "prompt": "a sunset over mountains, cinematic", "aspect_ratio": "16:9" }, "webhook_url": "https://your-server.com/clipia/webhook" }'POST /v1/models/:model enqueues a generation and instantly returns a request_id with links to its status and result, plus the operation cost in credits. Creating a generation requires the generate scope.
/v1/models/:modelRequest
Path parameter
Prop
Type
Headers
Prop
Type
Body
Prop
Type
Common keys inside input: prompt, image_url, image_urls, aspect_ratio, duration, resolution.
Example
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-2b4d-4e6f-9a01-23456789abcd" \
-d '{
"input": {
"prompt": "a sunset over mountains, cinematic",
"aspect_ratio": "16:9"
},
"webhook_url": "https://your-server.com/clipia/webhook"
}'import { createClient } from 'clipia-ai';
const clipia = createClient({ apiKey: process.env.CLIPIA_KEY! });
// An Idempotency-Key (UUID v4) is attached automatically.
const job = await clipia.queue.submit('nano-banana-2', {
input: { prompt: 'a sunset over mountains, cinematic', aspect_ratio: '16:9' },
webhookUrl: 'https://your-server.com/clipia/webhook',
});
console.log(job.request_id, job.cost);import os
from clipia import Clipia
client = Clipia(api_key=os.environ["CLIPIA_KEY"])
# An Idempotency-Key (UUID v4) is attached automatically.
job = client.submit(
"nano-banana-2",
input={"prompt": "a sunset over mountains, cinematic", "aspect_ratio": "16:9"},
webhook_url="https://your-server.com/clipia/webhook",
)
print(job.request_id, job.cost)Response 200
{
"request_id": "764cabcf-b745-4b3e-ae38-1200304cf45b",
"status": "IN_QUEUE",
"queue_position": 2,
"status_url": "https://api.clipia.ai/v1/requests/764cabcf-b745-4b3e-ae38-1200304cf45b/status",
"response_url": "https://api.clipia.ai/v1/requests/764cabcf-b745-4b3e-ae38-1200304cf45b",
"cost": 12
}Response fields
Prop
Type
costis the fixed operation price in credits, known up front. It is reserved atsubmitand settled on success; on failure it is fully refunded.- If the balance is too low, the request returns
402 insufficient_credits.
Idempotency
Pass an Idempotency-Key (UUID v4) to retry a POST safely after network failures. The same key with the same parameters returns the same request_id with no double charge (kept for 24 hours). The same key with different parameters returns 409.
Cost estimate
To learn the price before enqueueing, use POST /v1/models/:model/estimate. It takes the same input and returns the credit cost without charging or starting a generation.
/v1/models/:model/estimatecurl -X POST https://api.clipia.ai/v1/models/seedance-2-fast-i2v/estimate \
-H "Authorization: Bearer $CLIPIA_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": {
"prompt": "aerial shot over a neon city",
"duration": 8,
"resolution": "1080p"
}
}'const { credits } = await clipia.models.estimate('seedance-2-fast-i2v', {
prompt: 'aerial shot over a neon city',
duration: 8,
resolution: '1080p',
});
console.log(`this will cost ${credits} credits`);est = client.models.estimate(
"seedance-2-fast-i2v",
{"prompt": "aerial shot over a neon city", "duration": 8, "resolution": "1080p"},
)
print(est.credits){
"credits": 40
}