> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crun.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Crun Chat Completions API
> OpenAI-compatible /chat/completions endpoint for CRUN language models.
## API Endpoint
```text theme={null}
POST https://api.crun.ai/api/v1/chat/completions
```
This endpoint follows the [OpenAI Chat Completions](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create) request and response format.
It is designed for direct use with the official OpenAI SDKs and other OpenAI-compatible clients.
## Authentication
You can authenticate with either:
* `Authorization: Bearer YOUR_API_KEY`
* `X-API-KEY: YOUR_API_KEY`
## Request Examples
```bash cURL theme={null} theme={null}
curl -X POST "https://api.crun.ai/api/v1/chat/completions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.4",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Summarize the benefits of serverless functions in 3 bullet points."
}
],
"temperature": 0.6
}'
```
```python Python (OpenAI SDK) theme={null} theme={null}
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.crun.ai/api/v1",
)
response = client.chat.completions.create(
model="gpt-5.4",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Summarize the benefits of serverless functions in 3 bullet points."},
],
temperature=0.6,
)
print(response.choices[0].message.content)
```
```javascript JavaScript (OpenAI SDK) theme={null} theme={null}
import OpenAI from "openai";
const client = new OpenAI({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.crun.ai/api/v1"
});
const response = await client.chat.completions.create({
model: "gpt-5.4",
messages: [
{ role: "system", content: "You are a helpful assistant." },
{ role: "user", content: "Summarize the benefits of serverless functions in 3 bullet points." }
],
temperature: 0.6
});
console.log(response.choices[0].message.content);
```
## Conversation History Example
CRUN does not manage multi-turn conversation context for your application.
To continue a conversation, you must manage prior message history yourself and include the relevant history in each new request.
```bash cURL theme={null} theme={null}
curl -X POST "https://api.crun.ai/api/v1/chat/completions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.4",
"messages": [
{
"role": "system",
"content": "You are a helpful support assistant."
},
{
"role": "user",
"content": "My package has not arrived yet. What should I check first?"
},
{
"role": "assistant",
"content": "First, check the tracking link, delivery address, and any carrier delay notices."
},
{
"role": "user",
"content": "The tracking page says delayed by weather. Draft a short reply to the customer."
}
],
"temperature": 0.6
}'
```
```python Python (OpenAI SDK) theme={null} theme={null}
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.crun.ai/api/v1",
)
messages = [
{"role": "system", "content": "You are a helpful support assistant."},
{"role": "user", "content": "My package has not arrived yet. What should I check first?"},
{"role": "assistant", "content": "First, check the tracking link, delivery address, and any carrier delay notices."},
{"role": "user", "content": "The tracking page says delayed by weather. Draft a short reply to the customer."},
]
response = client.chat.completions.create(
model="gpt-5.4",
messages=messages,
temperature=0.6,
)
print(response.choices[0].message.content)
```
```javascript JavaScript (OpenAI SDK) theme={null} theme={null}
import OpenAI from "openai";
const client = new OpenAI({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.crun.ai/api/v1"
});
const messages = [
{ role: "system", content: "You are a helpful support assistant." },
{ role: "user", content: "My package has not arrived yet. What should I check first?" },
{ role: "assistant", content: "First, check the tracking link, delivery address, and any carrier delay notices." },
{ role: "user", content: "The tracking page says delayed by weather. Draft a short reply to the customer." }
];
const response = await client.chat.completions.create({
model: "gpt-5.4",
messages,
temperature: 0.6
});
console.log(response.choices[0].message.content);
```
## Structured Output Example
Use `response_format` when you need the model to return JSON. For schema-enforced structured outputs, use a model and upstream provider that support `json_schema`.
```bash cURL theme={null} theme={null}
curl -X POST "https://api.crun.ai/api/v1/chat/completions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.4",
"messages": [
{
"role": "system",
"content": "Extract tasks as JSON only."
},
{
"role": "user",
"content": "Maya should send the launch brief by Friday."
}
],
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "task",
"strict": true,
"schema": {
"type": "object",
"properties": {
"owner": { "type": "string" },
"task": { "type": "string" },
"due": { "type": "string" }
},
"required": ["owner", "task", "due"],
"additionalProperties": false
}
}
}
}'
```
```python Python (OpenAI SDK) theme={null} theme={null}
response = client.chat.completions.create(
model="gpt-5.4",
messages=[
{"role": "system", "content": "Extract tasks as JSON only."},
{"role": "user", "content": "Maya should send the launch brief by Friday."},
],
response_format={
"type": "json_schema",
"json_schema": {
"name": "task",
"strict": True,
"schema": {
"type": "object",
"properties": {
"owner": {"type": "string"},
"task": {"type": "string"},
"due": {"type": "string"},
},
"required": ["owner", "task", "due"],
"additionalProperties": False,
},
},
},
)
print(response.choices[0].message.content)
```
```javascript JavaScript (OpenAI SDK) theme={null} theme={null}
const response = await client.chat.completions.create({
model: "gpt-5.4",
messages: [
{ role: "system", content: "Extract tasks as JSON only." },
{ role: "user", content: "Maya should send the launch brief by Friday." }
],
response_format: {
type: "json_schema",
json_schema: {
name: "task",
strict: true,
schema: {
type: "object",
properties: {
owner: { type: "string" },
task: { type: "string" },
due: { type: "string" }
},
required: ["owner", "task", "due"],
additionalProperties: false
}
}
}
});
console.log(response.choices[0].message.content);
```
## Tool Calling Example
Chat Completions accepts OpenAI-compatible `tools` and `tool_choice` fields. Your application is responsible for executing tool calls and sending tool results back in a follow-up request.
```json request body theme={null} theme={null}
{
"model": "gpt-5.4",
"messages": [
{
"role": "user",
"content": "What is the weather like in Paris?"
}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string"
}
},
"required": ["city"],
"additionalProperties": false
}
}
}
],
"tool_choice": "auto"
}
```
## Vision Input Example
When the selected model supports image input, pass multimodal content parts in the user message.
```json request body theme={null} theme={null}
{
"model": "gpt-5.4",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Describe this chart in one paragraph."
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/chart.png"
}
}
]
}
],
"max_completion_tokens": 300
}
```
## Streaming Example
Set `stream=true` to receive Server-Sent Events. CRUN enables usage reporting for streaming requests when possible.
```bash cURL theme={null} theme={null}
curl -N "https://api.crun.ai/api/v1/chat/completions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.4",
"stream": true,
"messages": [
{
"role": "user",
"content": "Write a three-step checklist for reviewing an API integration."
}
],
"stream_options": {
"include_usage": true
}
}'
```
```python Python (OpenAI SDK) theme={null} theme={null}
stream = client.chat.completions.create(
model="gpt-5.4",
messages=[
{"role": "user", "content": "Write a three-step checklist for reviewing an API integration."}
],
stream=True,
stream_options={"include_usage": True},
)
for chunk in stream:
if chunk.choices:
print(chunk.choices[0].delta.content or "", end="")
```
```javascript JavaScript (OpenAI SDK) theme={null} theme={null}
const stream = await client.chat.completions.create({
model: "gpt-5.4",
messages: [
{ role: "user", content: "Write a three-step checklist for reviewing an API integration." }
],
stream: true,
stream_options: { include_usage: true }
});
for await (const chunk of stream) {
const content = chunk.choices?.[0]?.delta?.content;
if (content) process.stdout.write(content);
}
```
## Response Examples
```json basic response theme={null} theme={null}
{
"id": "chatcmpl_abc123",
"object": "chat.completion",
"created": 1772294400,
"model": "gpt-5.4",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "- No server management.\n- Automatic scaling for bursty traffic.\n- Pay only for actual execution time."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 22,
"completion_tokens": 19,
"total_tokens": 41
}
}
```
```text streaming response (SSE) theme={null} theme={null}
data: {"id":"chatcmpl_abc123","object":"chat.completion.chunk","created":1772294400,"model":"gpt-5.4","choices":[{"index":0,"delta":{"role":"assistant","content":"- No server management."},"finish_reason":null}]}
data: {"id":"chatcmpl_abc123","object":"chat.completion.chunk","created":1772294400,"model":"gpt-5.4","choices":[{"index":0,"delta":{"content":"\\n- Automatic scaling for bursty traffic."},"finish_reason":null}]}
data: {"id":"chatcmpl_abc123","object":"chat.completion.chunk","created":1772294400,"model":"gpt-5.4","choices":[],"usage":{"prompt_tokens":22,"completion_tokens":19,"total_tokens":41}}
data: [DONE]
```
## Notes
* Set `stream=true` to receive a `text/event-stream` response.
* If you omit `stream_options.include_usage`, CRUN enables it automatically for streaming requests.
* `max_tokens` and `max_completion_tokens` are both accepted and are capped by the selected model's output token limit.
* Unknown model IDs return an OpenAI-style error body with `code: "model_not_found"`.
* For new stateful, tool-heavy, or structured-output workflows, also consider the `/responses` endpoint. Responses uses `input`, `instructions`, and `text.format` instead of `messages` and `response_format`.
## Related Resources
Build with flexible input, stateful follow-ups, structured outputs, and tool-ready response items.
Learn the base URL, authentication method, and official SDK integration pattern.
Explore all available image, video, audio, and language model APIs.
Jump to the pricing page to compare billing across different models.
## OpenAPI
````yaml models/llm/chat-completions.json post /api/v1/chat/completions
openapi: 3.0.0
info:
title: CRUN OpenAI-Compatible Chat Completions API
description: OpenAI-compatible language model endpoint for chat completions on CRUN.
version: 1.0.0
contact:
name: Technical Support
email: support@crun.ai
servers:
- url: https://api.crun.ai
description: API Server
security:
- BearerAuth: []
- ApiKeyAuth: []
paths:
/api/v1/chat/completions:
post:
summary: Create a chat completion
description: >-
OpenAI-compatible chat completions endpoint.
- Use `Authorization: Bearer YOUR_API_KEY` with official OpenAI SDKs.
- Use `X-API-KEY: YOUR_API_KEY` for direct HTTP requests.
- When `stream=true`, the response is returned as Server-Sent Events
(`text/event-stream`).
operationId: models/llm/chat-completions
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChatCompletionsRequest'
examples:
basic:
summary: Standard request
value:
model: gpt-4o-mini
messages:
- role: system
content: You are a helpful assistant.
- role: user
content: Write a short tagline for a coffee brand.
temperature: 0.7
stream:
summary: Streaming request
value:
model: gpt-4o-mini
stream: true
messages:
- role: user
content: Explain vector databases in simple terms.
stream_options:
include_usage: true
structuredOutput:
summary: Structured output request
value:
model: gpt-5.4
messages:
- role: system
content: Extract tasks as JSON only.
- role: user
content: Maya should send the launch brief by Friday.
response_format:
type: json_schema
json_schema:
name: task
strict: true
schema:
type: object
properties:
owner:
type: string
task:
type: string
due:
type: string
required:
- owner
- task
- due
additionalProperties: false
toolCalling:
summary: Tool calling request
value:
model: gpt-5.4
messages:
- role: user
content: What is the weather like in Paris?
tools:
- type: function
function:
name: get_weather
description: Get current weather for a city.
parameters:
type: object
properties:
city:
type: string
required:
- city
additionalProperties: false
tool_choice: auto
vision:
summary: Vision input request
value:
model: gpt-5.4
messages:
- role: user
content:
- type: text
text: Describe this chart in one paragraph.
- type: image_url
image_url:
url: https://example.com/chart.png
max_completion_tokens: 300
responses:
'200':
description: >-
Successful completion response. Returns JSON when `stream=false`, or
SSE when `stream=true`.
content:
application/json:
schema:
$ref: '#/components/schemas/ChatCompletionResponse'
example:
id: chatcmpl_abc123
object: chat.completion
created: 1772294400
model: gpt-4o-mini
choices:
- index: 0
message:
role: assistant
content: >-
Bright flavor, smooth finish, and roasted for everyday
focus.
finish_reason: stop
usage:
prompt_tokens: 18
completion_tokens: 13
total_tokens: 31
text/event-stream:
schema:
type: string
description: >-
Server-Sent Events stream. Each chunk is prefixed with `data:`
and terminated by a blank line.
example: >+
data:
{"id":"chatcmpl_abc123","object":"chat.completion.chunk","created":1772294400,"model":"gpt-4o-mini","choices":[{"index":0,"delta":{"role":"assistant","content":"Hello"},"finish_reason":null}]}
data:
{"id":"chatcmpl_abc123","object":"chat.completion.chunk","created":1772294400,"model":"gpt-4o-mini","choices":[],"usage":{"prompt_tokens":18,"completion_tokens":1,"total_tokens":19}}
data: [DONE]
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/InsufficientCredits'
'404':
$ref: '#/components/responses/ModelNotFound'
'422':
$ref: '#/components/responses/ValidationError'
'429':
$ref: '#/components/responses/RateLimit'
'503':
$ref: '#/components/responses/ServiceUnavailable'
components:
schemas:
ChatCompletionsRequest:
type: object
description: >-
OpenAI-compatible Chat Completions request. Additional compatible fields
are accepted and passed through when supported by the upstream model.
properties:
model:
type: string
minLength: 1
maxLength: 128
description: Public model ID returned by `GET /api/v1/models`.
example: gpt-4o-mini
messages:
type: array
minItems: 1
description: Conversation messages in OpenAI format.
items:
$ref: '#/components/schemas/ChatMessage'
temperature:
type: number
minimum: 0
maximum: 2
description: Sampling temperature.
example: 0.7
top_p:
type: number
minimum: 0
maximum: 1
description: Nucleus sampling value.
example: 1
'n':
type: integer
minimum: 1
maximum: 8
default: 1
description: Number of completion choices to generate.
example: 1
stream:
type: boolean
default: false
description: Whether to return a Server-Sent Events stream.
example: false
stop:
description: Stop sequence or list of stop sequences.
oneOf:
- type: string
example: '###'
- type: array
items:
type: string
example:
- '###'
- END
max_tokens:
type: integer
minimum: 1
description: Maximum output tokens. Capped by the selected model.
example: 512
max_completion_tokens:
type: integer
minimum: 1
description: Maximum completion tokens. Capped by the selected model.
example: 512
presence_penalty:
type: number
minimum: -2
maximum: 2
description: Presence penalty value.
example: 0
frequency_penalty:
type: number
minimum: -2
maximum: 2
description: Frequency penalty value.
example: 0
user:
type: string
description: End-user identifier passed for observability.
example: user_123
stream_options:
type: object
description: >-
Streaming options. When `stream=true`, CRUN enables
`include_usage=true` by default if omitted.
additionalProperties: true
example:
include_usage: true
response_format:
type: object
description: >-
Structured output option in OpenAI-compatible format. Chat
Completions uses `response_format`; Responses uses `text.format`.
additionalProperties: true
example:
type: json_object
tools:
type: array
description: >-
Tool definitions in OpenAI-compatible format. Your application
executes tool calls and returns tool results in a follow-up request.
items:
type: object
additionalProperties: true
tool_choice:
description: Tool selection strategy.
oneOf:
- type: string
example: auto
- type: object
additionalProperties: true
required:
- model
- messages
additionalProperties: true
ChatCompletionResponse:
type: object
properties:
id:
type: string
example: chatcmpl_abc123
object:
type: string
example: chat.completion
created:
type: integer
description: Unix timestamp in seconds.
example: 1772294400
model:
type: string
description: Public model ID requested by the client.
example: gpt-4o-mini
choices:
type: array
items:
$ref: '#/components/schemas/ChatCompletionChoice'
usage:
$ref: '#/components/schemas/CompletionUsage'
required:
- id
- object
- created
- model
- choices
ChatMessage:
type: object
description: >-
OpenAI-compatible message object. Additional compatible fields are
allowed.
properties:
role:
type: string
enum:
- system
- user
- assistant
- tool
- developer
- function
description: Message role.
example: user
content:
description: >-
Message content. Can be a plain string or a multimodal content
array.
nullable: true
oneOf:
- type: string
example: Write a short tagline for a coffee brand.
- type: array
items:
oneOf:
- type: string
- $ref: '#/components/schemas/MessageContentPart'
name:
type: string
nullable: true
description: Optional participant name.
example: planner
tool_call_id:
type: string
nullable: true
description: Tool call identifier for tool messages.
example: call_123
required:
- role
additionalProperties: true
ChatCompletionChoice:
type: object
properties:
index:
type: integer
example: 0
message:
$ref: '#/components/schemas/AssistantMessage'
finish_reason:
type: string
nullable: true
example: stop
required:
- index
- message
CompletionUsage:
type: object
properties:
prompt_tokens:
type: integer
example: 18
completion_tokens:
type: integer
example: 24
total_tokens:
type: integer
example: 42
OpenAIErrorResponse:
type: object
properties:
error:
$ref: '#/components/schemas/OpenAIError'
required:
- error
MessageContentPart:
type: object
description: >-
One item inside a multimodal content array. Structure depends on the
client and upstream model.
additionalProperties: true
example:
type: text
text: Hello
AssistantMessage:
type: object
properties:
role:
type: string
example: assistant
content:
description: Assistant message content.
nullable: true
oneOf:
- type: string
example: >-
Serverless functions eliminate server management and scale
automatically.
- type: array
items:
oneOf:
- type: string
- $ref: '#/components/schemas/MessageContentPart'
required:
- role
OpenAIError:
type: object
properties:
message:
type: string
description: Human-readable error message.
example: The model `unknown-model` does not exist.
type:
type: string
description: OpenAI-style error type.
example: invalid_request_error
param:
type: string
nullable: true
description: Related request parameter, if available.
example: model
code:
type: string
nullable: true
description: Machine-readable error code, if available.
example: model_not_found
required:
- message
- type
responses:
BadRequest:
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIErrorResponse'
example:
error:
message: Invalid JSON body
type: invalid_request_error
param: null
code: null
Unauthorized:
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIErrorResponse'
example:
error:
message: API key missing
type: authentication_error
param: null
code: invalid_api_key
InsufficientCredits:
description: Insufficient credits
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIErrorResponse'
example:
error:
message: Insufficient Credits
type: insufficient_quota
param: null
code: insufficient_credits
ModelNotFound:
description: Unknown model ID
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIErrorResponse'
example:
error:
message: The model `unknown-model` does not exist.
type: invalid_request_error
param: null
code: model_not_found
ValidationError:
description: Request validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIErrorResponse'
example:
error:
message: Field `messages` is required.
type: invalid_request_error
param: null
code: null
RateLimit:
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIErrorResponse'
example:
error:
message: Rate limit reached for this account, please retry later.
type: rate_limit_error
param: null
code: rate_limit_exceeded
ServiceUnavailable:
description: Upstream or internal service failure
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIErrorResponse'
example:
error:
message: Upstream request failed
type: api_error
param: null
code: null
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: Use your CRUN API key as a Bearer token for OpenAI-compatible SDKs.
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: Use your CRUN API key in the `X-API-KEY` header.
````