ai

POST /v1/ai/inference/chat

Run one chat completion on an open model, paid from Zinn® AI credits.

All ai endpoints

All developer docs →

Zinn®, our Viking, hammering at his anvil beside an API endpoint sending events to several listeners.

Authentication

Send an API key as a bearer token. The key must carry the sites.create permission; a key without it is refused with 403, not 404.

Where your organisation id goes

This endpoint takes org_id as a field in the JSON body.

Your organisation id is on the API keys screen in your dashboard, beside the key itself. It is the same id in every call you make.

Try it

Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.

curl -X POST https://api.zinndigital.com/v1/ai/inference/chat \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "messages": <AiInferenceMessage[]> }'

Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console

Details

Serverless AI inference for Zinn® AI Hosting plans (every AI Hosting plan grants serverless_inference). Runs in the request, on actual tokens, billed from the org's Zinn® AI credits: plan-included credits first spend here (this is an AI Hosting surface), then bought top-up credit. The platform's small daily included allowance never funds it, and a customer's own provider key is not used. Gates, each before anything is sent or charged: the plan grants serverless_inference (else 422 FEATURE_NOT_INCLUDED); the model is offered and priced (else 422, refusal.aiInference.unknownModel); the org is in good standing (else 422 AI_NOT_IN_GOOD_STANDING); credit is left (else 422 AI_CREDIT_REQUIRED, details[].can_buy). An answer that stops at the caller's own max_output_tokens before it finishes (a reasoning model can spend a small cap thinking) answers 422 with details[] {field: max_output_tokens, maximum} and a failure of class refused, code output_cap_reached (aiError.outputCapReached): raise the cap and send it again. Any other failed model call answers 503 with a failure whose class is our_fault and names no supplier. Neither charges anything. At most 64 messages of 32,000 characters; max_output_tokens 1 to 4,096 (default 2,048). A reasoning model's thinking is off unless reasoning is true; opted in, the thinking counts against max_output_tokens and every token is billed. Requires sites.create.

Request body

NameTypeRequiredWhat it is
org_idUuidNoUUIDv7 identifier — sortable by creation time (docs/02 §8).
modelstringNoA model from GET /v1/ai/inference/models; empty means the default.
messagesAiInferenceMessage[]Yes—
max_output_tokensintegerNo—
reasoningbooleanNoLet a reasoning model think before it answers. Off by default, because the thinking is output tokens: opted in, it counts against max_output_tokens and is billed like the…

Response

NameTypeRequiredWhat it is
modelstringYes—
messageobjectYes—
finish_reasonstringYes—
usageobjectYes—
charged_microsintegerYesWhat this call charged, in USD micros.
balance_microsintegerYesThe org's Zinn® AI credit balance after the call, in USD micros.

Errors this endpoint can return

401 · 403 · 422 · 429 · 503