Chat Completions

OpenAI-compatible chat completions endpoint. Change 2 lines of code to switch from OpenAI.

OpenAI SDK compatible — change base_url, api_key, and set model to a tier id (e.g. tier-2).

Scope: text chat completions only. Tool/function calling and image/audio content are not supported yet — requests using them return a clear 400 rather than degraded output.

Endpoint

POSThttps://api.tierup.ai/v1/chat/completionsCreate a chat completion

Request Body

Parameter	Type	Required	Description
messages	array	Yes	Array of message objects with role and content
model	string	No	Standard OpenAI field. Accepts tier-1 … tier-4 (or the response labels tierup-speed, tierup-balance, tierup-intelligence, tierup-reasoning). Unknown models return 404
tier	integer	No	TierUp shorthand for model: performance tier 1–4. Default: 1 when neither is set
stream	boolean	No	Enable SSE streaming. Default: false
temperature	number	No	Sampling temperature 0–2
max_tokens	integer	No	Maximum tokens to generate. Capped at 8192 (the default)

Example Request

curl

curl https://api.tierup.ai/v1/chat/completions \
  -H "Authorization: Bearer $TIERUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tier-2",
    "messages": [
      { "role": "user", "content": "Explain async/await in one paragraph." }
    ]
  }'

Example Response

json

{
  "id": "chatcmpl-Tu8kXm2vQpL9nRbJ",
  "object": "chat.completion",
  "created": 1743811200,
  "model": "tierup-balance",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Async/await is syntactic sugar over Promises that lets you write asynchronous code as if it were synchronous..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 64,
    "total_tokens": 82
  }
}

Streaming

Pass stream: true to receive tokens incrementally over a Server-Sent Events (SSE) connection. Each chunk is a data: line containing a JSON delta. The stream ends with the sentinel data: [DONE].

curl

curl https://api.tierup.ai/v1/chat/completions \
  --no-buffer \
  -H "Authorization: Bearer $TIERUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tier-2",
    "stream": true,
    "messages": [
      { "role": "user", "content": "Count to five." }
    ]
  }'

Example SSE chunks:

sse

data: {"id":"chatcmpl-Tu8kXm2vQpL9nRbJ","object":"chat.completion.chunk","created":1743811200,"model":"tierup-balance","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-Tu8kXm2vQpL9nRbJ","object":"chat.completion.chunk","created":1743811200,"model":"tierup-balance","choices":[{"index":0,"delta":{"content":"1"},"finish_reason":null}]}

data: {"id":"chatcmpl-Tu8kXm2vQpL9nRbJ","object":"chat.completion.chunk","created":1743811200,"model":"tierup-balance","choices":[{"index":0,"delta":{"content":", 2"},"finish_reason":null}]}

data: {"id":"chatcmpl-Tu8kXm2vQpL9nRbJ","object":"chat.completion.chunk","created":1743811200,"model":"tierup-balance","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Models Endpoint

List available tiers.

GET/v1/modelsList available tiers

json

{
  "object": "list",
  "data": [
    { "id": "tier-1", "object": "model", "name": "Speed",        "owned_by": "tierup", "pricing": { "input_price_per_m": 0,   "output_price_per_m": 0,    "is_free": true  } },
    { "id": "tier-2", "object": "model", "name": "Balance",      "owned_by": "tierup", "pricing": { "input_price_per_m": 150, "output_price_per_m": 750,  "is_free": false } },
    { "id": "tier-3", "object": "model", "name": "Intelligence", "owned_by": "tierup", "pricing": { "input_price_per_m": 250, "output_price_per_m": 1250, "is_free": false } },
    { "id": "tier-4", "object": "model", "name": "Reasoning",    "owned_by": "tierup", "pricing": { "input_price_per_m": 100, "output_price_per_m": 400,  "is_free": false } }
  ]
}

Response Headers

Header	Description
X-TierUp-Balance-Low	Present when your account balance falls below $5.00
X-RateLimit-Limit	Maximum requests per day for your plan (100 for free users)
X-RateLimit-Remaining	Requests remaining in the current rate-limit window

Error Format

All errors return a JSON body with an error object containing message, type, and code.

json

// 401 Unauthorized
{
  "error": {
    "message": "Invalid API key provided.",
    "type": "authentication_error",
    "code": "unauthorized"
  }
}

// 402 Payment Required
{
  "error": {
    "message": "Insufficient balance. Please add credits to use paid tiers.",
    "type": "billing_error",
    "code": "insufficient_funds"
  }
}