OpenAI-compatible API guide

Choose the interface first

OpenAI recommends Responses API for all new projects. Chat Completions remains supported for existing messages and choices integrations. Embeddings, images, audio, and video use separate resources. Endpoint compatibility on this site still depends on both model and channel, so confirm the exact ID and route in the model marketplace.

Make a minimal Responses call

This site uses Authorization: Bearer. Responses places model and input in JSON. This request works only when the selected model and channel support /v1/responses:

Copycurl "$BASE_URL/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_NAME","input":"Reply only: connected"}'

Responses returns typed output items. SDK output_text is convenient for a simple final answer, but general clients must traverse output by type for messages, tool calls, and other items. Do not assume output[0] is always text.

Keep Chat Completions for compatible applications

Existing applications can call /v1/chat/completions, normally reading choices[0].message.content, finish_reason, and usage. Do not migrate by changing only the path: input/output, tool results, conversation continuation, and streaming events all differ.

Copycurl "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_NAME","messages":[{"role":"user","content":"Reply only: connected"}]}'

Conversation state and context

Responses can continue with previous_response_id, but top-level instructions are not inherited and must be sent again. Prior input still consumes tokens and context; continuation is not free unlimited memory. If application-controlled storage is required, define a data policy and preserve the complete output items required by the protocol.

Close the tool loop in the application

A custom-function loop declares tools, receives a call, validates its name and arguments on the server, performs a controlled action, returns the result, and continues until an answer or another call. Model JSON is not authorization. Revalidate files, network targets, money, and recipients, with timeouts, idempotency, least privilege, and human confirmation.

Parse streams to a real completion

Responses and Chat can both stream over SSE, but their event shapes differ. Read complete event/data records separated by blank lines, tolerate unknown event types, and wait for the protocol's completion event. Do not send arbitrary TCP chunks directly to a JSON parser. Persist stop state and any in-stream error; whether usage appears or needs an explicit option must be verified per endpoint and channel.

Errors, limits, and retries

For 401, check the key, organization, or IP restrictions. A 404 from this gateway or a specific resource calls for route and model checks. 429 can mean a temporary rate, credits, or a spend cap, while 5xx is more likely transient service failure. Honor Retry-After or use jittered exponential backoff with bounded attempts and time. Failed requests may still consume rate budget.

Usage, security, and compatibility boundary

Persist usage, estimate tokens before large inputs, and enforce per-user output, rate, and spend limits. Keep API keys in server-side secret management and rotate immediately after exposure. This gateway does not promise every OpenAI beta field; structured output, reasoning effort, parallel tools, image input, storage, and caching require field-level contract tests against the production target.