Постановка генерации
POST /v1/models/{model} — поставить генерацию и интерактивно отправить запрос.
Поставьте генерацию изображения или видео. Заполните параметры ниже и отправьте запрос со своим ключом.
Песочница
API-ключ в заголовке Authorization со схемой Bearer:
Authorization: Bearer clipia_live_xxxxxxxxxxxxxxxxxxxxxxПередавайте полную строку, включая префикс схемы Bearer и пробел.
Также принимаются Authorization: Key <ключ> и заголовок
X-Api-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" }'{
"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
}{
"error": {
"type": "invalid_request_error",
"code": "invalid_api_key",
"message": "API-ключ отсутствует, неверный или отозван."
}
}{
"error": {
"type": "billing_error",
"code": "insufficient_credits",
"message": "Недостаточно кредитов для генерации. Пополните баланс."
}
}{
"error": {
"type": "invalid_request_error",
"code": "insufficient_scope",
"message": "У ключа нет scope `generate`."
}
}{
"error": {
"type": "invalid_request_error",
"code": "model_input_invalid",
"message": "Параметр `resolution` не поддерживается этой моделью."
}
}{
"error": {
"type": "invalid_request_error",
"code": "rate_limit_exceeded",
"message": "Превышен лимит запросов. Повторите позже."
}
}POST /v1/models/:model ставит генерацию в очередь и сразу возвращает request_id со ссылками на статус и результат, а также стоимость операции в кредитах. Для создания генерации нужен scope generate.
/v1/models/:modelЗапрос
Path-параметр
Prop
Type
Заголовки
Prop
Type
Тело
Prop
Type
Распространённые ключи внутри input: prompt, image_url, image_urls, aspect_ratio, duration, resolution.
Пример
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! });
// Idempotency-Key (UUID v4) добавляется автоматически.
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"])
# Idempotency-Key (UUID v4) добавляется автоматически.
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)Ответ 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
}Поля ответа
Prop
Type
cost— фиксированная стоимость операции в кредитах, известная заранее. Резервируется приsubmit, окончательно списывается при успехе; при фейле возвращается полностью.- При нехватке кредитов запрос вернёт
402 insufficient_credits.
Идемпотентность
Передайте Idempotency-Key (UUID v4), чтобы безопасно повторять POST при сетевых сбоях. Тот же ключ с теми же параметрами вернёт тот же request_id без повторного списания (срок хранения — 24 часа). Тот же ключ с другими параметрами вернёт 409.
Оценка стоимости
Чтобы узнать цену до постановки в очередь, используйте POST /v1/models/:model/estimate. Он принимает тот же input и возвращает стоимость в кредитах без списания и без запуска генерации.
/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(`генерация обойдётся в ${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
}