Developer API

API Reference

A route-level reference generated from the gateway surface, grouped by developer, browser-session, and callback/internal audiences.

#Developer routes

Developer-facing routes are listed first, then expanded with parameters, request bodies, response shapes, error behavior, and operational notes from the gateway code.

POST

Endpoint

/auth/device/code

Create a device code, user code, verification URL, expiry, and polling interval.

Auth

None

API key scope

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`client` and optional `scope`; missing scope defaults to `ricochet_code`.

Response

Returns `device_code`, `user_code`, `verification_url`, `expires_in`, and `interval`, with snake_case and camelCase aliases where implemented.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

POST

Endpoint

/auth/device/token

Exchange an approved device code for access and refresh tokens.

Auth

None

API key scope

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`device_code` returned by `/auth/device/code`.

Response

Returns Grik `access_token`, `refresh_token`, expiry, and related token metadata.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

POST

Endpoint

/auth/refresh

Rotate a refresh token and receive a fresh access token.

Auth

None

API key scope

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`refresh_token`; the server rotates it and returns a new token pair.

Response

Returns Grik `access_token`, `refresh_token`, expiry, and related token metadata.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

GET

Endpoint

/users/me

Return the authenticated user profile used for billing and ownership.

Auth

Bearer token

API key scope

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

No JSON request body.

Response

Returns the resource or list described by the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

POST

Endpoint

/auth/api-keys

Issue an organization API key such as grik_live_... for server-side integrations.

Auth

User token

API key scope

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`name`, `scopes`, optional `product`, `mode`, `environment`, `spend_limit_micros`, and `spend_reset_interval`.

Response

Returns the API key record plus the raw key once. Store it immediately; it is not returned again.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

GET

Endpoint

/auth/api-keys

List active and revoked API keys without exposing the raw secret.

Auth

User token

API key scope

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

No JSON request body.

Response

Returns API key records with prefix/last4 and controls, never raw secrets.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

PATCH

Endpoint

/auth/api-keys/:id

Update key metadata, scopes, environment, status, or spend controls without revealing the raw secret.

Auth

User token

API key scope

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

Any mutable API key metadata: `name`, `scopes`, `status`, `environment`, `spend_limit_micros`, or `spend_reset_interval`.

Response

Returns the resource or list described by the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

DELETE

Endpoint

/auth/api-keys/:id

Revoke an API key by id. Revoked keys fail authentication immediately.

Auth

User token

API key scope

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

No JSON request body.

Response

Returns the resource or list described by the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

GET

Endpoint

/models

List AI Gateway models with provider availability, context length, pricing, capabilities, and data policy metadata.

Auth

Optional bearer

API key scope

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

No JSON request body.

Response

Returns provider model metadata, capabilities, pricing, context limits, availability, and data policy where available.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

GET

Endpoint

/rico/models

List RICO recipes, workflows, and effect presets. Optional type filters include recipe, workflow, and effect.

Auth

API key

API key scope

rico.media or video

Audience

Developers

Parameters

Optional `type` query parameter filters the catalog to models, recipes, workflows, or effects.

Request body

No JSON request body.

Response

Returns RICO models, sessions, messages, assets, timeline events, or MCP tool results depending on the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/rico/models/:id

Inspect one RICO recipe, workflow, model, or effect preset by id.

Auth

API key

API key scope

rico.media or video

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

No JSON request body.

Response

Returns RICO models, sessions, messages, assets, timeline events, or MCP tool results depending on the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/rico/workflows

List RICO Supercomputer recipes and allowlisted executor workflows for web, MCP, CLI, and API use.

Auth

API key

API key scope

rico.media or video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

No JSON request body.

Response

Returns RICO models, sessions, messages, assets, timeline events, or MCP tool results depending on the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/rico/recipes

List RICO Supercomputer recipes only.

Auth

API key

API key scope

rico.media or video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

No JSON request body.

Response

Returns RICO models, sessions, messages, assets, timeline events, or MCP tool results depending on the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/chat/completions

Run OpenAI/OpenRouter-compatible chat completions through the GRIKAI AI Gateway with streaming, tools, fallbacks, and provider routing.

Auth

API key

API key scope

ai.gateway

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

OpenAI-compatible chat request with `model`, optional `models`, `provider`, `messages`, `stream`, tools, and sampling fields.

Response

Returns or streams an OpenAI-compatible chat completion response. Non-stream responses include AI Gateway charge/provider headers.

Errors

AI Gateway chat errors use OpenAI-compatible `error.type`, `error.code`, and `error.message`; `402`, `429`, `502`, and `503` are important retry/billing signals.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
`Idempotency-Key` is implemented for this create/hosted-usage flow and should be stable per user action.

POST

Endpoint

/responses

Run OpenAI Responses-compatible requests through the GRIKAI AI Gateway with the same model catalog, routing, fallbacks, and usage billing.

Auth

API key

API key scope

ai.gateway

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

OpenAI Responses-compatible request with `model`, `input`, optional `models`, `provider`, `stream`, tools, instructions, and `max_output_tokens`.

Response

Returns or streams an OpenAI Responses-compatible response. Non-stream responses include AI Gateway charge/provider headers.

Errors

AI Gateway chat errors use OpenAI-compatible `error.type`, `error.code`, and `error.message`; `402`, `429`, `502`, and `503` are important retry/billing signals.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
`Idempotency-Key` is implemented for this create/hosted-usage flow and should be stable per user action.

POST

Endpoint

/responses/input_tokens

Count Responses input tokens before execution. OpenAI-backed models use upstream token counting; other providers return an estimated count.

Auth

API key

API key scope

ai.gateway

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

OpenAI Responses-compatible request with `model`, `input`, optional `models`, `provider`, `stream`, tools, instructions, and `max_output_tokens`.

Response

Returns `input_tokens`, model/provider metadata, `estimated`, `estimate_method`, and context length.

Errors

AI Gateway chat errors use OpenAI-compatible `error.type`, `error.code`, and `error.message`; `402`, `429`, `502`, and `503` are important retry/billing signals.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Call before upstream hosted model execution to estimate tokens, cost, balance, or approval state before committing to a paid request.

GET

Endpoint

/ai-gateway/balance

Return balance_micros, pending reservation micros, available balance, and USD display values.

Auth

API key

API key scope

ai.gateway

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

No JSON request body.

Response

Returns `balance_micros`, pending reservations, available balance, currency, and unit metadata.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.

GET

Endpoint

/ai-gateway/pricing

Return AI Gateway packages, platform fee, minimum charge, and customer-visible model pricing.

Auth

Optional bearer

API key scope

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

No JSON request body.

Response

Returns AI Gateway packages, platform fee basis points, minimum charge, model rates, and chat/responses endpoint URLs.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

Pricing values come from backend config endpoints; do not copy static tables into client code.

POST

Endpoint

/ai-gateway/quote

Estimate tokens, customer charge, available balance, spend-limit decision, and fallback-route charge before execution. This does not reserve or charge balance.

Auth

API key

API key scope

ai.gateway

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`endpoint`, `model`, `input` or `messages`, optional fallback `models`, `provider` routing, and `max_output_tokens`/`max_tokens`. The quote is read-only and does not reserve balance.

Response

Returns estimated input/output tokens, customer charge, available balance, spend-limit decision, pricing, and candidate route breakdown without charging balance.

Errors

AI Gateway chat errors use OpenAI-compatible `error.type`, `error.code`, and `error.message`; `402`, `429`, `502`, and `503` are important retry/billing signals.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Call before upstream hosted model execution to estimate tokens, cost, balance, or approval state before committing to a paid request.

GET

Endpoint

/ai-gateway/usage

List AI Gateway usage events with provider, model, status, date, and limit filters.

Auth

API key

API key scope

ai.gateway

Audience

Developers

Parameters

Optional query parameters: `status`, `model`, `from`, `to`, and `limit`.

Request body

No JSON request body.

Response

Returns usage/reservation events with provider, model, token counts, charge, route attempts, status, and metadata.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.

GET

Endpoint

/ai-gateway/usage/:id

Fetch one usage event with token counts, provider cost, platform fee, charge, route attempts, and metadata.

Auth

API key

API key scope

ai.gateway

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

No JSON request body.

Response

Returns usage/reservation events with provider, model, token counts, charge, route attempts, status, and metadata.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.

GET

Endpoint

/ai-gateway/reservations

List active, failed, and settled preflight reservations for idempotency and pending-balance debugging.

Auth

API key

API key scope

ai.gateway

Audience

Developers

Parameters

Optional query parameters: `status`, `model`, `from`, `to`, and `limit`.

Request body

No JSON request body.

Response

Returns usage/reservation events with provider, model, token counts, charge, route attempts, status, and metadata.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.

GET

Endpoint

/keys

List account API keys without exposing the raw secret.

Auth

User token

API key scope

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

No JSON request body.

Response

Returns API key records with prefix/last4 and controls, never raw secrets.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

POST

Endpoint

/keys

Create an API key with ai.gateway scope and optional spend controls. The raw key is returned only once.

Auth

User token

