Chat completions
Send OpenAI-compatible chat requests with clear controls.
Run chat workflows for assistants, copilots, and internal tools with a familiar request shape, server-side keys, usage tracking, and safe retry behavior.
Last updated: July 6, 2026. Examples use safe placeholders and do not include real API keys, secrets, or customer data.
Default path
Use non-streaming requests first. They return a complete chat.completion response and are easier to validate before customer-facing traffic grows.
Implementation path
Four steps from key to response.
Keep the first integration small: authenticate from your backend, send a minimal message array, parse the response, then add retry and rate-limit handling.
Step 1
Authenticate server-side
Read a scoped API key from a server-side environment variable and send it as a Bearer token.
Open sectionStep 2
Send a chat request
Post an OpenAI-compatible payload with a model string and a messages array.
Open sectionStep 3
Parse the response
Read choices[0].message.content for the assistant message and usage for request accounting.
Open sectionStep 4
Handle limits and errors
Retry transient failures with backoff, but fix auth, payload, capacity, and unsupported feature errors before resending.
Open sectionEndpoint
Post JSON to the chat completions route.
The endpoint follows the OpenAI-compatible /v1 path. Send requests from trusted server-side code with a scoped Bearer token.
| Item | Value | Notes |
|---|---|---|
| Method | POST | Send JSON to the chat completions endpoint. |
| Endpoint | https://unlimitedcodex.com/v1/chat/completions | Use the same base URL pattern as other OpenAI-compatible /v1 endpoints. |
| Authorization | Bearer token | Use an API key with chat:write scope from trusted server-side code. |
| Content type | application/json | The request body must be valid JSON. |
Non-streaming request
Start with a complete response.
Non-streaming requests are the safest first path because your client receives the full response object, status, headers, and usage in one place.
Keep the API key in process.env or a secret manager.
Use a short system instruction and a minimal user message.
Set max_tokens when the UI or cost budget needs a ceiling.
Parse usage so request, token, and cost monitoring can stay accurate.
const response = await fetch("https://unlimitedcodex.com/v1/chat/completions", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.UCX_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
model: "gpt-5.5",
messages: [
{ role: "system", content: "You write concise operational summaries." },
{ role: "user", content: "Summarize the release checklist in three bullets." }
],
temperature: 0.2,
max_tokens: 180
})
});
const body = await response.json();
if (!response.ok) {
throw new Error(body.error?.code ?? "chat_request_failed");
}
console.log(body.choices[0].message.content);
console.log(body.usage);Request and response shape
Use familiar chat fields and usage accounting.
The required shape is small: a model string and at least one message. Optional fields can tighten output behavior or rate-limit planning.
| Field | Status | Notes |
|---|---|---|
| model | Recommended | Pass the target model value explicitly. Use gpt-5.5 or the GPT/Codex model values listed in your delivered setup files. |
| messages | Required | Array of system, user, assistant, or tool messages. Include only the context needed for the task. |
| temperature | Optional | Use a number from 0 to 2 when the workflow needs more or less variation. |
| max_tokens | Optional | Cap response length when the user experience or cost budget needs a predictable ceiling. |
| stream | Optional | Omit it or set false for the current supported path. See streaming behavior below before setting true. |
{
"id": "chatcmpl_example",
"object": "chat.completion",
"created": 1783372800,
"model": "gpt-5.5",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "This is an unlimitedcodex chat completion response. Use the delivered setup files for available GPT and Codex model values."
},
"finish_reason": "stop"
}
],
"usage": {
"inputTokens": 24,
"outputTokens": 32,
"totalTokens": 56
}
}Streaming behavior
Treat streaming as an explicit capability check.
Do not assume a streaming request will behave like a non-streaming request. Branch on the response code and keep a product-approved fallback path.
{
"error": {
"message": "Streaming responses are not enabled for this endpoint.",
"type": "unsupported_feature",
"code": "streaming_not_enabled"
}
}| Mode | Setting | Behavior | Client action |
|---|---|---|---|
| Non-streaming | Omit stream or set stream: false | Returns a complete chat.completion object when the request is accepted. | Use this as the default path for first integrations and customer-facing workflows. |
| Streaming | stream: true | The current endpoint returns 501 streaming_not_enabled. | Fall back to non-streaming only when that user experience is acceptable. |
Model routing notes
Make model policy visible before traffic grows.
The model field is part of the request contract and the operational record. Keep it intentional, then review policy before launch volume changes.
Keep model explicit
Send a model value in every request so usage logs, usage analysis, and support escalation have a stable policy signal.
Do not assume a silent fallback
Treat model fallback behavior as a configured product decision. Review policy before changing production model names.
Log only safe identifiers
Capture endpoint, status, model, usage, and a masked key prefix. Do not log raw prompts, API keys, or customer data.
Safe retries
Retry only work that can recover.
Retries help with temporary pressure and service failures. They can amplify capacity, payload, and billing problems when nothing changes.
Retry transient failures
408, 500, 502, 503, 504, and short 429 rate pressure
Use bounded exponential backoff with jitter. Respect Retry-After when the response includes it.
Do not retry unchanged payloads
400, 401, 402, 403, 501, and capacity pressure
Fix the payload, key, billing state, scope, unsupported option, or package capacity before sending the same work again.
Keep retries invisible to secrets
All client implementations
Retry the request function, not a logged raw payload. Redact Authorization headers and customer content from diagnostics.
async function runWithChatRetries(runRequest) {
for (let attempt = 0; attempt < 3; attempt += 1) {
const response = await runRequest();
if (response.ok) {
return response;
}
const body = await response.clone().json().catch(() => ({}));
const code = body.error?.code;
const retryable =
[408, 500, 502, 503, 504].includes(response.status) ||
(response.status === 429 && code === "rate_limit_exceeded");
if (!retryable) {
return response;
}
const retryAfter = Number(response.headers.get("retry-after") ?? 0);
const backoffMs = retryAfter > 0 ? retryAfter * 1000 : 500 * 2 ** attempt;
const jitterMs = Math.floor(Math.random() * 150);
await new Promise((resolve) => setTimeout(resolve, backoffMs + jitterMs));
}
return runRequest();
}Launch checklist
Check the integration before users depend on it.
A launch-ready chat workflow needs more than a successful request. Confirm keys, limits, errors, logs, and fallback behavior while the blast radius is still small.
Use separate keys for development, staging, and production.
Confirm chat:write scope and server-side environment storage.
Decide whether streaming_not_enabled should block or fall back.
Monitor request count, input tokens, output tokens, rate state, and status codes.
Redact prompts, Authorization headers, raw keys, and customer data from logs.
Link UI errors to retry, support, or upgrade actions instead of generic failure text.
FAQ
Chat completions questions.
Is the chat completions endpoint OpenAI-compatible?
Yes. The endpoint uses the familiar /v1/chat/completions path, Bearer authentication, messages array, chat.completion response object, choices, and usage fields.
Should I use streaming for customer-facing traffic?
Use non-streaming requests unless your integration has confirmed streaming support. The current endpoint returns 501 streaming_not_enabled when stream is true.
What should I log for debugging?
Log endpoint, status, error code, model, usage, timestamp, environment, and masked key prefix. Do not log raw API keys, secrets, full prompts, or customer data.
When should my client retry a chat request?
Retry transient 408, rate pressure 429, and 5xx responses with bounded backoff. Do not retry unchanged authentication, payload, billing, capacity, or unsupported feature failures.
Free tools
Build and validate chat requests
Generate snippets, validate JSON, estimate tokens, and plan OpenAI migration before your first live call.
Request Builder
Build chat completion JSON visually and export cURL, JavaScript, or Python snippets.
Request Validator
Validate chat, embeddings, and image JSON payloads against unlimitedcodex OpenAI-compatible rules.
Token Estimator
Estimate token volume from prompt or response text before quota planning and launch.
Migration Generator
Generate or transform OpenAI SDK snippets to unlimitedcodex base URL, keys, and scopes.
Next step
Pair chat completions with auth, limits, and error handling.
Before launch, make sure keys are scoped, rate-limit behavior is understood, and client retries distinguish temporary pressure from required fixes.