LLM Endpoints

Generation and embeddings are part of All tools. A start needs the relevant scope and enough credits, and the tool must be available in /v1/health. Free credits also follow the free limits. The model catalog is readable separately.

The LLM API exposes provider-neutral model aliases for text generation, structured JSON output, declared tool calls, and embeddings. Public responses show only Chab aliases, usage, credits, and result data.

LLM operations support paid plans and bounded free access. The model catalog is not billable. Generation and embeddings create billable asynchronous operations and require an Idempotency-Key.

Model Aliases

Use GET /v1/llm/models to discover the current public aliases.

Provider names, provider model identifiers, private routing details, fallback routing, and provider request options are not part of the public API.

GET/v1/llm/models

Required scope: api:llm:read

curl https://www.chab.ai/v1/llm/models \
  -H "Authorization: Bearer CHAB_API_KEY"

Example response:

{
  "data": {
    "models": [
      {
        "alias": "fast-chat",
        "status": "preview",
        "modalities": ["text"],
        "capabilities": ["text"],
        "max_context_tokens": 128000,
        "max_input_tokens": 128000,
        "max_output_tokens": 8192,
        "max_reasoning_tokens": null,
        "max_inputs": null,
        "max_total_tokens": null,
        "embedding_dimensions": null,
        "pricing": {
          "strategy": "token_usage",
          "currency": "credit"
        },
        "preview": true,
        "warnings": []
      }
    ]
  },
  "meta": {
    "request_id": "req_123"
  }
}

POST/v1/llm/generate

Required scope: api:llm:write

Creates an asynchronous generation operation.

curl -X POST https://www.chab.ai/v1/llm/generate \
  -H "Authorization: Bearer CHAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: llm-generate-001" \
  -d '{
    "model": "fast-chat",
    "prompt": "Write a concise product update for the weekly customer email.",
    "max_output_tokens": 300
  }'

Request fields:

Unsupported request fields are rejected. Streaming, callbacks, dry-run, artifact options, provider options, routing options, and fallback options are not accepted by LLM generation. Routing is fixed per public alias and no fallback option is offered.

Accepted response:

{
  "operation": {
    "id": "op_01JZ7H0A1B2C3D4E5F6G7H8J9K",
    "status": "queued",
    "operation_key": "llm.generate",
    "family": "llm",
    "status_url": "/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K",
    "result_url": "/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K/result",
    "estimated_credits": 2,
    "result_available": false,
    "warnings": []
  },
  "meta": {
    "request_id": "req_123",
    "credits": {
      "estimated": 2,
      "reserved": 2,
      "currency": "credit"
    }
  }
}

Completed result shape:

{
  "data": {
    "result": {
      "model": "fast-chat",
      "output": {
        "type": "message",
        "content": "Here is a concise update for this week."
      },
      "finish_reason": "stop",
      "usage": {
        "input_tokens": 32,
        "output_tokens": 12,
        "cached_input_tokens": 0,
        "reasoning_tokens": 0
      },
      "credits": {
        "incurred": 1,
        "currency": "credit"
      }
    },
    "artifacts": [],
    "warnings": [],
    "result_expires_at": "2026-07-17T12:00:00+00:00"
  },
  "meta": {
    "request_id": "req_123"
  }
}

For response_format=json_schema, Chab validates the model response against the supplied schema. If the first response is invalid, Chab makes one repair attempt and charges for all model work already performed. If the repair is still invalid, the operation fails with structured_output_invalid. Structured successes include repair_attempts in the result.

For tool calls, Chab validates returned tool names and arguments against the declared tools. Tool declarations are normalized to function name, optional description, and optional parameter schema before provider work starts; provider options inside tool declarations or tool_choice are rejected. Chab never executes tools on your behalf.

Prompt text, messages, system instructions, schemas, tool declarations, and tool choice are encrypted for the worker and redacted from public operation summaries.

POST/v1/llm/embeddings

Required scope: api:llm:write

Creates an asynchronous embedding operation. Every returned vector has 768 dimensions and is normalized to unit length.

curl -X POST https://www.chab.ai/v1/llm/embeddings \
  -H "Authorization: Bearer CHAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: llm-embeddings-001" \
  -d '{
    "model": "embedding-small",
    "input": ["support ticket about invoices", "documentation about billing"]
  }'

Request fields:

Batch handles, file handles, callbacks, dry-run, artifact options, streaming, provider options, routing options, fallback options, and custom dimensions are not accepted.

Completed result shape:

{
  "data": {
    "result": {
      "model": "embedding-small",
      "dimensions": 768,
      "embeddings": [
        {
          "index": 0,
          "vector": [0.12, -0.04, 0.31]
        }
      ],
      "usage": {
        "input_tokens": 18,
        "vector_count": 1
      },
      "credits": {
        "incurred": 1,
        "currency": "credit"
      }
    },
    "artifacts": [],
    "warnings": [],
    "result_expires_at": "2026-07-17T12:00:00+00:00"
  },
  "meta": {
    "request_id": "req_123"
  }
}

The example vector is shortened for readability. Runtime vectors contain 768 numbers.

Pricing

Generation pricing is token based. The initial estimate uses estimated input tokens plus requested maximum output tokens and, when enabled, the reasoning token cap. Chab computes one summed decimal rate expression and applies a single ceil() over the total. Settlement uses reported model usage when available; otherwise Chab uses the same deterministic estimate.

Embedding pricing is based on estimated input tokens and settles from the same deterministic estimate because embedding usage is not reported. The minimum is 1 credit:

max(1, ceil(input_tokens * 0.2 / 1000))

Use max_credit_budget on either operation start to cap spend for that request. If the estimate exceeds the supplied budget, Chab returns max_budget_exceeded before creating operation rows or credit holds.

Errors

LLM endpoints use the shared error envelope. Common LLM-specific errors:

Authentication, scope, plan, credit, idempotency, rate-limit, and provider errors follow the shared pages for those error families.