Chat
A chat request sends a conversation to a model and returns one complete reply, with the tokens it used and what it cost. The request shape is the same for every model in the catalog.
The message model
A conversation is an array of messages, oldest first.
Properties
- Name
role- Type
- string
- Description
One of
system,user,assistantortool.
- Name
content- Type
- string | array | null
- Description
Text, or an array of content parts:
{ "type": "text", "text": "..." }and{ "type": "image_url", "image_url": { "url": "..." } }. The URL can behttps://or adata:URI.nullonly on assistant messages that carrytool_calls.
- Name
tool_calls- Type
- array
- Description
Assistant messages only: the tool calls the model made. See Agents.
- Name
tool_call_id- Type
- string
- Description
Tool messages only: the id of the tool call this message answers.
- Name
name- Type
- string
- Description
Optional name of the participant.
Image parts only work with models that accept images — see the catalog.
Create a completion
Runs the conversation through the model and returns the reply. The body is validated strictly: an unknown field returns 400 INVALID. To let the model call tools, use Agents.
Required attributes
- Name
model- Type
- string
- Description
A model id from the catalog.
- Name
messages- Type
- array
- Description
The conversation, at least one message.
- Name
maxTokens- Type
- integer
- Description
The most output tokens this call may generate, up to
32000. Reasoning models count reasoning tokens toward it.
Optional attributes
- Name
system- Type
- string
- Description
Instructions for the model. Equivalent to a leading
systemmessage.
- Name
temperature- Type
- number
- Description
Sampling temperature,
0to2.
- Name
topP- Type
- number
- Description
Nucleus sampling,
0to1.
- Name
stop- Type
- array
- Description
Up to four sequences that end generation.
- Name
reasoningEffort- Type
- string
- Description
low,mediumorhigh. For reasoning models such as gpt-oss and GPT-5.6 Luna.
- Name
tag- Type
- string
- Description
A label for the feature making the call, such as
caption.generate. It appears in the API's logs so spend can be broken down by feature. Up to 64 characters.
- Name
userId- Type
- string
- Description
Your end user whose credits pay for the call. Ignored unless your service meters credits.
Request
curl https://api.llm.vovix.io/v1/chat \
-H "x-api-key: $LLM_API_KEY" \
-H "content-type: application/json" \
-d '{
"model": "google.gemma-3-12b-it",
"system": "You write short, vivid image captions.",
"messages": [
{ "role": "user", "content": "A red fox in a snowy forest at dawn" }
],
"maxTokens": 120,
"tag": "caption.generate"
}'
Response
{
"model": "google.gemma-3-12b-it",
"text": "Dawn light catches a red fox mid-step, its breath a pale cloud against the snow-heavy pines.",
"toolCalls": [],
"finishReason": "stop",
"usage": { "inputTokens": 31, "outputTokens": 24 },
"costUsd": 0.00000975,
"latencyMs": 842,
"requestId": "<x-request-id returned by Mantle>"
}
Response
- Name
model- Type
- string
- Description
The model that answered.
- Name
text- Type
- string
- Description
The reply.
- Name
reasoning- Type
- string
- Description
Reasoning text, when the model returns it.
- Name
toolCalls- Type
- array
- Description
Always empty on this endpoint.
- Name
finishReason- Type
- string
- Description
stopwhen the model finished,lengthwhen it hitmaxTokens.
- Name
usage- Type
- object
- Description
inputTokensandoutputTokens. Absent only if the model didn't report usage.
- Name
costUsd- Type
- number
- Description
Tokens multiplied by the catalog price. Absent when usage is absent — never a guessed zero.
- Name
latencyMs- Type
- integer
- Description
Time spent on the model call, retries included.
- Name
requestId- Type
- string
- Description
Upstream request id. Include it when reporting a problem.
Stream a completion
The same request as POST /v1/chat, answered as server-sent events while the model writes. Use it when a person is watching the reply appear, or when the output is too long to finish within 26 seconds — a stream may run for up to 5 minutes.
Anything refused before the model is called — the key, the body, the model, the budget, the credits — is a normal JSON error with its real status, exactly like /v1/chat. Once the stream has started the status is already 200, so a failure after that arrives as an error event carrying the status /v1/chat would have returned.
Events
- Name
text- Type
- event
- Description
{ "delta": "..." }— the next piece of the reply.
- Name
reasoning- Type
- event
- Description
{ "delta": "..." }— the next piece of reasoning, for models that emit it.
- Name
done- Type
- event
- Description
The whole
/v1/chatresponse body: text, usage, cost, credits. The last event of a successful stream.
- Name
error- Type
- event
- Description
{ "status": 504, "error": { "code": "TIMEOUT", "message": "..." } }— the last event of a failed stream. See Errors.
Every stream ends with exactly one done or error. A stream that ends without either was cut off.
How finely text is split depends on the model upstream: Gemma arrives a few words at a time, while gpt-oss arrives in one or two large pieces.
Request
curl -N https://api.llm.vovix.io/v1/chat/stream \
-H "x-api-key: $LLM_API_KEY" \
-H "content-type: application/json" \
-d '{
"model": "google.gemma-3-12b-it",
"messages": [{ "role": "user", "content": "Write a haiku about foxes" }],
"maxTokens": 120
}'
Response
event: text
data: {"delta":"Red "}
event: text
data: {"delta":"fox in the snow"}
event: done
data: {"model":"google.gemma-3-12b-it","text":"Red fox in the snow…","finishReason":"stop","usage":{"inputTokens":14,"outputTokens":19},"costUsd":0.0000067,…}
Send an image
Mix text and image parts in one user message. The model must accept images.
Request body
{
"model": "google.gemma-3-12b-it",
"messages": [
{
"role": "user",
"content": [
{ "type": "image_url", "image_url": { "url": "https://example.com/fox.jpg" } },
{ "type": "text", "text": "Describe this photo in one sentence." }
]
}
],
"maxTokens": 120
}