BETOPIA PLATFORM

One API for the models you need.

Build with OpenAI, Anthropic, OpenRouter, and self-hosted models through one consistent API—with streaming, tool calling, vision, and automatic routing.

bash

export BETOPIA_BASE_URL="https://api.betopia.ai/v1"\nexport BETOPIA_API_KEY="sk_..."

01AuthenticateCreate and securely store an API key.02Make a requestUse Chat Completions or Responses.03Go to productionHandle errors, limits, and streaming.

REQUEST ROUTING

Choose a model, or let Betopia route.

Every request reaches the same API. An explicit model name uses that exact model; model: "auto" selects a healthy model that satisfies the request’s capabilities.

1

Read requirementsBetopia detects tools, streaming, images, reasoning, and context needs.

2

Filter eligible modelsOnly models that support every required capability remain.

3

Rank and callThe best candidate is called, with healthy fallbacks for retryable provider failures.

AUTHENTICATION

Authenticate every request

Use a JWT to create or manage API keys. Use an API key for your server, CI, or long-lived integration.

Credential	Best for	Header
API key (`sk_...`)	Servers and CI	`Authorization: Bearer sk_...`
JWT	Login flows and short-lived tooling	`Authorization: Bearer <jwt>`

Create a scoped key

bash

curl -X POST "$BETOPIA_BASE_URL/keys" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production","expires_in_days":90,"token_limit":500000}'

MODELS

Discover available capabilities

Fetch models before relying on an optional capability. Public discovery is available without credentials; use the authenticated endpoint for your account’s full catalog.

bash

curl "$BETOPIA_BASE_URL/public/models"

Capability	What it enables
`tools`	Function/tool definitions.
`streaming`	Server-sent response events.
`vision`	Image input.
`reasoning`	Configurable reasoning effort.
`json_schema`	Structured output.

CHAT COMPLETIONS

Make your first chat completion

Use the OpenAI-compatible Chat Completions API for existing SDKs and straightforward conversations. Set model to a specific model or auto to let Betopia select an eligible model.

bash

curl -X POST "$BETOPIA_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $BETOPIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Explain how stars form."}]}'

Explicit model

You receive exactly the model requested or a clear error—never a silent substitution.

Auto routing

Betopia selects a model compatible with your request’s tools, image, and reasoning requirements.

AGENTS

Use tools and the Responses API

Use Chat Completions for compatibility. Use the Responses API for new agent flows, multi-turn work, and server-side continuation.

	Chat Completions	Responses
Conversation history	Resend `messages[]`	Continue with `previous_response_id`
Tool schema	Nested under `function`	Flat name and parameters
Best for	Existing OpenAI integrations	New agents and multi-turn workflows

Tool calling loop

1

Send a tool definition with the user request.

2

Validate the JSON-string arguments, then run the function in your application.

3

Return one result for each call ID so the model can finish its response.

json

{"model":"auto","messages":[{"role":"user","content":"Weather in Dhaka?"}],"tools":[{"type":"function","function":{"name":"get_weather","parameters":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}}}]}

Continue a Responses API tool call

For Responses, send only the function output and the previous response ID. Do not resend full history or provider reasoning state.

bash

curl -X POST "$BETOPIA_BASE_URL/responses" \
  -H "Authorization: Bearer $BETOPIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"previous_response_id":"resp_abc123","input":[{"type":"function_call_output","call_id":"call_xyz","output":"{\"temperature_c\":31}"}]}'

STREAMING & MULTIMODAL

Stream output and send images safely

Set stream: true for Server-Sent Events. For Chat Completions, the final event is data: [DONE]; for Responses, use the lifecycle events below.

Responses event	Meaning
`response.created`	Generation has started.
`response.output_text.delta`	Next assistant text chunk.
`response.function_call_arguments.delta`	Next function argument chunk.
`response.completed`	The final response is included.
`response.failed`	Generation failed; no completed event follows.

bash

curl -N -X POST "$BETOPIA_BASE_URL/responses" \
  -H "Authorization: Bearer $BETOPIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","input":"Write a short plan.","stream":true}'

Chat image input

Use {"type":"image_url","image_url":{"url":"..."}}.

Responses image input

Use {"type":"input_image","image_url":"..."} with a flat URL string.

REASONING & OUTPUT

Use the correct API for the output you need

Capability	Chat Completions	Responses
Reasoning	`reasoning_effort: "low" \| "medium" \| "high"`	`reasoning: { effort }`
Structured output	`response_format` with JSON Schema	Not supported
Legacy text completion	`POST /v1/completions` is maintained only for compatibility—do not use it for new integrations.

json

{"model":"auto","messages":[{"role":"user","content":"Extract the name and age."}],"response_format":{"type":"json_schema","json_schema":{"name":"person","schema":{"type":"object","properties":{"name":{"type":"string"},"age":{"type":"integer"}},"required":["name","age"]}}}}

PRODUCTION

Handle limits and failures intentionally

Status	Meaning	Action
400	Invalid request or unsupported feature.	Fix the request.
401	Missing or invalid credential.	Refresh credentials.
404	Model or previous response not found.	Check identifier/expiry.
429	Rate or budget limit.	Retry after `reset_at`.
502	Upstream provider failure.	Bounded retry for idempotent operations.

Support requests

Every response includes X-Request-Id. Log it and include it with any support request.

Body limits

Text-only requests allow 1 MB. Image requests allow 20 MB; keep base64 images below 15 MB for headroom.

REFERENCE

Endpoint quick reference

Endpoint	Use it for
`POST /v1/auth/register` / `login`	Create a JWT.
`POST /v1/keys`	Create a scoped API key.
`GET /v1/models`	List your authenticated model catalog.
`GET /v1/public/models`	Discover publicly available models.
`POST /v1/chat/completions`	OpenAI-compatible conversations.
`POST /v1/responses`	Agent and multi-turn workflows.
`POST /v1/completions`	Legacy plain-text completions.
`GET /v1/user/limits`	Check usage and remaining budget.

LangChain

python

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    base_url="https://api.betopia.ai/v1",
    api_key=os.environ["BETOPIA_API_KEY"],
    model="auto",
    use_responses_api=False,
)