Making Your First Request

A detailed guide to making inference requests.

Request Structure

All inference requests follow the OpenAI API format.

Endpoint

POST /v1/chat/completions

Headers

Header	Value	Required
Content-Type	application/json	Yes
Authorization	Bearer {api_key}	Yes

Request Body

{
  "model": "your-chat-model",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "max_tokens": 100,
  "temperature": 0.7,
  "stream": false
}

Parameters

Parameter	Type	Default	Description
model	string	required	Model identifier
messages	array	required	Conversation messages
max_tokens	integer	none	Maximum tokens to generate. If omitted, the model generates until a stop token or the context window is reached
temperature	float	1.0	Sampling temperature (0-2)
top_p	float	1.0	Nucleus sampling parameter
stream	boolean	false	Enable streaming responses
stop	array	null	Stop sequences

note

The defaults above are OpenAI/vLLM conventions, not values enforced by the platform. The request body is forwarded to the model as-is, so any parameter you omit is left for the serving engine to default.

Message Roles

Role	Description
system	Sets the behavior of the assistant
user	Messages from the user
assistant	Previous assistant responses

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1704067200,
  "model": "your-chat-model",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 9,
    "total_tokens": 29
  }
}

Available Models

Check available models:

curl https://api.bulutistan.ai/v1/models \
  -H "Authorization: Bearer sk-proj-your-api-key"

Two groups of optional fields can appear on each entry, and both are omitted entirely when they do not apply rather than sent as null — test for the key, not for a truthy value:

• region — an uppercase ISO 3166-1 alpha-2 code naming where the model is served from, where your operator has recorded one.
• deprecated_at, sunset_at, replacement_model_id, replacement_model_name, replacement_note — present only on a model that is being retired. It keeps serving normally until sunset_at, then leaves the listing and answers 410 Gone.

See Models for the full field reference, and Model Deprecation for the Deprecation and Sunset response headers your requests will start carrying.

Error Handling

from openai import OpenAI, APIError

client = OpenAI(
    api_key="sk-proj-your-api-key",
    base_url="https://api.bulutistan.ai/v1"
)

try:
    response = client.chat.completions.create(
        model="your-chat-model",
        messages=[{"role": "user", "content": "Hello"}]
    )
except APIError as e:
    print(f"API Error: {e.status_code} - {e.message}")

See Error Handling for complete error reference.