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, assistant or tool.
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 be https:// or a data: URI. null only on assistant messages that carry tool_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.

POST/v1/chat

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 system message.
Name
temperature
Type
number
Description
Sampling temperature, 0 to 2.
Name
topP
Type
number
Description
Nucleus sampling, 0 to 1.
Name
stop
Type
array
Description
Up to four sequences that end generation.
Name
reasoningEffort
Type
string
Description
low, medium or high. 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

POST

/v1/chat

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
stop when the model finished, length when it hit maxTokens.
Name
usage
Type
object
Description
inputTokens and outputTokens. 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.

POST/v1/chat

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
}