OpenAI-совместимый шлюз текстовых моделей (`/v1/chat/completions`). Доступен, когда у аккаунта включён LLM-шлюз; текстовые модели видны в `GET /v1/models` записями `LlmModelSummary`. Scope `chat` (ключи со scope `generate` его включают).
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/clipia-ai:clipia-ai-llm-api"curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Clipia Ai LLM API
version: v1
contact:
name: Clipia API Support
url: https://clipia.ai
license:
name: Proprietary
url: https://clipia.ai/terms
termsOfService: https://clipia.ai/terms
description: 'Operations tagged LLM across 2 of this provider''s published API definitions: clipia-v1.json, clipia-ai-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.clipia.ai
description: Production
security:
- apiKey: []
tags:
- name: LLM
description: 'OpenAI-совместимый шлюз текстовых моделей (`/v1/chat/completions`).
Доступен, когда у аккаунта включён LLM-шлюз; текстовые модели видны в
`GET /v1/models` записями `LlmModelSummary`. Scope `chat` (ключи со scope
`generate` его включают).'
paths:
/v1/chat/completions:
post:
tags:
- LLM
operationId: createChatCompletion
summary: Chat completion (OpenAI-совместимый)
description: 'Drop-in замена `POST https://api.openai.com/v1/chat/completions`:
`model` — slug из `GET /v1/models` (LLM-записи), `messages` — массив
OpenAI-сообщений, `stream: true` — SSE-поток чанков `chat.completion.chunk`.
Неизвестные верхнеуровневые поля (`route`, `transforms`, `usage`,
`include_reasoning`) игнорируются, не отклоняются.
Оплата — кредитами по ставке модели (`pricing` в `LlmModelSummary`);
фактическое списание конкретного ответа — `GET /v1/generation?id=`.
Ответ содержит `id` вида `chatcmpl-…` и `provider: "Clipia"`.
Ошибки — в OpenAI-конверте `{ "error": { "message", "type", "code" } }`:
`402 insufficient_quota`, `429 rate_limit_error` (+ `Retry-After`),
`404 model_not_found`.
**Sandbox.** С тестовым ключом (`clipia_test_…`) возвращается
детерминированный ответ без обращения к модели и без списания.'
security:
- apiKey: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChatCompletionRequest'
examples:
basic:
value:
model: gpt-5.6-sol
messages:
- role: user
content: Напиши заголовок для статьи о Nano Banana 2
max_tokens: 200
responses:
'200':
description: 'Ответ `chat.completion` (JSON) либо SSE-поток (`text/event-stream`)
при `stream: true`, завершающийся `data: [DONE]`.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ChatCompletionResponse'
text/event-stream:
schema:
type: string
description: 'SSE-чанки `chat.completion.chunk`, последняя строка `data: [DONE]`.'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
description: Бюджет/кредиты исчерпаны (`insufficient_quota`).
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'404':
description: Неизвестный `model`.
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'429':
description: Лимит RPM/TPM/одновременных запросов; см. `Retry-After`.
headers:
Retry-After:
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
servers:
- url: https://api.clipia.ai
description: Production
/v1/completions:
post:
tags:
- LLM
operationId: createCompletion
deprecated: true
summary: Text completion (legacy OpenAI, deprecated)
description: '**Устарело.** Совместимость со старыми клиентами (`continue.dev`,
langchain `OpenAI` non-chat). Тонкая проекция над тем же ядром, что и
`/v1/chat/completions`: `prompt` становится одним user-сообщением, ответ
проецируется в форму `text_completion` (`choices[].text`). Новые
интеграции должны использовать `/v1/chat/completions`; этот маршрут
не получает новых возможностей (tools, response_format, reasoning).
`id` ответа — `cmpl-…`, принимается `GET /v1/generation?id=`.'
security:
- apiKey: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- model
- prompt
properties:
model:
type: string
prompt:
oneOf:
- type: string
- type: array
items:
type: string
max_tokens:
type: integer
temperature:
type: number
stream:
type: boolean
additionalProperties: true
responses:
'200':
description: 'Ответ `text_completion` (JSON) либо SSE-поток при `stream: true`.'
content:
application/json:
schema:
type: object
properties:
id:
type: string
examples:
- cmpl-7Qx9rT2bK3mN8pL1sV4wY6zA
object:
type: string
const: text_completion
model:
type: string
choices:
type: array
items:
type: object
properties:
index:
type: integer
text:
type: string
finish_reason:
type:
- string
- 'null'
usage:
$ref: '#/components/schemas/OpenAIUsage'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
description: Лимит; см. `Retry-After`.
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
servers:
- url: https://api.clipia.ai
description: Production
/v1/generation:
get:
tags:
- LLM
operationId: getGenerationStats
summary: Фактическое списание за ответ LLM
description: 'OpenAI-совместимая статистика одного ответа шлюза: фактически
списанные кредиты и токены. `id` — `id` ответа (`chatcmpl-…` / `cmpl-…`)
либо UUID запроса (`X-Request-Id`). Чужой или неизвестный `id` → 404.'
security:
- apiKey: []
parameters:
- name: id
in: query
required: true
schema:
type: string
examples:
chat:
value: chatcmpl-7Qx9rT2bK3mN8pL1sV4wY6zA
responses:
'200':
description: Статистика ответа.
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: object
properties:
id:
type: string
total_cost:
type: number
description: Фактически списанные кредиты (дробные).
tokens_prompt:
type:
- integer
- 'null'
tokens_completion:
type:
- integer
- 'null'
native_tokens_prompt:
type:
- integer
- 'null'
native_tokens_completion:
type:
- integer
- 'null'
finish_reason:
type:
- string
- 'null'
model:
type:
- string
- 'null'
description: Публичный slug модели.
provider:
type: string
const: Clipia
streamed:
type:
- boolean
- 'null'
created_at:
type: string
format: date-time
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
servers:
- url: https://api.clipia.ai
description: Production
webhooks:
generation.completed:
post:
operationId: webhookGenerationCompleted
summary: Генерация завершена успешно
description: 'Если при `submit` был передан `webhook_url`, Clipia отправит `POST` на
этот URL по успешном завершении генерации.
**Заголовки подписи** (HMAC-SHA256):
- `X-Clipia-Webhook-Id` — UUID доставки.
- `X-Clipia-Timestamp` — Unix-время (секунды).
- `X-Clipia-Signature` — формат `t=,v1=`, где
`hmac = HMAC_SHA256(secret, "{timestamp}.{raw_body}")` в hex.
`secret` — webhook signing secret из личного кабинета.
Проверяйте подпись timing-safe сравнением и отбрасывайте доставки старше
окна свежести (по умолчанию 300 секунд). Обрабатывайте идемпотентно по
`request_id` (возможна повторная доставка). Ожидается ответ `2xx` в
течение 10 секунд; иначе — ретраи с экспоненциальной задержкой до 6 попыток.'
parameters:
- $ref: '#/components/parameters/WebhookId'
- $ref: '#/components/parameters/WebhookTimestamp'
- $ref: '#/components/parameters/WebhookSignature'
requestBody:
required: true
description: Payload успешной доставки.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookSuccess'
examples:
completed:
summary: Успех
value:
request_id: 764cabcf-b745-4b3e-ae38-1200304cf45b
status: OK
payload:
model: nano-banana-2
output:
images:
- url: https://media.clipia.ai/works/8f3a1c7e.webp
original_url: https://media.clipia.ai/works/8f3a1c7e.png
cost: 12
responses:
'200':
description: Доставка принята получателем.
tags:
- LLM
servers:
- url: https://api.clipia.ai
description: Production
generation.failed:
post:
operationId: webhookGenerationFailed
summary: Генерация завершилась ошибкой
description: 'Если при `submit` был передан `webhook_url`, Clipia отправит `POST` на
этот URL при ошибке генерации. Кредиты при этом возвращены.
Заголовки подписи и правила доставки идентичны `generation.completed`
(HMAC-SHA256, `X-Clipia-Signature`, окно свежести, ретраи).'
parameters:
- $ref: '#/components/parameters/WebhookId'
- $ref: '#/components/parameters/WebhookTimestamp'
- $ref: '#/components/parameters/WebhookSignature'
requestBody:
required: true
description: Payload доставки об ошибке.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookError'
examples:
failed:
summary: Ошибка
value:
request_id: 764cabcf-b745-4b3e-ae38-1200304cf45b
status: ERROR
error:
code: content_moderated
message: Generation failed. Please retry or contact support.
responses:
'200':
description: Доставка принята получателем.
tags:
- LLM
servers:
- url: https://api.clipia.ai
description: Production
components:
schemas:
Error:
type: object
description: Единый JSON-формат ошибки. Сообщения санитизированы.
required:
- error
properties:
error:
type: object
required:
- type
- code
- message
properties:
type:
type: string
description: Категория ошибки (закрытый список).
enum:
- invalid_request_error
- authentication_error
- permission_error
- billing_error
- idempotency_error
- rate_limit_error
- api_error
code:
type: string
description: 'Машиночитаемый код ошибки. Соответствие `code → type`:
`invalid_request`, `not_found`, `model_input_invalid`, `invalid_model` → `invalid_request_error`;
`invalid_api_key` → `authentication_error`; `insufficient_scope` → `permission_error`;
`insufficient_credits`, `subscription_required` → `billing_error`;
`idempotency_key_reuse`, `request_in_progress` → `idempotency_error`;
`rate_limit_exceeded`, `concurrency_limit_exceeded` → `rate_limit_error`;
`internal_error`, `service_unavailable` → `api_error`.
'
examples:
- invalid_api_key
- insufficient_credits
- subscription_required
- insufficient_scope
- not_found
- idempotency_key_reuse
- request_in_progress
- model_input_invalid
- rate_limit_exceeded
- concurrency_limit_exceeded
- internal_error
- service_unavailable
message:
type: string
description: Человекочитаемое описание ошибки.
retry_after_seconds:
type: integer
description: Подсказка для 429/503 — через сколько секунд повторить (дублирует `Retry-After`).
retry_after_ms:
type: integer
description: То же в миллисекундах (для коротких окон опроса).
OpenAIUsage:
type: object
properties:
prompt_tokens:
type: integer
completion_tokens:
type: integer
total_tokens:
type: integer
cost:
type: number
description: Списанные кредиты (дробные).
WebhookError:
type: object
description: Payload вебхука об ошибке генерации (кредиты возвращены).
required:
- request_id
- status
- error
properties:
request_id:
type: string
format: uuid
status:
type: string
const: ERROR
description: Признак ошибки.
error:
$ref: '#/components/schemas/GenerationError'
OpenAIError:
type: object
description: Конверт ошибки OpenAI-совместимого шлюза (отличается от `Error` очереди).
required:
- error
properties:
error:
type: object
required:
- message
- type
properties:
message:
type: string
type:
type: string
examples:
- invalid_request_error
- rate_limit_error
- insufficient_quota
code:
type:
- string
- 'null'
examples:
- model_not_found
- insufficient_quota
- rate_limit_exceeded
- concurrency_limit_exceeded
ChatCompletionRequest:
type: object
description: Подмножество OpenAI chat-запроса; остальные поля OpenAI-формата принимаются и игнорируются.
required:
- model
- messages
additionalProperties: true
properties:
model:
type: string
description: Slug LLM-модели из `GET /v1/models`.
examples:
- gpt-5.6-sol
messages:
type: array
items:
type: object
required:
- role
- content
properties:
role:
type: string
enum:
- system
- user
- assistant
- tool
content:
description: Строка либо массив частей (text / image_url).
name:
type: string
tool_call_id:
type: string
stream:
type: boolean
default: false
temperature:
type: number
top_p:
type: number
max_tokens:
type: integer
max_completion_tokens:
type: integer
n:
type: integer
seed:
type: integer
stop:
oneOf:
- type: string
- type: array
items:
type: string
tools:
type: array
items:
type: object
tool_choice: {}
response_format:
type: object
reasoning_effort:
type: string
stream_options:
type: object
properties:
include_usage:
type: boolean
user:
type: string
WebhookSuccess:
type: object
description: Payload вебхука об успешном завершении генерации.
required:
- request_id
- status
- payload
properties:
request_id:
type: string
format: uuid
status:
type: string
const: OK
description: Признак успеха.
payload:
type: object
required:
- model
- output
- cost
properties:
model:
type: string
examples:
- nano-banana-2
output:
type: object
description: 'Результат генерации (медиа-URL на `media.clipia.ai`): `images: [{ url }]`,
`video: { url }` либо `audio: { url, format? }` вместе с
`audios: [{ url, format? }]` (все варианты трека; первый совпадает с `audio`).
⚠️ Payload вебхука компактнее ответа `GET /v1/requests/{id}`: поле
`original_url` в него не кладётся. Если нужен оригинал в полном
качестве — запросите результат по `request_id`.
'
additionalProperties: true
cost:
type: number
description: Итоговая стоимость в кредитах.
GenerationError:
type: object
description: 'Санитизированная ошибка генерации — без деталей внутренней инфраструктуры.
Кредиты за FAILED возвращаются всегда. `code` — закрытый словарь
(snake_case), по нему клиент решает, повторять ли запрос:
| code | Смысл | Повтор |
| --- | --- | --- |
| `generation_failed` | Общая ошибка генерации | можно |
| `content_moderated` | Запрос отклонён модерацией контента | с тем же вводом бесполезен |
| `invalid_input` | Ввод не принят моделью (размер/формат/параметры) | исправьте запрос |
| `model_unavailable` | Модель временно недоступна | позже |
| `timeout` | Генерация не уложилась во время | можно |
| `rate_limited` | Модель перегружена | с паузой |
| `insufficient_credits` | Не хватило кредитов на момент списания | после пополнения |
| `result_unavailable` | Результат получен, но не сохранён/недоступен | можно |
| `empty_result` | Модель вернула пустой результат | можно / измените запрос |
| `canceled` | Отменено пользователем или системой | — |
'
required:
- code
- message
properties:
code:
type: string
enum:
- generation_failed
- content_moderated
- invalid_input
- model_unavailable
- timeout
- rate_limited
- insufficient_credits
- result_unavailable
- empty_result
- canceled
examples:
- generation_failed
message:
type: string
description: Нейтральное описание на английском; без имён внутренних систем.
examples:
- Generation failed. Please retry or contact support.
ChatCompletionResponse:
type: object
required:
- id
- object
- created
- model
- choices
- usage
properties:
id:
type: string
description: Детерминированный id ответа; принимается `GET /v1/generation?id=`.
examples:
- chatcmpl-7Qx9rT2bK3mN8pL1sV4wY6zA
object:
type: string
const: chat.completion
created:
type: integer
model:
type: string
provider:
type: string
const: Clipia
choices:
type: array
items:
type: object
properties:
index:
type: integer
message:
type: object
properties:
role:
type: string
content:
type:
- string
- 'null'
tool_calls:
type: array
items:
type: object
finish_reason:
type:
- string
- 'null'
enum:
- stop
- length
- tool_calls
- content_filter
- error
- null
usage:
$ref: '#/components/schemas/OpenAIUsage'
responses:
RateLimited:
description: "Превышен лимит. `error.type` всегда `rate_limit_error`; различайте по `error.code`:\n\n- `rate_limit_exceeded` — запросов в минуту (RPM) или токенов в минуту (TPM) по ключу;\n- `concurrency_limit_exceeded` — слишком много генераций одновременно\n (по ключу или по аккаунту). Дождитесь завершения одной и повторите.\n\nВ обоих случаях сервер отдаёт заголовок `Retry-After` и дублирует подсказку в\n`error.retry_after_seconds`.\n"
headers:
Retry-After:
description: Через сколько секунд можно повторить запрос.
schema:
type: integer
RateLimit-Limit:
description: Лимит запросов в минуту.
schema:
type: integer
RateLimit-Remaining:
description: Остаток запросов в текущем окне.
schema:
type: integer
RateLimit-Reset:
description: Через сколько секунд сбросится окно лимита.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
rateLimited:
summary: RPM/TPM по ключу
value:
error:
type: rate_limit_error
code: rate_limit_exceeded
message: Rate limit exceeded. Retry after the reset window.
retry_after_seconds: 12
concurrencyLimited:
summary: Слишком много одновременных генераций
value:
error:
type: rate_limit_error
code: concurrency_limit_exceeded
message: Too many concurrent generations in flight for this API key (limit 5). Wait for one to finish, then retry.
retry_after_seconds: 5
Unauthorized:
description: Ключ отсутствует, неверный или отозван.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalidApiKey:
value:
error:
type: invalid_request_error
code: invalid_api_key
message: API-ключ отсутствует, неверный или отозван.
NotFound:
description: Неизвестный `request_id` или `model`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
notFound:
value:
error:
type: invalid_request_error
code: not_found
message: Запрос с таким идентификатором не найден.
parameters:
WebhookId:
name: X-Clipia-Webhook-Id
in: header
required: true
description: UUID доставки вебхука.
schema:
type: string
format: uuid
WebhookSignature:
name: X-Clipia-Signature
in: header
required: true
description: 'Подпись доставки в формате `t=<ts>,v1=<hmac>`, где
`hmac = HMAC_SHA256(secret, "{timestamp}.{raw_body}")` в hex.
'
schema:
type: string
examples:
- t=1717243200,v1=5257a869e7d1f3...
WebhookTimestamp:
name: X-Clipia-Timestamp
in: header
required: true
description: Unix-время доставки (секунды). Используется для проверки свежести.
schema:
type: integer
format: int64
examples:
- 1717243200
securitySchemes:
apiKey:
type: apiKey
in: header
name: Authorization
description: 'API-ключ в заголовке `Authorization` со схемой `Bearer`:
```
Authorization: Bearer <CLIPIA_API_KEY>
```
Передавайте полную строку, включая префикс схемы `Bearer ` и пробел.
Также принимаются `Authorization: Key <ключ>` и заголовок
`X-Api-Key: <ключ>` — выбирайте удобную схему.
Ключ создаётся в консоли разработчика (clipia.ai/developer, вкладка
«API-ключи») и показывается один раз. Формат: `clipia_live_…` (боевой), `clipia_test_…` (песочница).
**Sandbox / тестовый режим.** Ключ с префиксом `clipia_test_…` работает в
песочнице: `submit` не списывает кредиты и не запускает реальную
генерацию — он мгновенно возвращает `status: COMPLETED` с детерминированным
mock-результатом (фиксированный sample-ассет на `media.clipia.ai`). Поле
`cost` показывает расчётную стоимость, но она не списывается. Вебхуки
приходят тем же подписанным механизмом (HMAC-SHA256). Режим предназначен
для отладки интеграции до подключения боевого ключа.
'
x-sandbox:
keyPrefix: clipia_test_
chargesCredits: false
callsGeneration: false
immediateStatus: COMPLETED
sampleImageUrl: https://media.clipia.ai/sandbox/v1/sample-image.png
sampleVideoUrl: https://media.clipia.ai/sandbox/v1/sample-video.mp4
sampleAudioUrl: https://media.clipia.ai/sandbox/v1/sample-audio.mp3
x-refined-from:
- clipia-v1.json
- clipia-ai-openapi.yml