Постановка генерации

POST /v1/models/{model} — поставить генерацию и интерактивно отправить запрос.

Поставьте генерацию изображения или видео. Заполните параметры ниже и отправьте запрос со своим ключом.

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 ставит генерацию в очередь и сразу возвращает request_id со ссылками на статус и результат, а также стоимость операции в кредитах. Для создания генерации нужен scope generate.

POST/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 и возвращает стоимость в кредитах без списания и без запуска генерации.

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(`генерация обойдётся в ${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
}

Поставьте генерацию изображения или видео. Заполните параметры ниже и отправьте запрос со своим ключом.

Песочница

Authorization

Authorization<token>

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

Authorization: Key clipia_live_xxxxxxxxxxxxxxxxxxxxxx

In: header

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

Запрос

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.

Идемпотентность

Оценка стоимости

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(`генерация обойдётся в ${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

Постановка генерации

200

401

402

403

422

429

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

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

Example invalidApiKey

Example insufficientCredits

Example insufficientScope

Example modelInputInvalid

Example rateLimited