API key scope

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`name`, `scopes`, optional `product`, `mode`, `environment`, `spend_limit_micros`, and `spend_reset_interval`.

Response

Returns the API key record plus the raw key once. Store it immediately; it is not returned again.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

PATCH

Endpoint

/keys/:id

Update key name, status, scopes, environment, spend limit, or reset interval without rotating the secret.

Auth

User token

API key scope

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

Any mutable API key metadata: `name`, `scopes`, `status`, `environment`, `spend_limit_micros`, or `spend_reset_interval`.

Response

Returns the resource or list described by the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

DELETE

Endpoint

/keys/:id

Revoke an API key by id.

Auth

User token

API key scope

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

No JSON request body.

Response

Returns the resource or list described by the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

GET

Endpoint

/billing/credits

Return product credit wallets plus ai_gateway_balance_micros.

Auth

API key

API key scope

billing.read

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

No JSON request body.

Response

Returns payment, subscription, entitlement, transaction, wallet, or provider status records.

Errors

Billing endpoints return structured API errors such as `invalid_request`, `payment_provider_not_configured`, `payment_provider_unavailable`, `not_found`, and `provider_unavailable`.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.

GET

Endpoint

/billing/transactions

List billing transactions with optional product filter.

Auth

API key

API key scope

billing.read

Audience

Developers

Parameters

Optional query parameters: `limit` (default 50, max 100) and `product` such as `ai_gateway`.

Request body

No JSON request body.

Response

Returns payment, subscription, entitlement, transaction, wallet, or provider status records.

Errors

Billing endpoints return structured API errors such as `invalid_request`, `payment_provider_not_configured`, `payment_provider_unavailable`, `not_found`, and `provider_unavailable`.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.

GET

Endpoint

/billing/entitlements

Return active subscriptions and period-end cancellation fields.

Auth

API key

API key scope

billing.read

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

No JSON request body.

Response

Returns payment, subscription, entitlement, transaction, wallet, or provider status records.

Errors

Billing endpoints return structured API errors such as `invalid_request`, `payment_provider_not_configured`, `payment_provider_unavailable`, `not_found`, and `provider_unavailable`.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.

POST

Endpoint

/rico/sessions

Create a RICO Supercomputer session with brief, recipe, inputs, cost estimate, messages, and pending steps.

Auth

API key

API key scope

rico.media or video

Audience

Developers

Parameters

Optional `limit` query parameter limits recent rows. The gateway caps large limits.

Request body

`workflow`, optional `brief`, `channel`, `inputs`, `attached_asset_ids`, and `auto_run_limit`.

Response

Returns RICO models, sessions, messages, assets, timeline events, or MCP tool results depending on the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/rico/sessions/:id/approve

Approve a RICO Supercomputer session, deduct RICO media credits, and queue deterministic execution.

Auth

API key

API key scope

rico.media or video

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

JSON object. See the OpenAPI schema for the exact fields accepted by this operation.

Response

Returns RICO models, sessions, messages, assets, timeline events, or MCP tool results depending on the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/rico/mcp

Call the RICO MCP endpoint with tools such as rico_estimate_cost, rico_apply_effect, rico_repurpose, and rico_get_job.

Auth

API key

API key scope

rico.media or video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

JSON-RPC style MCP request, or direct tool call with `tool`/`name` and `arguments`.

Response

Returns RICO models, sessions, messages, assets, timeline events, or MCP tool results depending on the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/generate/video

Start text-to-video or image-to-video generation with model, aspect ratio, duration, mode, image URL, and sound options.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`prompt` is required. Optional fields include `model`, `model_name`, `aspect_ratio`, image/video inputs, `mode`, `duration`, `sound`, `external_task_id`, and `callback_url`.

Response

Returns `task_id`, queued status, credit fields when charged, and timestamps where implemented.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
`Idempotency-Key` is implemented for this create/hosted-usage flow and should be stable per user action.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/kling/videos/effects

Queue a Kling Video Effects Center task by effect_scene with single-image or dual-image input.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`effect_scene` and `input.image` or exactly two `input.images` are required. Top-level `image`/`images` are normalized into `input`.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/kling/lipsync

Queue Kling advanced lip-sync and track it through the provider task registry.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

Provider-shaped JSON object. The gateway injects the route `task_type`, strips data URL prefixes, and forwards remaining fields to the Kling worker.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/kling/multi-elements

Queue a Kling multi-elements video editing task.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

Provider-shaped JSON object. The gateway injects the route `task_type`, strips data URL prefixes, and forwards remaining fields to the Kling worker.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/repurpose

Start a repurposing pipeline from a YouTube or file URL with optional language.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`url` is required; `language` is optional.

Response

Returns `task_id`, queued status, credit fields when charged, and timestamps where implemented.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
`Idempotency-Key` is implemented for this create/hosted-usage flow and should be stable per user action.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/rico/sessions

List recent RICO Supercomputer sessions for the authenticated account.

Auth

API key

API key scope

rico.media or video

Audience

Developers

Parameters

Optional `limit` query parameter limits recent rows. The gateway caps large limits.

Request body

No JSON request body.

Response

Returns RICO models, sessions, messages, assets, timeline events, or MCP tool results depending on the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/rico/sessions/:id

Fetch a RICO Supercomputer session with messages, workflow steps, status, and current assets.

Auth

API key

API key scope

rico.media or video

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

No JSON request body.

Response

Returns RICO models, sessions, messages, assets, timeline events, or MCP tool results depending on the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/rico/sessions/:id/events

Fetch a polling-friendly RICO session timeline with messages, steps, and assets.

Auth

API key

API key scope

rico.media or video

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

No JSON request body.

Response

Returns RICO models, sessions, messages, assets, timeline events, or MCP tool results depending on the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/rico/sessions/:id/messages

Add a user or assistant message to an existing RICO session.

Auth

API key

API key scope

rico.media or video

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

`content` is required. Optional `workflow`, `inputs`, and `attached_asset_ids` can advance the session.

Response

Returns RICO models, sessions, messages, assets, timeline events, or MCP tool results depending on the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/rico/sessions/:id/assets

List media assets produced by a RICO Supercomputer session.

Auth

API key

API key scope

rico.media or video

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

No JSON request body.

Response

Returns RICO models, sessions, messages, assets, timeline events, or MCP tool results depending on the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/rico/assets

List recent RICO media assets.

Auth

API key

API key scope

rico.media or video

Audience

Developers

Parameters

Optional `limit` query parameter limits recent rows. The gateway caps large limits.

Request body

No JSON request body.

Response

Returns RICO models, sessions, messages, assets, timeline events, or MCP tool results depending on the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/rico/assets

Upload or register a RICO media asset by multipart file, URL, or data URL.

Auth

API key

API key scope

rico.media or video

Audience

Developers

Parameters

Optional `limit` query parameter limits recent rows. The gateway caps large limits.

Request body

JSON accepts `url`, `media_url`, `data_url`, `type`, `title`, `prompt`, `source_id`, `parent_project_id`, and `metadata`; multipart uses field `file` plus form fields.

Response

Returns RICO models, sessions, messages, assets, timeline events, or MCP tool results depending on the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/rico/assets/:id

Fetch one RICO media asset by id.

Auth

API key

API key scope

rico.media or video

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

No JSON request body.

Response

Returns RICO models, sessions, messages, assets, timeline events, or MCP tool results depending on the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/generation/:id

Fetch a generation record, status, output video URL, metadata, file size, and any error message.

Auth

API key

API key scope

video

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

No JSON request body.

Response

Returns the stored generation or repurpose record with current status, outputs, clips, metadata, and errors where available.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/kling/tasks/:id

Fetch any Kling provider task by local task ID, provider task ID, or external task ID.

Auth

API key

API key scope

video

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

No JSON request body.

Response

Returns the stored provider task matched by local id, provider task id, or `external_task_id`.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/repurpose

List recent repurpose jobs.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

No JSON request body.

Response

Returns the stored generation or repurpose record with current status, outputs, clips, metadata, and errors where available.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
`Idempotency-Key` is implemented for this create/hosted-usage flow and should be stable per user action.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/repurpose/:id

Fetch a repurposing task with rendered clips, transcripts, segments, viral scores, and output URLs.

Auth

API key

API key scope

video

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

No JSON request body.

Response

Returns the stored generation or repurpose record with current status, outputs, clips, metadata, and errors where available.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/repurpose/:id/retry

Retry a failed repurpose job.

Auth

API key

API key scope

video

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

JSON object. See the OpenAPI schema for the exact fields accepted by this operation.

Response

Returns the stored generation or repurpose record with current status, outputs, clips, metadata, and errors where available.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

DELETE

Endpoint

/repurpose/:id

Delete a repurpose job by id.

Auth

API key

API key scope

video

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

No JSON request body.

Response

Returns the stored generation or repurpose record with current status, outputs, clips, metadata, and errors where available.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

PUT

Endpoint

/repurpose/:task_id/clip/:clip_id

Update a clip edit state for a repurpose task.

Auth

API key

API key scope

video

Audience

Developers

Parameters

Path parameters `task_id` and `clip_id` identify the repurpose project and the clip being edited or rendered.

