Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Consumption API

The Consumption API is what you call to run inference. Two surfaces (OpenAI Chat Completions and Anthropic Messages) sit in front of the same routing engine.

The Consumption API is what you call to run inference. It's the API behind the Quickstart and the one most teams ever touch. Two surfaces sit in front of the same routing engine:

  • OpenAI Chat Completions at https://api.thegrid.ai/v1 with Authorization: Bearer YOUR_KEY.

  • Anthropic Messages (beta) at https://messages-beta.api.thegrid.ai/v1 with x-api-key: YOUR_KEY.

Same instruments, same routing, same Consumption key. Pick whichever request shape fits your stack. The canonical instrument list lives in Current instruments; pass the instrument string (text-prime, code-max, claude-opus-latest, etc.) in the model field.

Create a chat completion

Create chat completion

post

Creates a chat completion for the provided messages using the specified model. This endpoint is compatible with the OpenAI chat completions API format.

The request is validated and then routed to the appropriate LLM provider. Your account balance is checked before processing.

Authorizations
AuthorizationstringRequired

Bearer token authentication using your API key.

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Generate API keys from your Grid Dashboard.

Body
modelstringOptionalExample: text-prime
max_tokensinteger · min: 1 · nullableOptionalDeprecated
max_completion_tokensinteger · min: 1 · nullableOptional
temperaturenumber · max: 2 · nullableOptionalDefault: 1
top_pnumber · max: 1 · nullableOptionalDefault: 1
ninteger · min: 1 · max: 128 · nullableOptionalDefault: 1
streamboolean · nullableOptionalDefault: false
stopone of · nullableOptional
stringOptional
or
string[] · max: 4Optional
logprobsboolean · nullableOptionalDefault: false
top_logprobsinteger · max: 20 · nullableOptional
response_formatone of · nullableOptional
or
or
tool_choiceone of · nullableOptional
string · enumOptionalPossible values:
or
parallel_tool_callsbooleanOptionalDefault: true
frequency_penaltynumber · min: -2 · max: 2 · nullableOptionalDefault: 0
presence_penaltynumber · min: -2 · max: 2 · nullableOptionalDefault: 0
seedinteger · nullableOptional
service_tierstring · enum · nullableOptionalPossible values:
reasoning_effortstring · enum · nullableOptionalPossible values:
storeboolean · nullableOptional
verbositystring · enum · nullableOptionalPossible values:
prompt_cache_keystring · nullableOptional
prompt_cache_retentionstring · enum · nullableOptionalPossible values:
safety_identifierstring · nullableOptional
routestring · enumOptionalPossible values:
providerobjectOptional
userstringOptionalDeprecated
Responses
200

Chat completion response

application/json
idstringRequiredExample: chatcmpl-abc123
objectstring · enumRequiredPossible values:
createdintegerRequiredExample: 1677858242
modelstringRequiredExample: text-prime
system_fingerprintstring · nullableOptional
service_tierstring · enum · nullableOptionalPossible values:
post/chat/completions
curl -L -X POST 'https://api.thegrid.ai/v1/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "text-prime",
    "messages": [
      {"role": "system", "content": "Be concise and to the point."},
      {"role": "user", "content": "Write one paragraph on why inference needs a market."}
    ],
    "max_completion_tokens": 500
  }'

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1677858242,
  "model": "text-prime",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Inference - the real‑time application of trained AI models to generate predictions, classifications, or recommendations - requires a market because its value is realized only when it can be delivered as a scalable, reliable service to end users. A market provides the economic incentives for developers to invest in optimizing hardware, software, and infrastructure that reduce latency, improve accuracy, and lower cost per query; it creates competition that drives innovation in model compression, edge deployment, and pricing models (pay‑per‑call, subscription, or platform‑as‑a‑service). Moreover, a market facilitates the aggregation of demand across diverse industries—healthcare, finance, retail, autonomous systems—allowing providers to achieve economies of scale, standardize APIs, and ensure compliance and security standards. Without such a marketplace, inference would remain a fragmented, research‑only capability, lacking the financial and operational mechanisms needed for widespread, sustainable adoption."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 18,
    "total_tokens": 43
  }
}

Create a message (Anthropic-compatible)

Beta

Create a message

post

Send a structured list of input messages and receive a model-generated response using the Anthropic-compatible Messages format. This is the endpoint that powers Claude Code.

This endpoint is in beta and is served from its own dedicated base URL https://messages-beta.api.thegrid.ai/v1.

This endpoint authenticates via the x-api-key header (not Authorization: Bearer), matching the Anthropic API convention.

For a step-by-step Claude Code setup guide, see Use The Grid in Claude Code.

Authorizations
x-api-keystringRequired

Anthropic-compatible API key authentication for the [BETA] Messages endpoint.

Include your API key in the x-api-key header:

x-api-key: YOUR_API_KEY

Generate API keys from your Grid Dashboard.

Body
modelstringRequiredExample: text-prime
max_tokensinteger · min: 1RequiredExample: 1024
systemone of · nullableOptional
stringOptional
or
stop_sequencesstring[] · nullableOptional
streamboolean · nullableOptionalDefault: false
temperaturenumber · nullableOptional
top_pnumber · nullableOptional
top_kinteger · nullableOptional
service_tierstring · enum · nullableOptionalPossible values:
Responses
200

Message response

application/json
idstringRequiredExample: msg_01XFDUDYJgAACzvnptvVoYEL
typestring · enumRequiredPossible values:
rolestring · enumRequiredPossible values:
modelstringRequiredExample: text-prime
stop_reasonstring · enum · nullableRequiredPossible values:
stop_sequencestring · nullableOptional
post/messages
curl -X POST 'https://messages-beta.api.thegrid.ai/v1/messages' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "text-prime",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Write one paragraph on why inference needs a market."}
    ]
  }'

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Inference - the real-time application of trained AI models - requires a market because its value is realized only when delivered as a scalable, reliable service."
    }
  ],
  "model": "text-prime",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 25,
    "output_tokens": 42
  }
}

Quick example

A minimal chat completion call:

The -L flag is required. The Consumption API returns a 307 Temporary Redirect on the way to the routing layer that fulfills inference, and cURL does not follow redirects by default. The OpenAI and Anthropic SDKs handle this automatically. See Request routing and redirects for details.

Where next

PreviousAuthenticationNextTrading API

Last updated

Was this helpful?