AI

Create a chat completion

OpenAI-compatible completion. A successful request is ALWAYS answered with an SSE stream (text/event-stream), regardless of the stream flag: a meta event, then content/tool_use events carrying usage/credits, terminated by data: [DONE]. The terminal event carries stopReason; treat max_tokens as a TRUNCATED reply rather than a complete one, and note that omitting max_tokens on the request lets the server size the output ceiling for the model (recommended for reasoning models, which spend thinking tokens inside that ceiling). A message content may be a string or an array of parts; image parts are accepted in OpenAI Chat (image_url), OpenAI Responses (input_image) or Anthropic (image with a source) form and are translated to whatever the target model speaks. Authenticate with an API key (b4m_live_) or a JWT.

TOOL SEARCH. On a model whose GET /api/v1/models row has supports_tool_search: true and backend: "anthropic", a tools entry may set toolSchema.defer_loading: true, and a { "serverTool": { "type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex" } } (or the bm25 pair) entry adds Anthropic's tool search, so deferred definitions load only when the model searches for them. The stream then carries provider_block events ({ type, provider: "anthropic", block }) for the server-run search; echo each block back verbatim, in order, in the assistant messages content of the next request, and never answer one with a tool_result. When the server-run search loop hits its iteration limit the stream ends with stopReason: "pause_turn"; continue by re-sending the conversation with that assistant turn's provider blocks echoed. A client-side search may return { "type": "tool_reference", "tool_name": "..." } blocks inside a tool_result's content. On every other model, Bedrock-served Claude included, defer_loading is ignored (every tool is sent as usual) and a server tool, a tool_reference or an echoed tool search block is refused with a 400 rather than run without it.

ERRORS. Everything checked before the model provider is called fails with a JSON error body and a real HTTP status, before any stream opens: a malformed or otherwise invalid request or an unknown model 400 (errorCode: "unknown_model" for the latter), a bad credential 401, a key without a required scope 403 (with required_scopes), a body over 25 MB 413, a body that fails schema validation 422, insufficient credits 422 with errorCode: "insufficient_credits" (personal or org balance, or an org per-member credit cap), a rate limit 429 with Retry-After, and a catalogued model whose provider is not configured on this deployment 503 with errorCode: "provider_not_configured" (retryable). Once the stream has opened the status stays 200 and a failure arrives as one terminal in-band error event. Branch on that event's code, never on message, which is prose and may change: insufficient_credits (buy credits) when credits run out mid-generation, provider_rejected when the model provider refused our credentials, content_blocked when the model declined the request (do not retry it unchanged), and provider_error for any other provider failure. Treat code as optional.

post/api/ai/v1/completions

Request

  • Base URL: https://your-deployment.example.com
  • URL: https://your-deployment.example.com/api/ai/v1/completions
  • Auth: one of:
    • HTTP bearer
    • API key in header x-api-key

Request body

modelstring required
streamboolean
temperaturenumber
max_tokensnumber

Example request

{
  "model": "claude-opus-4-8",
  "messages": [
    {
      "role": "user",
      "content": "How do I reset my password?"
    }
  ],
  "max_tokens": 500
}

Response

SSE stream of completion events (see the CompletionStreamEvent shape).

Changes

No recorded changes to this operation across all 2 revisions of this API.