Request body

Optional editable clip fields: `title`, `transcript`, `segments`, `caption_settings`, and `timeline_edit`.

Response

Returns the stored generation or repurpose record with current status, outputs, clips, metadata, and errors where available.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/repurpose/:task_id/clip/:clip_id/render-captions

Render a repurpose clip with timeline edits and optional burned captions.

Auth

API key

API key scope

video

Audience

Developers

Parameters

Path parameters `task_id` and `clip_id` identify the repurpose project and the clip being edited or rendered.

Request body

Optional `caption_settings` and `timeline_edit`. If omitted, stored clip settings are used; caption settings must exist before render.

Response

Returns the stored generation or repurpose record with current status, outputs, clips, metadata, and errors where available.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/images/generate

Generate images from a prompt, reference image, palette, model, and resolution. Kling models are queued through the provider task registry.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`prompt` or `image_url` is required for non-Kling image jobs. Kling models use `prompt`, `model_name`, references, `n`, `resolution`, and `aspect_ratio`.

Response

Returns the resource or list described by the operation.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/kling/images/generations

Queue Kling image generation directly with model_name, n, aspect ratio, references, and provider task status.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`prompt` is required. Optional Kling fields include `model_name`, `negative_prompt`, `image`, `image_reference`, `n`, `resolution`, `aspect_ratio`, and `external_task_id`.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/kling/general/ai-multi-shot

Queue Kling AI Multi-Shot from one frontal image and store all returned shots in the media library.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`element_frontal_image` is required. Additional provider fields pass through to Kling.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/kling/images/kolors-virtual-try-on

Queue Kling Kolors virtual try-on with human and cloth images.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`human_image` and `cloth_image` are required. Additional provider fields pass through to Kling.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/images/edit

Edit an image with a prompt and source image URL.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`image_url` is required; `prompt` describes the edit.

Response

Returns `task_id`, queued status, credit fields when charged, and timestamps where implemented.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/images/enhance

Enhance or upscale an image asset.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`image_url` is required.

Response

Returns `task_id`, queued status, credit fields when charged, and timestamps where implemented.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/images/faceswap

Swap a face between target and source images.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`target_image` and `swap_image` are required.

Response

Returns `task_id`, queued status, credit fields when charged, and timestamps where implemented.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/images/3d-angles

Generate a 3D/360-style video from an image.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`image_url` is required.

Response

Returns `task_id`, queued status, credit fields when charged, and timestamps where implemented.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/images/character-gen

Generate a consistent character from a prompt and optional reference image.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`image_url` and `prompt` are required.

Response

Returns `task_id`, queued status, credit fields when charged, and timestamps where implemented.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/kling/image-recognize

Run Kling image recognition and segmentation utilities for object, head, face, and clothing masks.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

Provider-shaped JSON object. The gateway injects the route `task_type`, strips data URL prefixes, and forwards remaining fields to the Kling worker.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/kling/audio/text-to-audio

Queue Kling text-to-audio generation and persist the generated audio in the media library.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

Provider-shaped JSON object. The gateway injects the route `task_type`, strips data URL prefixes, and forwards remaining fields to the Kling worker.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/kling/audio/video-to-audio

Queue Kling video-to-audio generation for a supplied video source.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

Provider-shaped JSON object. The gateway injects the route `task_type`, strips data URL prefixes, and forwards remaining fields to the Kling worker.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/kling/lipsync/identify-face

Identify faces for Kling lip-sync workflows before creating the final lip-sync task.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

Provider-shaped JSON object. The gateway injects the route `task_type`, strips data URL prefixes, and forwards remaining fields to the Kling worker.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/kling/voices

Create a Kling custom voice task.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

Provider-shaped JSON object. The gateway injects the route `task_type`, strips data URL prefixes, and forwards remaining fields to the Kling worker.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/kling/voices

List Kling custom voices.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

No JSON request body.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/kling/voices/:id

Fetch one Kling custom voice task by id.

Auth

API key

API key scope

video

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

No JSON request body.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/kling/voices/delete

Queue deletion of a Kling custom voice.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

Provider-shaped JSON object. The gateway injects the route `task_type`, strips data URL prefixes, and forwards remaining fields to the Kling worker.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/kling/voices/presets

List Kling preset voices available for audio and avatar tools.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

No JSON request body.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/kling/elements

Create Kling advanced custom elements for multi-element video editing.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

Provider-shaped JSON object. The gateway injects the route `task_type`, strips data URL prefixes, and forwards remaining fields to the Kling worker.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/kling/elements

List Kling advanced custom elements.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

No JSON request body.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/kling/elements/:id

Fetch one Kling advanced custom element by id.

Auth

API key

API key scope

video

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

No JSON request body.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/kling/multi-elements/init-selection

Initialize Kling multi-elements selections for editing workflows.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

Provider-shaped JSON object. The gateway injects the route `task_type`, strips data URL prefixes, and forwards remaining fields to the Kling worker.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/kling/multi-elements/add-selection

Add a Kling multi-elements selection.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

Provider-shaped JSON object. The gateway injects the route `task_type`, strips data URL prefixes, and forwards remaining fields to the Kling worker.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/kling/multi-elements/delete-selection

Delete a Kling multi-elements selection.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

Provider-shaped JSON object. The gateway injects the route `task_type`, strips data URL prefixes, and forwards remaining fields to the Kling worker.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/kling/multi-elements/clear-selection

Clear all Kling multi-elements selections.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

Provider-shaped JSON object. The gateway injects the route `task_type`, strips data URL prefixes, and forwards remaining fields to the Kling worker.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/kling/multi-elements/preview-selection

Preview a Kling multi-elements selection.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

Provider-shaped JSON object. The gateway injects the route `task_type`, strips data URL prefixes, and forwards remaining fields to the Kling worker.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/kling/multi-elements

List Kling multi-elements tasks.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

No JSON request body.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/kling/multi-elements/:id

Fetch one Kling multi-elements task by id.

Auth

API key

API key scope

video

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

No JSON request body.

Response

Returns the local provider task id, provider, `task_type`, `external_task_id`, status, and credit fields for charged Kling tools.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta provider passthrough route: required gateway validations are documented, but extra payload fields follow Kling/provider semantics.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/repurpose/tts

Generate speech audio from text and a voice selection.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`text` is required; `voice` is optional.

Response

Returns `task_id`, queued status, credit fields when charged, and timestamps where implemented.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/repurpose/enhance-audio

Queue audio enhancement for a source video.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`video_url` is required.

Response

Returns `task_id`, queued status, credit fields when charged, and timestamps where implemented.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/repurpose/lipsync

Synchronize a video with a supplied audio track.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`video_url` and `audio_url` are required.

Response

Returns `task_id`, queued status, credit fields when charged, and timestamps where implemented.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/repurpose/recast

Replace or recast a character in a source video with a target image.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`video_url` and `target_image` are required.

Response

Returns `task_id`, queued status, credit fields when charged, and timestamps where implemented.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/video/transitions

Create transitions across two or more input video URLs.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`video_urls` must contain at least two videos.

Response

Returns `task_id`, queued status, credit fields when charged, and timestamps where implemented.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/video/edit

Edit an existing video with a natural-language prompt.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`video_url` and `prompt` are required.

Response

Returns `task_id`, queued status, credit fields when charged, and timestamps where implemented.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/ads/generate

Generate an ad creative from a product URL.

Auth

API key

API key scope

video

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`product_url` is required.

Response

Returns `task_id`, queued status, credit fields when charged, and timestamps where implemented.

Errors

Some legacy media handlers still return a string error body; clients should tolerate both string and structured error bodies.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/broll/search

Search for B-roll media for repurpose and editing workflows.

Auth

API key

API key scope

video

Audience

Developers

Parameters

Required `query` query parameter searches the B-roll provider.

Request body

No JSON request body.

Response

Returns the resource or list described by the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/ricochet/budget

Check ricochet_code credits, plan, window limits, task limits, and upgrade URL before a hosted AI run.

Auth

API key

API key scope

ricochet_code

Audience

Ricochet clients

Parameters

Optional `task_id`, `run_id`, or `session_id` query parameter scopes the budget check to one hosted run.

Request body

No JSON request body.

Response

Returns credits, plan/budget windows, task limits, approval requirements, and upgrade URL.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/ricochet/usage/quote

Quote and reserve hosted Ricochet usage before calling an upstream model.

Auth

API key

API key scope

ricochet_code

Audience

Ricochet clients

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

Usage preflight fields include `idempotency_key`, `session_id`, `run_id`, `turn_id`, `provider`, `model`, `key_source`, token estimates, and `operation`.

Response

Returns quote, reservation, or settled usage details plus decision flags such as `approval_required` or `budget_exceeded`.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Call before upstream hosted model execution to estimate tokens, cost, balance, or approval state before committing to a paid request.
`Idempotency-Key` is implemented for this create/hosted-usage flow and should be stable per user action.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/ricochet/usage/report

Report hosted model usage with idempotency, token counts, provider, model, and billing metadata.

Auth

API key

API key scope

ricochet_code

Audience

