AI API

Base path: /api/ai

The AI endpoints power the in-editor assistant and media accessibility helpers. The provider registry and media-search tools are built from the deployment’s configuration; authentication and stream access go through the IAM/streams repositories; token budgets and rate limits use the cache/KV service.

These endpoints are only available when the deployment configures an AI provider — see System requirements.

Chat

  • POST /api/ai/chat — a streaming chat completion for the assistant.
    • Body: { "messages": UIMessage[], "blocks": Node[] } — the conversation plus the current document blocks, which give the assistant live context.
    • The assistant can call editing and media tools (including media search and, when enabled, web search) and returns a streamed response.
    • Token budgets act as a circuit breaker: when a provider’s daily budget is exhausted the endpoint returns 503 Service Unavailable.

Anonymous playground

When the deployment enables anonymous access, unauthenticated chat requests are allowed with separate playground limits:

  • Requests are rate-limited by client fingerprint; exceeding the limit returns 429 Too Many Requests with a Retry-After header. Remaining quota is reported in the x-ratelimit-remaining-hour and x-ratelimit-remaining-day headers.
  • Input is moderated; flagged content is rejected with 400.
  • Generated media is inlined as data URLs and never persisted.

Without anonymous access enabled, chat requires an authenticated session (401 otherwise).

Media generation

Both endpoints require an authenticated session.

  • POST /api/ai/generate/alt-text — generate alternative text for an image.

    • Body: { "media_url"?: string, "stream_id"?: string, "lang"?: string } — provide either a stream_id (a stream from the Media streams API) or a direct media_url. lang defaults to "en".
    • Response: { "data": string }.

  • POST /api/ai/generate/text-tracks — generate text tracks (captions/transcript) for an audio or video stream.

    • Body: { "stream_id": string, "lang"?: string }. lang defaults to "en".