General Chat Interface (Default Streaming)

• Route: POST /v1/chat/completions
• The same route supports both streaming and non-streaming; this page demonstrates streaming calls
• Successful responses follow the original OpenAI protocol without an extra code / data wrapper

Request Example

curl --request POST \
  --url https://api.magickapi.com/v1/chat/completions \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-5",
    "stream": true,
    "stream_options": { "include_usage": true },
    "messages": [
      {
        "role": "system",
        "content": "你是一个专业的 AI 助手。"
      },
      {
        "role": "user",
        "content": "介绍一下人工智能的发展历史。"
      }
    ]
  }'

Streaming Response Example

data: {"id":"chatcmpl_123","object":"chat.completion.chunk","created":1712345678,"model":"gpt-5","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl_123","object":"chat.completion.chunk","created":1712345678,"model":"gpt-5","choices":[{"index":0,"delta":{"content":"人工智能"},"finish_reason":null}]}

data: {"id":"chatcmpl_123","object":"chat.completion.chunk","created":1712345678,"model":"gpt-5","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":28,"completion_tokens":18,"total_tokens":46}}

data: [DONE]

Error Response Example

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_request"
  }
}

Authentication

• Request header: Authorization: Bearer YOUR_API_KEY
• For the API Key, use the key generated from the Magick API dashboard.

Common Parameters

model

• Type: string

• Required: Yes

  Pass the specific model ID. The project will select the upstream model based on channel mapping and distribution rules.

messages

• Type: array

• Required: Yes

  Consistent with the OpenAI Chat Completions protocol. Each message must contain at least role and content.

stream

• Type: boolean

• Default: true

  Whether to use streaming output. When omitted, many clients will send according to their own default behavior; if you want to force streaming, it is recommended to explicitly pass true.

stream_options

• Type: object

  The current project supports OpenAI-style stream_options. Common usage:

{
  "stream_options": {
    "include_usage": true
  }
}

Other Common Fields

The following OpenAI-compatible fields can be used directly; whether they are ultimately accepted by the upstream depends on the model and channel capabilities:

• temperature
• top_p
• max_tokens
• max_completion_tokens
• tools
• tool_choice
• response_format
• reasoning_effort

Compatibility Notes

• POST /v1/completions still exists, but it is recommended to use POST /v1/chat/completions for new integrations.