Ricochet clients

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

Usage settlement fields include `reservation_id`, `idempotency_key`, session/run ids, provider/model, key source, token counts, and source metadata.

Response

Returns quote, reservation, or settled usage details plus decision flags such as `approval_required` or `budget_exceeded`.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
`Idempotency-Key` is implemented for this create/hosted-usage flow and should be stable per user action.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/ricochet/usage

List Ricochet hosted usage events with filters for session, run, provider, model, and limit.

Auth

API key

API key scope

ricochet_code

Audience

Ricochet clients

Parameters

Optional query parameters: `session_id`, `run_id`, `provider`, `model`, and `limit`.

Request body

No JSON request body.

Response

Returns the resource or list described by the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/ricochet/usage/approve-premium

Store a temporary approval for premium model usage in a task, run, or session.

Auth

API key

API key scope

ricochet_code

Audience

Ricochet clients

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`task_id`, `run_id`, or `session_id` identifies the premium approval target; optional approval metadata may be included.

Response

Returns quote, reservation, or settled usage details plus decision flags such as `approval_required` or `budget_exceeded`.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/ricochet/sessions

List Ricochet IDE and device sessions for the current user.

Auth

User token

API key scope

Audience

Ricochet clients

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

No JSON request body.

Response

Returns the resource or list described by the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

DELETE

Endpoint

/ricochet/sessions/:id

Revoke a Ricochet IDE or device session.

Auth

User token

API key scope

Audience

Ricochet clients

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

No JSON request body.

Response

Returns the resource or list described by the operation.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

POST

Endpoint

/ricochet/openai/v1/chat/completions

Legacy Ricochet hosted coding chat completions alias. Use /chat/completions on the AI Gateway for new generic model integrations.

Auth

API key

API key scope

ricochet_code

Audience

Ricochet clients

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

OpenAI-compatible chat request with `model`, optional `models`, `provider`, `messages`, `stream`, tools, and sampling fields.

Response

Returns or streams an OpenAI-compatible chat completion response. Non-stream responses include AI Gateway charge/provider headers.

Errors

AI Gateway chat errors use OpenAI-compatible `error.type`, `error.code`, and `error.message`; `402`, `429`, `502`, and `503` are important retry/billing signals.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Compatibility endpoint for existing Ricochet clients; new generic model integrations should use the AI Gateway route.
`Idempotency-Key` is implemented for this create/hosted-usage flow and should be stable per user action.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

POST

Endpoint

/ricochet/openai/v1/responses

Ricochet hosted coding Responses API alias for clients that use OpenAI Responses.

Auth

API key

API key scope

ricochet_code

Audience

Ricochet clients

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

OpenAI Responses-compatible request with `model`, `input`, optional `models`, `provider`, `stream`, tools, instructions, and `max_output_tokens`.

Response

Returns or streams an OpenAI Responses-compatible response. Non-stream responses include AI Gateway charge/provider headers.

Errors

AI Gateway chat errors use OpenAI-compatible `error.type`, `error.code`, and `error.message`; `402`, `429`, `502`, and `503` are important retry/billing signals.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Compatibility endpoint for existing Ricochet clients; new generic model integrations should use the AI Gateway route.
`Idempotency-Key` is implemented for this create/hosted-usage flow and should be stable per user action.
May deduct video, Ricochet, or media credits. Successful charged responses expose `credits_deducted`, `remaining_credits`, or usage decision fields where implemented.

GET

Endpoint

/social/accounts

List social accounts connected to the current user.

Auth

API key

API key scope

social

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

No JSON request body.

Response

Returns social account, post, caption, upload, or auto-import status objects from the current beta implementation.

Errors

Social beta routes may return legacy string errors for validation, provider configuration, upload, or database failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta route: parts of the social integration are mock or provider-dependent in the current code.

POST

Endpoint

/social/accounts/connect

Connect a social account record for YouTube, Instagram, TikTok, LinkedIn, X, or Facebook.

Auth

API key

API key scope

social

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`provider`, `provider_id`, `name`, and optional `avatar_url`. Current handler stores a mock token.

Response

Returns social account, post, caption, upload, or auto-import status objects from the current beta implementation.

Errors

Social beta routes may return legacy string errors for validation, provider configuration, upload, or database failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta route: parts of the social integration are mock or provider-dependent in the current code.

DELETE

Endpoint

/social/accounts/:id

Disconnect a social account by id.

Auth

API key

API key scope

social

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

No JSON request body.

Response

Returns social account, post, caption, upload, or auto-import status objects from the current beta implementation.

Errors

Social beta routes may return legacy string errors for validation, provider configuration, upload, or database failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta route: parts of the social integration are mock or provider-dependent in the current code.

GET

Endpoint

/social/posts

List scheduled posts, optionally filtered by date range.

Auth

API key

API key scope

social

Audience

Developers

Parameters

Optional `start` and `end` query parameters filter scheduled posts by date/time.

Request body

No JSON request body.

Response

Returns social account, post, caption, upload, or auto-import status objects from the current beta implementation.

Errors

Social beta routes may return legacy string errors for validation, provider configuration, upload, or database failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta route: parts of the social integration are mock or provider-dependent in the current code.

POST

Endpoint

/social/posts

Create a draft or scheduled post with content, hashtags, media, accounts, and platform options.

Auth

API key

API key scope

social

Audience

Developers

Parameters

Optional `start` and `end` query parameters filter scheduled posts by date/time.

Request body

`content`, `hashtags`, `media_id`, `media_type`, optional `scheduled_at`, `account_ids`, and `platform_options`.

Response

Returns social account, post, caption, upload, or auto-import status objects from the current beta implementation.

Errors

Social beta routes may return legacy string errors for validation, provider configuration, upload, or database failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta route: parts of the social integration are mock or provider-dependent in the current code.

PUT

Endpoint

/social/posts/:id

Update post content, hashtags, schedule, or status.

Auth

API key

API key scope

social

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

Mutable fields: `content`, `hashtags`, `scheduled_at`, and `status`.

Response

Returns social account, post, caption, upload, or auto-import status objects from the current beta implementation.

Errors

Social beta routes may return legacy string errors for validation, provider configuration, upload, or database failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta route: parts of the social integration are mock or provider-dependent in the current code.

DELETE

Endpoint

/social/posts/:id

Delete a scheduled post and clear its account associations.

Auth

API key

API key scope

social

Audience

Developers

Parameters

Path parameter `id` identifies the API key, job, session, payment, subscription, model, or provider resource.

Request body

No JSON request body.

Response

Returns social account, post, caption, upload, or auto-import status objects from the current beta implementation.

Errors

Social beta routes may return legacy string errors for validation, provider configuration, upload, or database failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta route: parts of the social integration are mock or provider-dependent in the current code.

POST

Endpoint

/social/generate-caption

Generate a social caption from a transcript or media id.

Auth

API key

API key scope

social

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`transcript` or `media_id`; media id falls back to a stored clip transcript.

Response

Returns social account, post, caption, upload, or auto-import status objects from the current beta implementation.

Errors

Social beta routes may return legacy string errors for validation, provider configuration, upload, or database failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta route: parts of the social integration are mock or provider-dependent in the current code.

POST

Endpoint

/social/upload

Upload an MP4 for social publishing workflows.

Auth

API key

API key scope

social

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

Multipart form field `file`; MP4 only, max 200 MB.

Response

Returns social account, post, caption, upload, or auto-import status objects from the current beta implementation.

Errors

Social beta routes may return legacy string errors for validation, provider configuration, upload, or database failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta route: parts of the social integration are mock or provider-dependent in the current code.

POST

Endpoint

/import/auto

Auth

API key

API key scope

social

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`platform` and `channel` identify the source to monitor.

Response

Returns social account, post, caption, upload, or auto-import status objects from the current beta implementation.

Errors

Social beta routes may return legacy string errors for validation, provider configuration, upload, or database failures.

Operations notes

The listed scope is enforced for API keys. User bearer tokens are authenticated separately and do not carry API-key scopes.
Advanced/Beta route: parts of the social integration are mock or provider-dependent in the current code.

GET

Endpoint

/config/pricing

Return pricing.yaml-backed generation costs, subscription plans, credit packages, Ricochet plans, and model billing policy.

Auth

None

API key scope

Audience

Developers

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

No JSON request body.

Response

Returns `pricing.yaml` backed generation costs, subscriptions, credit packages, Ricochet plans, storage policy, and model billing policy.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

Pricing values come from backend config endpoints; do not copy static tables into client code.

