Chat

POST /v1/chat/completions

POSThttps://api.topbilling.in/v1/chat/completionsscope chat:write

Creates a model response for a conversation. OpenAI Chat Completions request and response shapes.

Authentication

Send your key as Authorization: Bearer tb_… or x-api-key: tb_…. See Authentication.

Optional headers: Idempotency-Key (non-streaming requests; replays within 24 hours are not charged again).

Parameters

modelstringrequired

A Top Billing model id from GET /v1/models.

messagesarrayrequired

Roles system, developer, user, assistant, tool; text and image parts.

max_completion_tokensinteger

Upper bound on generated tokens (max_tokens is accepted as an alias). Also sizes the credit reservation.

temperaturenumber

Sampling temperature.

top_pnumber

Nucleus sampling.

stopstring | array

Stop sequences.

streamboolean

Server-sent events. See Streaming.

stream_options.include_usageboolean

Adds a final chunk with usage.

toolsarray

Function definitions, on models with tool_calling.

tool_choicestring | object

auto, none, required or a named function.

parallel_tool_callsboolean

Allow several tool calls in one turn.

response_formatobject

Structured output, on models that support it.

userstring

Your end-user identifier.

Any other field is rejected with 400 unsupported_parameter on the translated lane — for example n > 1, logprobs, logit_bias, seed, reasoning_effort, legacy functions. See the compatibility matrix for both lanes.

Request

POST /v1/chat/completions

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TB_API_KEY"],
    base_url="https://api.topbilling.in/v1",
)

response = client.chat.completions.create(
    model="<model-id>",
    messages=[{"role": "user", "content": "Summarise this ticket in one line."}],
)
print(response.choices[0].message.content)

Response

json

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "<model-id>",
  "choices": [
    {"index": 0, "message": {"role": "assistant", "content": "..."}, "finish_reason": "stop"}
  ],
  "usage": {"prompt_tokens": 18, "completion_tokens": 24, "total_tokens": 42, "prompt_tokens_details": {"cached_tokens": 0}}
}

Headers on every response: x-request-id, x-ratelimit-limit-requests, x-ratelimit-remaining-requests, x-ratelimit-reset-requests.

Errors

400 invalid or unsupported parameter · 401 key · 402 balance or spend limit · 403 scope · 404 model · 413 body over 32 MB · 429 rate limit · 5xx upstream, retryable and not charged. Details in Errors.