> ## 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
> CRUN 语言模型的 OpenAI 兼容 /chat/completions 接口。
## API 地址
```text theme={null}
POST https://api.crun.ai/api/v1/chat/completions
```
该接口遵循 [OpenAI Chat Completions](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create) 的请求和响应格式。
您可以直接搭配官方 OpenAI SDK，或其他 OpenAI 兼容客户端使用。
## 身份验证
您可以使用以下任一方式进行身份验证：
* `Authorization: Bearer YOUR_API_KEY`
* `X-API-KEY: YOUR_API_KEY`
## 请求示例
```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);
```
## 对话历史示例
CRUN 不会为您的应用管理多轮对话上下文。
如需继续一段对话，您必须自行维护历史消息，并在每次新请求中传入相关上下文。
```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);
```
## 结构化输出示例
当您需要模型返回 JSON 时，可以使用 `response_format`。如果需要严格遵循 JSON Schema，请选择支持 `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);
```
## 工具调用示例
Chat Completions 接受 OpenAI 兼容的 `tools` 与 `tool_choice` 字段。您的应用需要自行执行工具调用，并在后续请求中把工具结果传回模型。
```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"
}
```
## 视觉输入示例
当所选模型支持图像输入时，可以在用户消息中传入多模态 content parts。
```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
}
```
## 流式请求示例
设置 `stream=true` 后，可以接收 Server-Sent Events。CRUN 会在可用时为流式请求启用 usage 信息。
```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);
}
```
## 响应示例
```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]
```
## 注意事项
* 设置 `stream=true` 可接收 `text/event-stream` 响应。
* 如果省略 `stream_options.include_usage`，CRUN 会自动为流式请求启用该选项。
* `max_tokens` 和 `max_completion_tokens` 都可以使用，并会受所选模型的输出 token 上限约束。
* 未知模型 ID 会返回 OpenAI 风格的错误体，其中 `code` 为 `"model_not_found"`。
* 对于新的有状态、工具密集或结构化输出工作流，也可以考虑 `/responses` 接口。Responses 使用 `input`、`instructions` 和 `text.format`，而不是 `messages` 和 `response_format`。
## 相关资源
使用灵活输入、有状态追问、结构化输出和工具就绪的 response items 构建应用。
了解 base URL、身份验证方式以及官方 SDK 的接入模式。
浏览所有可用的图像、视频、音频和语言模型 API。
前往价格页面，比较不同模型的计费规则。
## OpenAPI
````yaml zh/models/llm/chat-completions.json post /api/v1/chat/completions
openapi: 3.0.0
info:
title: CRUN OpenAI 兼容 Chat Completions API
description: CRUN 语言模型的 OpenAI 兼容 Chat Completions 接口。
version: 1.0.0
contact:
name: Technical Support
email: support@crun.ai
servers:
- url: https://api.crun.ai
description: API 服务器
security:
- BearerAuth: []
- ApiKeyAuth: []
paths:
/api/v1/chat/completions:
post:
summary: 创建 Chat Completion
description: |-
OpenAI 兼容的 Chat Completions 接口。
- 使用官方 OpenAI SDK 时，请使用 `Authorization: Bearer YOUR_API_KEY`。
- 直接发起 HTTP 请求时，可以使用 `X-API-KEY: YOUR_API_KEY`。
- 当 `stream=true` 时，响应会以 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: 标准请求
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: 流式请求
value:
model: gpt-4o-mini
stream: true
messages:
- role: user
content: Explain vector databases in simple terms.
stream_options:
include_usage: true
structuredOutput:
summary: 结构化输出请求
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: 工具调用请求
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: 视觉输入请求
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: 成功的补全响应。`stream=false` 时返回 JSON，`stream=true` 时返回 SSE。
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 流。每个片段以 `data:` 开头，并以空行结束。
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 兼容的 Chat Completions 请求。其他兼容字段会被接受，并在模型支持时透传。
properties:
model:
type: string
minLength: 1
maxLength: 128
description: 由 `GET /api/v1/models` 返回的公开模型 ID。
example: gpt-4o-mini
messages:
type: array
minItems: 1
description: OpenAI 格式的对话消息。
items:
$ref: '#/components/schemas/ChatMessage'
temperature:
type: number
minimum: 0
maximum: 2
description: 采样温度。
example: 0.7
top_p:
type: number
minimum: 0
maximum: 1
description: 核采样参数。
example: 1
'n':
type: integer
minimum: 1
maximum: 8
default: 1
description: 要生成的补全结果数量。
example: 1
stream:
type: boolean
default: false
description: 是否返回 Server-Sent Events 流式响应。
example: false
stop:
description: 停止序列或停止序列列表。
oneOf:
- type: string
example: '###'
- type: array
items:
type: string
example:
- '###'
- END
max_tokens:
type: integer
minimum: 1
description: 最大输出 token 数，会受所选模型上限限制。
example: 512
max_completion_tokens:
type: integer
minimum: 1
description: 最大补全 token 数，会受所选模型上限限制。
example: 512
presence_penalty:
type: number
minimum: -2
maximum: 2
description: Presence penalty 参数。
example: 0
frequency_penalty:
type: number
minimum: -2
maximum: 2
description: Frequency penalty 参数。
example: 0
user:
type: string
description: 用于可观测性的终端用户标识。
example: user_123
stream_options:
type: object
description: 流式输出选项。当 `stream=true` 且未传入该字段时，CRUN 默认启用 `include_usage=true`。
additionalProperties: true
example:
include_usage: true
response_format:
type: object
description: >-
OpenAI 兼容结构化输出选项。Chat Completions 使用 `response_format`；Responses 使用
`text.format`。
additionalProperties: true
example:
type: json_object
tools:
type: array
description: OpenAI 兼容工具定义。应用需要执行工具调用，并在后续请求中返回工具结果。
items:
type: object
additionalProperties: true
tool_choice:
description: 工具选择策略。
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 时间戳，单位为秒。
example: 1772294400
model:
type: string
description: 客户端请求的公开模型 ID。
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 兼容的消息对象。允许传入其他兼容字段。
properties:
role:
type: string
enum:
- system
- user
- assistant
- tool
- developer
- function
description: 消息角色。
example: user
content:
description: 消息内容。可以是普通字符串，也可以是多模态内容数组。
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: 可选的参与者名称。
example: planner
tool_call_id:
type: string
nullable: true
description: 工具消息对应的工具调用 ID。
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: 多模态内容数组中的一个项目。具体结构取决于客户端和模型支持情况。
additionalProperties: true
example:
type: text
text: Hello
AssistantMessage:
type: object
properties:
role:
type: string
example: assistant
content:
description: 助手消息内容。
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: 面向用户可读的错误信息。
example: The model `unknown-model` does not exist.
type:
type: string
description: OpenAI 风格的错误类型。
example: invalid_request_error
param:
type: string
nullable: true
description: 相关请求参数。如果可用，会返回该字段。
example: model
code:
type: string
nullable: true
description: 机器可读的错误码。如果可用，会返回该字段。
example: model_not_found
required:
- message
- type
responses:
BadRequest:
description: 无效请求
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIErrorResponse'
example:
error:
message: Invalid JSON body
type: invalid_request_error
param: null
code: null
Unauthorized:
description: 身份验证失败
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: 积分不足
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIErrorResponse'
example:
error:
message: Insufficient Credits
type: insufficient_quota
param: null
code: insufficient_credits
ModelNotFound:
description: 未知模型 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: 请求校验失败
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: 超过速率限制
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: 上游或内部服务失败
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: 在 OpenAI 兼容 SDK 中，将您的 CRUN API Key 作为 Bearer token 使用。
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: 在 `X-API-KEY` 请求头中使用您的 CRUN API Key。
````