Method	Endpoint	Auth	Scope	Audience	Description
POST	`/auth/device/code`	None	-	Developers	Create a device code, user code, verification URL, expiry, and polling interval.
POST	`/auth/device/token`	None	-	Developers	Exchange an approved device code for access and refresh tokens.
POST	`/auth/refresh`	None	-	Developers	Rotate a refresh token and receive a fresh access token.
GET	`/users/me`	Bearer token	-	Developers	Return the authenticated user profile used for billing and ownership.
POST	`/auth/api-keys`	User token	-	Developers	Issue an organization API key such as grik_live_... for server-side integrations.
GET	`/auth/api-keys`	User token	-	Developers	List active and revoked API keys without exposing the raw secret.
PATCH	`/auth/api-keys/:id`	User token	-	Developers	Update key metadata, scopes, environment, status, or spend controls without revealing the raw secret.
DELETE	`/auth/api-keys/:id`	User token	-	Developers	Revoke an API key by id. Revoked keys fail authentication immediately.
GET	`/models`	Optional bearer	-	Developers	List AI Gateway models with provider availability, context length, pricing, capabilities, and data policy metadata.
GET	`/rico/models`	API key	rico.media or video	Developers	List RICO recipes, workflows, and effect presets. Optional type filters include recipe, workflow, and effect.
GET	`/rico/models/:id`	API key	rico.media or video	Developers	Inspect one RICO recipe, workflow, model, or effect preset by id.
GET	`/rico/workflows`	API key	rico.media or video	Developers	List RICO Supercomputer recipes and allowlisted executor workflows for web, MCP, CLI, and API use.
GET	`/rico/recipes`	API key	rico.media or video	Developers	List RICO Supercomputer recipes only.
POST	`/chat/completions`	API key	ai.gateway	Developers	Run OpenAI/OpenRouter-compatible chat completions through the GRIKAI AI Gateway with streaming, tools, fallbacks, and provider routing.Send Idempotency-Key for user-triggered create/retry requests.
POST	`/responses`	API key	ai.gateway	Developers	Run OpenAI Responses-compatible requests through the GRIKAI AI Gateway with the same model catalog, routing, fallbacks, and usage billing.Send Idempotency-Key for user-triggered create/retry requests.
POST	`/responses/input_tokens`	API key	ai.gateway	Developers	Count Responses input tokens before execution. OpenAI-backed models use upstream token counting; other providers return an estimated count.Use before the upstream hosted-model call.
GET	`/ai-gateway/balance`	API key	ai.gateway	Developers	Return balance_micros, pending reservation micros, available balance, and USD display values.
GET	`/ai-gateway/pricing`	Optional bearer	-	Developers	Return AI Gateway packages, platform fee, minimum charge, and customer-visible model pricing.
POST	`/ai-gateway/quote`	API key	ai.gateway	Developers	Estimate tokens, customer charge, available balance, spend-limit decision, and fallback-route charge before execution. This does not reserve or charge balance.Use before the upstream hosted-model call.
GET	`/ai-gateway/usage`	API key	ai.gateway	Developers	List AI Gateway usage events with provider, model, status, date, and limit filters.
GET	`/ai-gateway/usage/:id`	API key	ai.gateway	Developers	Fetch one usage event with token counts, provider cost, platform fee, charge, route attempts, and metadata.
GET	`/ai-gateway/reservations`	API key	ai.gateway	Developers	List active, failed, and settled preflight reservations for idempotency and pending-balance debugging.
GET	`/keys`	User token	-	Developers	List account API keys without exposing the raw secret.
POST	`/keys`	User token	-	Developers	Create an API key with ai.gateway scope and optional spend controls. The raw key is returned only once.
PATCH	`/keys/:id`	User token	-	Developers	Update key name, status, scopes, environment, spend limit, or reset interval without rotating the secret.
DELETE	`/keys/:id`	User token	-	Developers	Revoke an API key by id.
GET	`/billing/credits`	API key	billing.read	Developers	Return product credit wallets plus ai_gateway_balance_micros.
GET	`/billing/transactions`	API key	billing.read	Developers	List billing transactions with optional product filter.
GET	`/billing/entitlements`	API key	billing.read	Developers	Return active subscriptions and period-end cancellation fields.
POST	`/rico/sessions`	API key	rico.media or video	Developers	Create a RICO Supercomputer session with brief, recipe, inputs, cost estimate, messages, and pending steps.
POST	`/rico/sessions/:id/approve`	API key	rico.media or video	Developers	Approve a RICO Supercomputer session, deduct RICO media credits, and queue deterministic execution.
POST	`/rico/mcp`	API key	rico.media or video	Developers	Call the RICO MCP endpoint with tools such as rico_estimate_cost, rico_apply_effect, rico_repurpose, and rico_get_job.
POST	`/generate/video`	API key	video	Developers	Start text-to-video or image-to-video generation with model, aspect ratio, duration, mode, image URL, and sound options.Send Idempotency-Key for user-triggered create/retry requests.
POST	`/kling/videos/effects`	API key	video	Developers	Queue a Kling Video Effects Center task by effect_scene with single-image or dual-image input.
POST	`/kling/lipsync`	API key	video	Developers	Queue Kling advanced lip-sync and track it through the provider task registry.
POST	`/kling/multi-elements`	API key	video	Developers	Queue a Kling multi-elements video editing task.
POST	`/repurpose`	API key	video	Developers	Start a repurposing pipeline from a YouTube or file URL with optional language.Send Idempotency-Key for user-triggered create/retry requests.
GET	`/rico/sessions`	API key	rico.media or video	Developers	List recent RICO Supercomputer sessions for the authenticated account.
GET	`/rico/sessions/:id`	API key	rico.media or video	Developers	Fetch a RICO Supercomputer session with messages, workflow steps, status, and current assets.
GET	`/rico/sessions/:id/events`	API key	rico.media or video	Developers	Fetch a polling-friendly RICO session timeline with messages, steps, and assets.
POST	`/rico/sessions/:id/messages`	API key	rico.media or video	Developers	Add a user or assistant message to an existing RICO session.
GET	`/rico/sessions/:id/assets`	API key	rico.media or video	Developers	List media assets produced by a RICO Supercomputer session.
GET	`/rico/assets`	API key	rico.media or video	Developers	List recent RICO media assets.
POST	`/rico/assets`	API key	rico.media or video	Developers	Upload or register a RICO media asset by multipart file, URL, or data URL.
GET	`/rico/assets/:id`	API key	rico.media or video	Developers	Fetch one RICO media asset by id.
GET	`/generation/:id`	API key	video	Developers	Fetch a generation record, status, output video URL, metadata, file size, and any error message.
GET	`/kling/tasks/:id`	API key	video	Developers	Fetch any Kling provider task by local task ID, provider task ID, or external task ID.
GET	`/repurpose`	API key	video	Developers	List recent repurpose jobs.
GET	`/repurpose/:id`	API key	video	Developers	Fetch a repurposing task with rendered clips, transcripts, segments, viral scores, and output URLs.
POST	`/repurpose/:id/retry`	API key	video	Developers	Retry a failed repurpose job.
DELETE	`/repurpose/:id`	API key	video	Developers	Delete a repurpose job by id.
PUT	`/repurpose/:task_id/clip/:clip_id`	API key	video	Developers	Update a clip edit state for a repurpose task.
POST	`/repurpose/:task_id/clip/:clip_id/render-captions`	API key	video	Developers	Render a repurpose clip with timeline edits and optional burned captions.
POST	`/images/generate`	API key	video	Developers	Generate images from a prompt, reference image, palette, model, and resolution. Kling models are queued through the provider task registry.
POST	`/kling/images/generations`	API key	video	Developers	Queue Kling image generation directly with model_name, n, aspect ratio, references, and provider task status.
POST	`/kling/general/ai-multi-shot`	API key	video	Developers	Queue Kling AI Multi-Shot from one frontal image and store all returned shots in the media library.
POST	`/kling/images/kolors-virtual-try-on`	API key	video	Developers	Queue Kling Kolors virtual try-on with human and cloth images.
POST	`/images/edit`	API key	video	Developers	Edit an image with a prompt and source image URL.
POST	`/images/enhance`	API key	video	Developers	Enhance or upscale an image asset.
POST	`/images/faceswap`	API key	video	Developers	Swap a face between target and source images.
POST	`/images/3d-angles`	API key	video	Developers	Generate a 3D/360-style video from an image.
POST	`/images/character-gen`	API key	video	Developers	Generate a consistent character from a prompt and optional reference image.
POST	`/kling/image-recognize`	API key	video	Developers	Run Kling image recognition and segmentation utilities for object, head, face, and clothing masks.
POST	`/kling/audio/text-to-audio`	API key	video	Developers	Queue Kling text-to-audio generation and persist the generated audio in the media library.
POST	`/kling/audio/video-to-audio`	API key	video	Developers	Queue Kling video-to-audio generation for a supplied video source.
POST	`/kling/lipsync/identify-face`	API key	video	Developers	Identify faces for Kling lip-sync workflows before creating the final lip-sync task.
POST	`/kling/voices`	API key	video	Developers	Create a Kling custom voice task.
GET	`/kling/voices`	API key	video	Developers	List Kling custom voices.
GET	`/kling/voices/:id`	API key	video	Developers	Fetch one Kling custom voice task by id.
POST	`/kling/voices/delete`	API key	video	Developers	Queue deletion of a Kling custom voice.
GET	`/kling/voices/presets`	API key	video	Developers	List Kling preset voices available for audio and avatar tools.
POST	`/kling/elements`	API key	video	Developers	Create Kling advanced custom elements for multi-element video editing.
GET	`/kling/elements`	API key	video	Developers	List Kling advanced custom elements.
GET	`/kling/elements/:id`	API key	video	Developers	Fetch one Kling advanced custom element by id.
POST	`/kling/multi-elements/init-selection`	API key	video	Developers	Initialize Kling multi-elements selections for editing workflows.
POST	`/kling/multi-elements/add-selection`	API key	video	Developers	Add a Kling multi-elements selection.
POST	`/kling/multi-elements/delete-selection`	API key	video	Developers	Delete a Kling multi-elements selection.
POST	`/kling/multi-elements/clear-selection`	API key	video	Developers	Clear all Kling multi-elements selections.
POST	`/kling/multi-elements/preview-selection`	API key	video	Developers	Preview a Kling multi-elements selection.
GET	`/kling/multi-elements`	API key	video	Developers	List Kling multi-elements tasks.
GET	`/kling/multi-elements/:id`	API key	video	Developers	Fetch one Kling multi-elements task by id.
POST	`/repurpose/tts`	API key	video	Developers	Generate speech audio from text and a voice selection.
POST	`/repurpose/enhance-audio`	API key	video	Developers	Queue audio enhancement for a source video.
POST	`/repurpose/lipsync`	API key	video	Developers	Synchronize a video with a supplied audio track.
POST	`/repurpose/recast`	API key	video	Developers	Replace or recast a character in a source video with a target image.
POST	`/video/transitions`	API key	video	Developers	Create transitions across two or more input video URLs.
POST	`/video/edit`	API key	video	Developers	Edit an existing video with a natural-language prompt.
POST	`/ads/generate`	API key	video	Developers	Generate an ad creative from a product URL.
GET	`/broll/search`	API key	video	Developers	Search for B-roll media for repurpose and editing workflows.
GET	`/ricochet/budget`	API key	ricochet_code	Ricochet clients	Check ricochet_code credits, plan, window limits, task limits, and upgrade URL before a hosted AI run.
POST	`/ricochet/usage/quote`	API key	ricochet_code	Ricochet clients	Quote and reserve hosted Ricochet usage before calling an upstream model.Use before the upstream hosted-model call.
POST	`/ricochet/usage/report`	API key	ricochet_code	Ricochet clients	Report hosted model usage with idempotency, token counts, provider, model, and billing metadata.
GET	`/ricochet/usage`	API key	ricochet_code	Ricochet clients	List Ricochet hosted usage events with filters for session, run, provider, model, and limit.
POST	`/ricochet/usage/approve-premium`	API key	ricochet_code	Ricochet clients	Store a temporary approval for premium model usage in a task, run, or session.
GET	`/ricochet/sessions`	User token	-	Ricochet clients	List Ricochet IDE and device sessions for the current user.
DELETE	`/ricochet/sessions/:id`	User token	-	Ricochet clients	Revoke a Ricochet IDE or device session.
POST	`/ricochet/openai/v1/chat/completions`	API key	ricochet_code	Ricochet clients	Legacy Ricochet hosted coding chat completions alias. Use /chat/completions on the AI Gateway for new generic model integrations.Compatibility route for existing Ricochet clients.
POST	`/ricochet/openai/v1/responses`	API key	ricochet_code	Ricochet clients	Ricochet hosted coding Responses API alias for clients that use OpenAI Responses.Compatibility route for existing Ricochet clients.
GET	`/social/accounts`	API key	social	Developers	List social accounts connected to the current user.
POST	`/social/accounts/connect`	API key	social	Developers	Connect a social account record for YouTube, Instagram, TikTok, LinkedIn, X, or Facebook.
DELETE	`/social/accounts/:id`	API key	social	Developers	Disconnect a social account by id.
GET	`/social/posts`	API key	social	Developers	List scheduled posts, optionally filtered by date range.
POST	`/social/posts`	API key	social	Developers	Create a draft or scheduled post with content, hashtags, media, accounts, and platform options.
PUT	`/social/posts/:id`	API key	social	Developers	Update post content, hashtags, schedule, or status.
DELETE	`/social/posts/:id`	API key	social	Developers	Delete a scheduled post and clear its account associations.
POST	`/social/generate-caption`	API key	social	Developers	Generate a social caption from a transcript or media id.
POST	`/social/upload`	API key	social	Developers	Upload an MP4 for social publishing workflows.
POST	`/import/auto`	API key	social	Developers	Register a platform channel or folder for automated video import monitoring.
GET	`/config/pricing`	None	-	Developers	Return pricing.yaml-backed generation costs, subscription plans, credit packages, Ricochet plans, and model billing policy.

