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.

Authorization

Authorization<token>

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

modelstringrequired

Slug модели, напр. nano-banana-2, seedance-2-fast-i2v. Список — GET /v1/models.

Header Parameters

Idempotency-Key?string

UUID v4 для безопасных ретраев POST. Тот же ключ с теми же параметрами вернёт тот же request_id (без повторного списания). Срок хранения — 24 часа. Тот же ключ с другими параметрами → 409.

Formatuuid

Request Body

inputobjectrequired

Параметры генерации. Состав зависит от модели — точную схему смотрите в GET /v1/models/{model} (input_schema). Распространённые ключи: prompt, image_url, image_urls, aspect_ratio, duration, resolution.

Empty Object

webhook_url?string

URL для POST-уведомления о завершении генерации (опционально).

Formaturi

Response 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.

POST/v1/models/:model

Request

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

cost is the fixed operation price in credits, known up front. It is reserved at submit and 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.

POST/v1/models/:model/estimate

curl -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
}

Enqueue an image or video generation. Fill in the parameters below and send the request with your key.

Playground

Authorization

Authorization<token>

API-ключ в заголовке Authorization со схемой Key:

Authorization: Key clipia_live_xxxxxxxxxxxxxxxxxxxxxx

In: header

Path Parameters

modelstringrequired

Slug модели, напр. nano-banana-2, seedance-2-fast-i2v. Список — GET /v1/models.

Header Parameters

Idempotency-Key?string

Formatuuid

Request Body

inputobjectrequired

Empty Object

webhook_url?string

URL для POST-уведомления о завершении генерации (опционально).

Formaturi

Response 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"
  }'

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

Request

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

cost is the fixed operation price in credits, known up front. It is reserved at submit and settled on success; on failure it is fully refunded.
If the balance is too low, the request returns 402 insufficient_credits.

Idempotency

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.

POST/v1/models/:model/estimate

curl -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
}

200

401

402

403

422

429

Поставлено в очередь (боевой ключ)

Песочница (тестовый ключ clipia_test_…) — сразу COMPLETED

Example invalidApiKey

Example insufficientCredits

Example insufficientScope

Example modelInputInvalid

Example rateLimited

Submit a generation

200

401

402

403

422

429

Поставлено в очередь (боевой ключ)

Песочница (тестовый ключ clipia_test_…) — сразу COMPLETED

Example invalidApiKey

Example insufficientCredits

Example insufficientScope

Example modelInputInvalid

Example rateLimited