API Reference

DrAI API Reference

The complete contract for the DrAI API: POST /v1/chat/completions, GET /v1/models, streaming (SSE) and error handling. OpenAI-compatible, so most clients work without changes.

Base URL: https://api.dr-ai.top/v1

Authentication

All endpoints require a bearer token:

Authorization: Bearer sk-your-api-key

Missing or invalid keys return 401 invalid_api_key. Create keys in the dashboard.

Chat Completions

POST/v1/chat/completions

Generate a chat completion on any model in your subscription. Supports streaming, tool/function calling and vision inputs.

curl https://api.dr-ai.top/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-mini",
    "messages": [
      {"role": "system", "content": "You are a precise assistant."},
      {"role": "user", "content": "Summarize the DrAI API in one line."}
    ],
    "temperature": 0.7,
    "max_tokens": 300,
    "stream": false
  }'

Request parameters

Parameter	Type	Default	Description
`model` required	string	—	Model ID, e.g. `gpt-5-mini`, `gpt-5`, `claude-opus-4`, `deepseek-chat`. See model catalog.
`messages` required	array	—	Conversation history. Each item has `role` (`system` \| `user` \| `assistant` \| `tool`) and `content`.
`temperature`	number	1.0	Sampling temperature, 0–2. Lower = more deterministic; higher = more creative.
`max_tokens`	integer	model default	Maximum number of tokens to generate, including reasoning tokens.
`stream`	boolean	false	When `true`, the response is delivered as server-sent events (SSE).
`top_p`	number	1.0	Nucleus sampling. DrAI recommends altering `temperature` or `top_p`, but not both.
`stop`	string \| array	null	Up to 4 sequences where the API stops generating.
`tools`	array	null	Function/tool definitions for tool calling (OpenAI format).

Response

{
  "id": "chatcmpl-9xK2mQ7rF...",
  "object": "chat.completion",
  "created": 1786910400,
  "model": "gpt-5-mini",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "..."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 24, "completion_tokens": 45, "total_tokens": 69}
}

Streaming responses (SSE)

Set "stream": true to receive tokens as server-sent events. Each event is a data: line containing a chunk with a choices[0].delta object; the stream ends with data: [DONE].

# curl -N https://api.dr-ai.top/v1/chat/completions ... -d '{"model":"gpt-5-mini",...,"stream":true}'
data: {"id":"chatcmpl-9xK2mQ7rF...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-9xK2mQ7rF...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-9xK2mQ7rF...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: {"id":"chatcmpl-9xK2mQ7rF...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

All OpenAI-compatible SDKs handle this format natively — e.g. Python: for chunk in client.chat.completions.create(..., stream=True).

List models

GET/v1/models

Return the model IDs available to your account.

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

{
  "object": "list",
  "data": [
    {"id": "gpt-5", "object": "model", "created": 1755000000, "owned_by": "openai"},
    {"id": "gpt-5-mini", "object": "model", "created": 1755000000, "owned_by": "openai"},
    {"id": "claude-opus-4", "object": "model", "created": 1755000000, "owned_by": "anthropic"}
  ]
}

The complete, always-current list is on the model catalog page.

Error codes

Errors use the OpenAI error envelope: {"error": {"message": "...", "type": "...", "code": "..."}}.

Status	Type / code	Meaning	Fix
`400`	`invalid_request_error`	Malformed JSON, missing `model` or `messages`, bad parameter value.	Validate the request body against the parameter table above.
`401`	`invalid_api_key`	Missing or invalid `Authorization` header.	Regenerate the key in the dashboard and check the header format.
`404`	`model_not_found`	The model ID does not exist or is not in your plan.	Check the ID against /docs-models.
`429`	`rate_limit_exceeded` / `insufficient_quota`	Too many requests, or subscription limit reached.	Back off using the `Retry-After` header; upgrade the plan if persistent.
`500`	`server_error`	Internal error on our side.	Retry with exponential backoff; check status.dr-ai.top.
`503`	`overloaded`	Upstream provider is overloaded.	Retry after a short delay, or route to an alternate model.

Retries: retry 429, 500 and 503 with exponential backoff (e.g. 1s → 2s → 4s, jittered). Never retry 400 or 401 without changing the request.

Build something great

You have the contract. Now grab a key and ship — all 18+ models are one subscription away.

Get Started — free Back to Quickstart