POST/auth/device/code

Create a device code, user code, verification URL, expiry, and polling interval.

Auth: NoneScope: -Audience: Developers

POST/auth/device/token

Exchange an approved device code for access and refresh tokens.

Auth: NoneScope: -Audience: Developers

POST/auth/refresh

Rotate a refresh token and receive a fresh access token.

Auth: NoneScope: -Audience: Developers

GET/users/me

Return the authenticated user profile used for billing and ownership.

Auth: Bearer tokenScope: -Audience: Developers

POST/auth/api-keys

Issue an organization API key such as grik_live_... for server-side integrations.

Auth: User tokenScope: -Audience: Developers

GET/auth/api-keys

List active and revoked API keys without exposing the raw secret.

Auth: User tokenScope: -Audience: Developers

PATCH/auth/api-keys/:id

Update key metadata, scopes, environment, status, or spend controls without revealing the raw secret.

Auth: User tokenScope: -Audience: Developers

DELETE/auth/api-keys/:id

Revoke an API key by id. Revoked keys fail authentication immediately.

Auth: User tokenScope: -Audience: Developers

GET/models

List AI Gateway models with provider availability, context length, pricing, capabilities, and data policy metadata.

Auth: Optional bearerScope: -Audience: Developers

GET/rico/models

List RICO recipes, workflows, and effect presets. Optional type filters include recipe, workflow, and effect.

Auth: API keyScope: rico.media or videoAudience: Developers

GET/rico/models/:id

Inspect one RICO recipe, workflow, model, or effect preset by id.

Auth: API keyScope: rico.media or videoAudience: Developers

GET/rico/workflows

List RICO Supercomputer recipes and allowlisted executor workflows for web, MCP, CLI, and API use.

Auth: API keyScope: rico.media or videoAudience: Developers

GET/rico/recipes

List RICO Supercomputer recipes only.

Auth: API keyScope: rico.media or videoAudience: Developers

POST/chat/completions

Run OpenAI/OpenRouter-compatible chat completions through the GRIKAI AI Gateway with streaming, tools, fallbacks, and provider routing.Send Idempotency-Key for user-triggered create/retry requests.

Auth: API keyScope: ai.gatewayAudience: Developers

POST/responses

Run OpenAI Responses-compatible requests through the GRIKAI AI Gateway with the same model catalog, routing, fallbacks, and usage billing.Send Idempotency-Key for user-triggered create/retry requests.

Auth: API keyScope: ai.gatewayAudience: Developers

POST/responses/input_tokens

Count Responses input tokens before execution. OpenAI-backed models use upstream token counting; other providers return an estimated count.Use before the upstream hosted-model call.

Auth: API keyScope: ai.gatewayAudience: Developers

GET/ai-gateway/balance

Return balance_micros, pending reservation micros, available balance, and USD display values.

Auth: API keyScope: ai.gatewayAudience: Developers

GET/ai-gateway/pricing

Return AI Gateway packages, platform fee, minimum charge, and customer-visible model pricing.

Auth: Optional bearerScope: -Audience: Developers

POST/ai-gateway/quote

Estimate tokens, customer charge, available balance, spend-limit decision, and fallback-route charge before execution. This does not reserve or charge balance.Use before the upstream hosted-model call.

Auth: API keyScope: ai.gatewayAudience: Developers

GET/ai-gateway/usage

List AI Gateway usage events with provider, model, status, date, and limit filters.

Auth: API keyScope: ai.gatewayAudience: Developers

GET/ai-gateway/usage/:id

Fetch one usage event with token counts, provider cost, platform fee, charge, route attempts, and metadata.

Auth: API keyScope: ai.gatewayAudience: Developers

GET/ai-gateway/reservations

List active, failed, and settled preflight reservations for idempotency and pending-balance debugging.

Auth: API keyScope: ai.gatewayAudience: Developers

GET/keys

List account API keys without exposing the raw secret.

Auth: User tokenScope: -Audience: Developers

POST/keys

Create an API key with ai.gateway scope and optional spend controls. The raw key is returned only once.

Auth: User tokenScope: -Audience: Developers

PATCH/keys/:id

Update key name, status, scopes, environment, spend limit, or reset interval without rotating the secret.

Auth: User tokenScope: -Audience: Developers

DELETE/keys/:id

Revoke an API key by id.

Auth: User tokenScope: -Audience: Developers

GET/billing/credits

Return product credit wallets plus ai_gateway_balance_micros.

Auth: API keyScope: billing.readAudience: Developers

GET/billing/transactions

List billing transactions with optional product filter.

Auth: API keyScope: billing.readAudience: Developers

