Reference Chat completions

Chat completions

Sends a conversation to any chat model in OpenAI's Chat Completions format and returns its reply, whole or streamed.

POSThttps://api.runmoth.si/v1/chat/completions

Body

modelrequired

A chat model ID from the catalog.

messagesrequired

The conversation, with roles system, developer, user, assistant and tool. A user message can hold text and image_url parts, as a link or as base64 data.

max_tokensinteger

The longest reply, in tokens, held in full until the call settles. When you send neither this nor max_completion_tokens, the reply stops at 4,096 tokens with finish_reason length. The models that reason first, grok-4.7, deepseek-v4.1-flash and kimi-k3, hold and may bill up to 2,048 output tokens even when this is smaller, though the reply you see stops here.

max_completion_tokensinteger

Read when max_tokens is absent.

streamboolean

Sends the reply as it is written. Chat and streaming shows how to read it.

stream_optionsobject

include_usage set to true adds one last chunk with the token counts and charged_micros.

temperaturenumber

From 0 to 2, sent where capabilities.sampling_params is true and dropped without an error elsewhere. On Claude models a value above 1 becomes 1.

top_pnumber

From 0 to 1, sent where temperature is.

stopstring or array

Text that ends the reply. The GPT, Grok, DeepSeek and Kimi models refuse it.

toolsarray

Functions the model may call, on models whose capabilities.tools is true.

tool_choicestring or object

auto, none, required or a named function. required and a named function need capabilities.forced_tool_choice.

parallel_tool_callsboolean

False asks for one tool call at a time.

response_formatobject

text, json_object or json_schema, as far as the model takes it. What is removed lists which.

web_search_optionsobject

Turns on web search on models that have it.

presence_penalty, frequency_penaltynumber

Sent to the Gemini models and dropped elsewhere.

seedinteger

Sent to the Gemini models and dropped elsewhere.

ninteger

Must be 1 when sent.

Reply

The reply is a usual chat completion. Its id and model are Moth's, usage counts only your own tokens, finish_reason is stop, length, tool_calls or content_filter, and the moth-charged-micros header says what the call cost.

Errors

400invalid_request_errorThe body isn't valid, the model can't take a setting, or the conversation is longer than its context

401authentication_errorThe key is missing, revoked or expired

402insufficient_creditThe balance or the key's cap can't cover the call's hold

403permission_errorThe key may not use this model

404not_found_errorThe model isn't a chat model in the catalog

429rate_limit_errorToo many calls from the key or the account, or to the model, so wait for retry-after when it is sent

529overloaded_errorThe model is paused, or busy or down at its host, so choose another or wait for retry-after when it is sent