Quickstart

This guide gets you from nothing to a working model call. You'll check the API is up, fetch your service's API key, and send your first chat request.

Check the API is up

/health needs no key, so it's the quickest way to confirm the base URL resolves and the Lambda is running.

curl https://api.llm.vovix.io/v1/health

{ "ok": true, "models": 10, "region": "us-east-1" }

Get your API key

Keys are issued by the Vovix admin and shown once, when they are created. A key is named llm::<role>::<app>::<email> with your app as its customerId. With access to the AWS account, find your app's key id and read its value:

aws apigateway get-api-keys --customer-id pixora \
  --query "items[?starts_with(name, 'llm::')].[id,name]" --output text

aws apigateway get-api-key --api-key <keyId> --include-value \
  --query value --output text

Store the value as a secret in your service (for example LLM_API_KEY). See Authentication for how keys map to projects.

Send your first request

Pick a model from the catalog — google.gemma-3-12b-it is a good default: cheap, fast, and it accepts images.

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",
    "messages": [{ "role": "user", "content": "What is the capital of Japan? One word." }],
    "maxTokens": 16
  }'

{
  "model": "google.gemma-3-12b-it",
  "text": "Tokyo",
  "toolCalls": [],
  "finishReason": "stop",
  "usage": { "inputTokens": 22, "outputTokens": 3 },
  "costUsd": 0.00000285,
  "latencyMs": 612,
  "requestId": "<x-request-id returned by Mantle>"
}

maxTokens is required on every call. It is the hard ceiling on what one request can cost, and Mantle reserves quota against it before running the model.

What's next?

• Authentication — how your key maps to your service and its Mantle project
• Models — prices and capabilities of every model you can call
• Objects — get JSON that matches a schema instead of free text
• Errors — the error codes to handle, and which ones to retry