GET/billing/entitlements

Return active subscriptions and period-end cancellation fields.

Auth: API keyScope: billing.readAudience: Developers

POST/rico/sessions

Create a RICO Supercomputer session with brief, recipe, inputs, cost estimate, messages, and pending steps.

Auth: API keyScope: rico.media or videoAudience: Developers

POST/rico/sessions/:id/approve

Approve a RICO Supercomputer session, deduct RICO media credits, and queue deterministic execution.

Auth: API keyScope: rico.media or videoAudience: Developers

POST/rico/mcp

Call the RICO MCP endpoint with tools such as rico_estimate_cost, rico_apply_effect, rico_repurpose, and rico_get_job.

Auth: API keyScope: rico.media or videoAudience: Developers

POST/generate/video

Start text-to-video or image-to-video generation with model, aspect ratio, duration, mode, image URL, and sound options.Send Idempotency-Key for user-triggered create/retry requests.

Auth: API keyScope: videoAudience: Developers

POST/kling/videos/effects

Queue a Kling Video Effects Center task by effect_scene with single-image or dual-image input.

Auth: API keyScope: videoAudience: Developers

POST/kling/lipsync

Queue Kling advanced lip-sync and track it through the provider task registry.

Auth: API keyScope: videoAudience: Developers

POST/kling/multi-elements

Queue a Kling multi-elements video editing task.

Auth: API keyScope: videoAudience: Developers

POST/repurpose

Start a repurposing pipeline from a YouTube or file URL with optional language.Send Idempotency-Key for user-triggered create/retry requests.

Auth: API keyScope: videoAudience: Developers

GET/rico/sessions

List recent RICO Supercomputer sessions for the authenticated account.

Auth: API keyScope: rico.media or videoAudience: Developers

GET/rico/sessions/:id

Fetch a RICO Supercomputer session with messages, workflow steps, status, and current assets.

Auth: API keyScope: rico.media or videoAudience: Developers

GET/rico/sessions/:id/events

Fetch a polling-friendly RICO session timeline with messages, steps, and assets.

Auth: API keyScope: rico.media or videoAudience: Developers

POST/rico/sessions/:id/messages

Add a user or assistant message to an existing RICO session.

Auth: API keyScope: rico.media or videoAudience: Developers

GET/rico/sessions/:id/assets

List media assets produced by a RICO Supercomputer session.

Auth: API keyScope: rico.media or videoAudience: Developers

GET/rico/assets

List recent RICO media assets.

Auth: API keyScope: rico.media or videoAudience: Developers

POST/rico/assets

Upload or register a RICO media asset by multipart file, URL, or data URL.

Auth: API keyScope: rico.media or videoAudience: Developers

GET/rico/assets/:id

Fetch one RICO media asset by id.

Auth: API keyScope: rico.media or videoAudience: Developers

GET/generation/:id

Fetch a generation record, status, output video URL, metadata, file size, and any error message.

Auth: API keyScope: videoAudience: Developers

GET/kling/tasks/:id

Fetch any Kling provider task by local task ID, provider task ID, or external task ID.

Auth: API keyScope: videoAudience: Developers

GET/repurpose

List recent repurpose jobs.

Auth: API keyScope: videoAudience: Developers

GET/repurpose/:id

Fetch a repurposing task with rendered clips, transcripts, segments, viral scores, and output URLs.

Auth: API keyScope: videoAudience: Developers

POST/repurpose/:id/retry

Retry a failed repurpose job.

Auth: API keyScope: videoAudience: Developers

DELETE/repurpose/:id

Delete a repurpose job by id.

Auth: API keyScope: videoAudience: Developers

PUT/repurpose/:task_id/clip/:clip_id

Update a clip edit state for a repurpose task.

Auth: API keyScope: videoAudience: Developers

POST/repurpose/:task_id/clip/:clip_id/render-captions

Render a repurpose clip with timeline edits and optional burned captions.

Auth: API keyScope: videoAudience: Developers

POST/images/generate

Generate images from a prompt, reference image, palette, model, and resolution. Kling models are queued through the provider task registry.

Auth: API keyScope: videoAudience: Developers

POST/kling/images/generations

Queue Kling image generation directly with model_name, n, aspect ratio, references, and provider task status.

Auth: API keyScope: videoAudience: Developers

POST/kling/general/ai-multi-shot

Queue Kling AI Multi-Shot from one frontal image and store all returned shots in the media library.

Auth: API keyScope: videoAudience: Developers

POST/kling/images/kolors-virtual-try-on

Queue Kling Kolors virtual try-on with human and cloth images.

Auth: API keyScope: videoAudience: Developers

POST/images/edit

Edit an image with a prompt and source image URL.

Auth: API keyScope: videoAudience: Developers

POST/images/enhance

Enhance or upscale an image asset.

Auth: API keyScope: videoAudience: Developers

POST/images/faceswap

Swap a face between target and source images.

Auth: API keyScope: videoAudience: Developers

POST/images/3d-angles

Generate a 3D/360-style video from an image.

Auth: API keyScope: videoAudience: Developers

POST/images/character-gen

Generate a consistent character from a prompt and optional reference image.

Auth: API keyScope: videoAudience: Developers

POST/kling/image-recognize

Run Kling image recognition and segmentation utilities for object, head, face, and clothing masks.

Auth: API keyScope: videoAudience: Developers

POST/kling/audio/text-to-audio

Queue Kling text-to-audio generation and persist the generated audio in the media library.

Auth: API keyScope: videoAudience: Developers

POST/kling/audio/video-to-audio

Queue Kling video-to-audio generation for a supplied video source.

Auth: API keyScope: videoAudience: Developers

POST/kling/lipsync/identify-face

Identify faces for Kling lip-sync workflows before creating the final lip-sync task.

Auth: API keyScope: videoAudience: Developers

POST/kling/voices

Create a Kling custom voice task.

Auth: API keyScope: videoAudience: Developers

GET/kling/voices

List Kling custom voices.

Auth: API keyScope: videoAudience: Developers

GET/kling/voices/:id

Fetch one Kling custom voice task by id.

Auth: API keyScope: videoAudience: Developers

POST/kling/voices/delete

Queue deletion of a Kling custom voice.

Auth: API keyScope: videoAudience: Developers

GET/kling/voices/presets

List Kling preset voices available for audio and avatar tools.

Auth: API keyScope: videoAudience: Developers

POST/kling/elements

Create Kling advanced custom elements for multi-element video editing.

Auth: API keyScope: videoAudience: Developers

GET/kling/elements

List Kling advanced custom elements.

Auth: API keyScope: videoAudience: Developers

GET/kling/elements/:id

Fetch one Kling advanced custom element by id.

Auth: API keyScope: videoAudience: Developers

POST/kling/multi-elements/init-selection

Initialize Kling multi-elements selections for editing workflows.

Auth: API keyScope: videoAudience: Developers

POST/kling/multi-elements/add-selection

Add a Kling multi-elements selection.

Auth: API keyScope: videoAudience: Developers

POST/kling/multi-elements/delete-selection

Delete a Kling multi-elements selection.

Auth: API keyScope: videoAudience: Developers

POST/kling/multi-elements/clear-selection

Clear all Kling multi-elements selections.

Auth: API keyScope: videoAudience: Developers

POST/kling/multi-elements/preview-selection

Preview a Kling multi-elements selection.

Auth: API keyScope: videoAudience: Developers

GET/kling/multi-elements

List Kling multi-elements tasks.

Auth: API keyScope: videoAudience: Developers

GET/kling/multi-elements/:id

Fetch one Kling multi-elements task by id.

Auth: API keyScope: videoAudience: Developers

POST/repurpose/tts

Generate speech audio from text and a voice selection.

Auth: API keyScope: videoAudience: Developers

POST/repurpose/enhance-audio

Queue audio enhancement for a source video.

Auth: API keyScope: videoAudience: Developers

POST/repurpose/lipsync

Synchronize a video with a supplied audio track.

Auth: API keyScope: videoAudience: Developers

POST/repurpose/recast

Replace or recast a character in a source video with a target image.

Auth: API keyScope: videoAudience: Developers

POST/video/transitions

Create transitions across two or more input video URLs.

Auth: API keyScope: videoAudience: Developers

POST/video/edit

Edit an existing video with a natural-language prompt.

Auth: API keyScope: videoAudience: Developers

POST/ads/generate

Generate an ad creative from a product URL.

Auth: API keyScope: videoAudience: Developers

GET/broll/search

Search for B-roll media for repurpose and editing workflows.

Auth: API keyScope: videoAudience: Developers

GET/ricochet/budget

Check ricochet_code credits, plan, window limits, task limits, and upgrade URL before a hosted AI run.

Auth: API keyScope: ricochet_codeAudience: Ricochet clients

POST/ricochet/usage/quote

Quote and reserve hosted Ricochet usage before calling an upstream model.Use before the upstream hosted-model call.

Auth: API keyScope: ricochet_codeAudience: Ricochet clients

POST/ricochet/usage/report

Report hosted model usage with idempotency, token counts, provider, model, and billing metadata.

