Objects

Objects asks a model for JSON that matches a JSON Schema and returns the parsed value. You don't choose how: some models only honour a JSON-schema response format and others only a forced tool call, so the API uses whichever path was measured to work for the model you picked.

The schema constrains the model, but you should still validate the value on your side. Models can return values that are valid JSON and fit the schema yet make no sense for your product — a count of 400 images, say.

POST/v1/objects

Create an object

Accepts every attribute of Chat, plus the schema to fill.

Required attributes

Name
model
Type
string
Description
A model id from the catalog.
Name
messages
Type
array
Description
The conversation.
Name
maxTokens
Type
integer
Description
Up to 32000. If the output is cut off, the request fails with TRUNCATED rather than returning broken JSON.
Name
name
Type
string
Description
A snake_case name for the object, such as image_recipe.
Name
schema
Type
object
Description
A JSON Schema whose top level is "type": "object". Objects are closed automatically (additionalProperties: false) unless you set it.

Optional attributes

Name
description
Type
string
Description
What the object is for, up to 500 characters.
Name
mode
Type
string
Description
json_schema or tool. Overrides the path from the catalog; only needed for models outside it.

Request

POST

/v1/objects

curl https://api.llm.vovix.io/v1/objects \
  -H "x-api-key: $LLM_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "google.gemma-3-12b-it",
    "name": "image_recipe",
    "schema": {
      "type": "object",
      "properties": {
        "prompt": { "type": "string" },
        "aspect": { "type": "string", "enum": ["square", "wide", "tall"] }
      },
      "required": ["prompt", "aspect"]
    },
    "messages": [
      { "role": "user", "content": "A wide shot of a red fox in snow" }
    ],
    "maxTokens": 200
  }'

Response

{
  "model": "google.gemma-3-12b-it",
  "value": { "prompt": "A red fox walking through deep snow, wide landscape", "aspect": "wide" },
  "mode": "json_schema",
  "usage": { "inputTokens": 58, "outputTokens": 19 },
  "costUsd": 0.00001073,
  "latencyMs": 704,
  "requestId": "<x-request-id returned by Mantle>"
}

Response

Name
value
Type
object
Description
The parsed object.
Name
mode
Type
string
Description
The path that produced it: json_schema or tool.
Name
usage, costUsd, latencyMs, requestId
Description
As on Chat.

Errors specific to objects

422 TRUNCATED — output stopped at maxTokens. Raise maxTokens; the prompt is not the problem.
502 BAD_OUTPUT — the model returned text that isn't JSON, or called a different tool. The tokens were still spent and counted.
400 BAD_REQUEST — mode is missing for a model outside the catalog.