Auth: API keyScope: ricochet_codeAudience: Ricochet clients

GET/ricochet/usage

List Ricochet hosted usage events with filters for session, run, provider, model, and limit.

Auth: API keyScope: ricochet_codeAudience: Ricochet clients

POST/ricochet/usage/approve-premium

Store a temporary approval for premium model usage in a task, run, or session.

Auth: API keyScope: ricochet_codeAudience: Ricochet clients

GET/ricochet/sessions

List Ricochet IDE and device sessions for the current user.

Auth: User tokenScope: -Audience: Ricochet clients

DELETE/ricochet/sessions/:id

Revoke a Ricochet IDE or device session.

Auth: User tokenScope: -Audience: Ricochet clients

POST/ricochet/openai/v1/chat/completions

Legacy Ricochet hosted coding chat completions alias. Use /chat/completions on the AI Gateway for new generic model integrations.Compatibility route for existing Ricochet clients.

Auth: API keyScope: ricochet_codeAudience: Ricochet clients

POST/ricochet/openai/v1/responses

Ricochet hosted coding Responses API alias for clients that use OpenAI Responses.Compatibility route for existing Ricochet clients.

Auth: API keyScope: ricochet_codeAudience: Ricochet clients

GET/social/accounts

List social accounts connected to the current user.

Auth: API keyScope: socialAudience: Developers

POST/social/accounts/connect

Connect a social account record for YouTube, Instagram, TikTok, LinkedIn, X, or Facebook.

Auth: API keyScope: socialAudience: Developers

DELETE/social/accounts/:id

Disconnect a social account by id.

Auth: API keyScope: socialAudience: Developers

GET/social/posts

List scheduled posts, optionally filtered by date range.

Auth: API keyScope: socialAudience: Developers

POST/social/posts

Create a draft or scheduled post with content, hashtags, media, accounts, and platform options.

Auth: API keyScope: socialAudience: Developers

PUT/social/posts/:id

Update post content, hashtags, schedule, or status.

Auth: API keyScope: socialAudience: Developers

DELETE/social/posts/:id

Delete a scheduled post and clear its account associations.

Auth: API keyScope: socialAudience: Developers

POST/social/generate-caption

Generate a social caption from a transcript or media id.

Auth: API keyScope: socialAudience: Developers

POST/social/upload

Upload an MP4 for social publishing workflows.

Auth: API keyScope: socialAudience: Developers

POST/import/auto

Auth: API keyScope: socialAudience: Developers

GET/config/pricing

Return pricing.yaml-backed generation costs, subscription plans, credit packages, Ricochet plans, and model billing policy.

Auth: NoneScope: -Audience: Developers

#Browser-session routes

Browser-session routes are documented separately because they rely on the signed-in web session and are not starter server-side API-key integrations.

GET

Endpoint

/gallery

List media gallery items for the current logged-in user.

Auth

Bearer token

API key scope

Audience

Browser session

Parameters

Browser route filters include `kind`, `status`, `sort`, `q`, `limit`, and `offset`.

Request body

No JSON request body.

Response

Returns browser-session data for the signed-in user.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

Browser-session route. Use it from the signed-in web app, not from server-side API-key integrations.

GET

Endpoint

/user/storage

Return storage usage for the current logged-in user.

Auth

Bearer token

API key scope

Audience

Browser session

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

No JSON request body.

Response

Returns browser-session data for the signed-in user.

Errors

Standard API errors use a structured error body with code and message for authentication, scope, not found, conflict, rate limit, and internal failures.

Operations notes

Browser-session route. Use it from the signed-in web app, not from server-side API-key integrations.

Method	Endpoint	Auth	Scope	Audience	Description
GET	`/gallery`	Bearer token	-	Browser session	List media gallery items for the current logged-in user.
GET	`/user/storage`	Bearer token	-	Browser session	Return storage usage for the current logged-in user.

GET/gallery

List media gallery items for the current logged-in user.

Auth: Bearer tokenScope: -Audience: Browser session

GET/user/storage

Return storage usage for the current logged-in user.

Auth: Bearer tokenScope: -Audience: Browser session

#Callbacks and internal routes

Callbacks and internal approval routes are reachable network routes, but only providers or trusted Grik services should call them.

POST

Endpoint

/internal/notifications

Internal GRIKAI service route for notification enqueueing. Not a client integration endpoint.

Auth

Internal

API key scope

Audience

Internal

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

JSON object. See the OpenAPI schema for the exact fields accepted by this operation.

Response

Returns acknowledgement status or provider-specific webhook processing metadata.

Errors

Callback/internal routes use provider or internal-secret validation errors and are not normal client retry surfaces.

Operations notes

Callback/internal route. It is public on the network but not a normal client API.

POST

Endpoint

/webhooks/mailgun

Mailgun provider webhook for email delivery and event notifications.

Auth

Signed callback

API key scope

Audience

Callbacks

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

Provider callback payload. Do not call from client integrations.

Response

Returns acknowledgement status or provider-specific webhook processing metadata.

Errors

Callback/internal routes use provider or internal-secret validation errors and are not normal client retry surfaces.

Operations notes

Callback/internal route. It is public on the network but not a normal client API.

POST

Endpoint

/auth/device/approve

Internal web approval route that links a browser-approved device code to a Grik user.

Auth

Internal

API key scope

Audience

Internal

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

`user_code` plus authenticated user context or internal `user_id`/`email`. This is not a normal client integration endpoint.

Response

Returns acknowledgement status or provider-specific webhook processing metadata.

Errors

Callback/internal routes use provider or internal-secret validation errors and are not normal client retry surfaces.

Operations notes

Callback/internal route. It is public on the network but not a normal client API.

POST

Endpoint

/provider-callbacks/kling

Kling provider callback used to settle asynchronous task status.

Auth

Signed callback

API key scope

Audience

Callbacks

Parameters

Kling provider callbacks require the `token` query parameter matching `KLING_CALLBACK_TOKEN`.

Request body

Provider callback payload. Do not call from client integrations.

Response

Returns acknowledgement status or provider-specific webhook processing metadata.

Errors

Callback/internal routes use provider or internal-secret validation errors and are not normal client retry surfaces.

Operations notes

Callback/internal route. It is public on the network but not a normal client API.

POST

Endpoint

/billing/passimpay/webhook

PassimPay billing webhook used for idempotent payment settlement.

Auth

Signed callback

API key scope

Audience

Callbacks

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

Provider callback payload. Do not call from client integrations.

Response

Returns acknowledgement status or provider-specific webhook processing metadata.

Errors

Billing endpoints return structured API errors such as `invalid_request`, `payment_provider_not_configured`, `payment_provider_unavailable`, `not_found`, and `provider_unavailable`.

Operations notes

Callback/internal route. It is public on the network but not a normal client API.

POST

Endpoint

/billing/paypal/webhook

PayPal billing webhook used for verified payment and subscription settlement.

Auth

Signed callback

API key scope

Audience

Callbacks

Parameters

No path parameters. Some list endpoints support optional filters documented in OpenAPI.

Request body

Provider callback payload. Do not call from client integrations.

Response

Returns acknowledgement status or provider-specific webhook processing metadata.

Errors

Billing endpoints return structured API errors such as `invalid_request`, `payment_provider_not_configured`, `payment_provider_unavailable`, `not_found`, and `provider_unavailable`.

Operations notes

Callback/internal route. It is public on the network but not a normal client API.

Method	Endpoint	Auth	Scope	Audience	Description
POST	`/internal/notifications`	Internal	-	Internal	Internal GRIKAI service route for notification enqueueing. Not a client integration endpoint.
POST	`/webhooks/mailgun`	Signed callback	-	Callbacks	Mailgun provider webhook for email delivery and event notifications.
POST	`/auth/device/approve`	Internal	-	Internal	Internal web approval route that links a browser-approved device code to a Grik user.
POST	`/provider-callbacks/kling`	Signed callback	-	Callbacks	Kling provider callback used to settle asynchronous task status.
POST	`/billing/passimpay/webhook`	Signed callback	-	Callbacks	PassimPay billing webhook used for idempotent payment settlement.
POST	`/billing/paypal/webhook`	Signed callback	-	Callbacks	PayPal billing webhook used for verified payment and subscription settlement.

POST/internal/notifications

Internal GRIKAI service route for notification enqueueing. Not a client integration endpoint.

Auth: InternalScope: -Audience: Internal

POST/webhooks/mailgun

Mailgun provider webhook for email delivery and event notifications.

Auth: Signed callbackScope: -Audience: Callbacks

POST/auth/device/approve

Internal web approval route that links a browser-approved device code to a Grik user.

Auth: InternalScope: -Audience: Internal

POST/provider-callbacks/kling

Kling provider callback used to settle asynchronous task status.

Auth: Signed callbackScope: -Audience: Callbacks

POST/billing/passimpay/webhook

PassimPay billing webhook used for idempotent payment settlement.

Auth: Signed callbackScope: -Audience: Callbacks

POST/billing/paypal/webhook

PayPal billing webhook used for verified payment and subscription settlement.

Auth: Signed callbackScope: -Audience: Callbacks