diff --git a/docs/llmservice/api/API.md b/docs/llmservice/api/API.md index b638cdf3..ba141cbd 100644 --- a/docs/llmservice/api/API.md +++ b/docs/llmservice/api/API.md @@ -1,39 +1,106 @@ -# AI API +# B.AI API Reference -Chat completion. Auth: Bearer token. Non-stream: JSON with choices[].content. Stream: SSE chunks with choices[].delta.content. +B.AI provides a unified large language model API compatible with the OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages protocols. Use the same B.AI API Key with different protocols and choose the endpoint that matches your application or client. -- **Version:** 1.0 -- **Base URL:** `https://api.bankofai.io` -- **OpenAPI:** 3.1.0 +- **API version:** `v1` +- **Production Base URL:** `https://api.b.ai/v1` +- **Request format:** `application/json` +- **Character encoding:** UTF-8 +- **Streaming:** Server-Sent Events (SSE) + +--- + +## Quick Start + +### 1. Set the API Key + +macOS, Linux, or WSL: + +```bash +export BAI_API_KEY="sk-..." +``` + +Windows PowerShell: + +```powershell +$env:BAI_API_KEY = "sk-..." +``` + +### 2. Send Your First Responses Request + +```bash +curl https://api.b.ai/v1/responses \ + -H "Authorization: Bearer $BAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "your-model-id", + "input": "Introduce B.AI in one sentence." + }' +``` + +On success, the server returns HTTP `200` and a `response` object. + +Replace `your-model-id` with a model ID enabled for the selected endpoint. --- ## Authentication +B.AI supports the following authentication headers. Both use the same platform-issued API Key; choose either one. + ### Bearer Token -- **Type:** HTTP Bearer (JWT) -- **Header:** `Authorization: Bearer ` -- **Example:** `Bearer sk-xxx` +```http +Authorization: Bearer +``` + +Example: + +```bash +-H "Authorization: Bearer $BAI_API_KEY" +``` + +### x-api-key -### API Key (Messages endpoint only) +```http +x-api-key: +``` + +Example: + +```bash +-H "x-api-key: $BAI_API_KEY" +``` -- **Type:** API Key -- **Header:** `x-api-key: ` +> The two headers are equivalent. Codex, the OpenAI SDK, and most OpenAI-compatible clients use `Authorization`. --- -## Endpoints +## Endpoint Overview + +| Method | Endpoint | Protocol | Use case | +|---|---|---|---| +| `GET` | `/models` | OpenAI-compatible | List models associated with the current credential | +| `POST` | `/responses` | OpenAI Responses | Agents, reasoning, tool use, and Codex | +| `POST` | `/chat/completions` | OpenAI Chat Completions | General chat completions and existing OpenAI-compatible applications | +| `POST` | `/messages` | Anthropic Messages | Claude SDK, Claude Code, and other Anthropic-compatible clients | + +--- -### 1. List Models +## List Models `GET /v1/models` -List available models. Auth: Bearer token. +Returns the model list associated with the current API credential. -**Auth:** Bearer Token +### Request Example -**Response 200:** +```bash +curl https://api.b.ai/v1/models \ + -H "Authorization: Bearer $BAI_API_KEY" +``` + +### Response Example ```json { @@ -41,380 +108,713 @@ List available models. Auth: Bearer token. "success": true, "data": [ { - "id": "gpt-5.2", + "id": "your-model-id", "object": "model", - "created": 1626777600, - "owned_by": "openai", - "supported_endpoint_types": ["openai", "anthropic"] + "created": 1626777600 } ] } ``` -| Status | Description | -|--------|-------------| -| 200 | Success - list of models | -| 400 | Bad Request - invalid parameters or malformed body | -| 401 | Unauthorized - invalid or missing authentication | -| 403 | Forbidden - access denied, insufficient quota, or banned | -| 429 | Too Many Requests - rate limit exceeded | -| 500 | Internal Server Error | - --- -### 2. Chat Completions (OpenAI Compatible) +## Responses API (OpenAI-Compatible) -`POST /v1/chat/completions` +`POST /v1/responses` + +The Responses API accepts model input and returns generated output. Depending on the selected model and configuration, requests can use streaming, reasoning, function calling, and web search. The endpoint can also be used by clients such as Codex that use the Responses protocol. + +- **Full URL:** `https://api.b.ai/v1/responses` +- **Authentication:** Bearer Token or `x-api-key` +- **Non-streaming response:** JSON +- **Streaming response:** SSE + +The request structure of the Responses API differs from Chat Completions: -Accepts a list of messages and returns a model-generated response. Supports both single-turn and multi-turn conversations. Responses can be streamed (SSE) or returned as a single JSON object. +- Use `input` instead of `messages`. +- Use `max_output_tokens` instead of `max_tokens`. +- Use the `output` array for messages, reasoning, tool calls, and other output items. +- Streaming mode returns named Responses events instead of Chat Completion chunks. -**Auth:** Bearer Token +### Model and Endpoint Compatibility -#### Request Body +The Responses endpoint accepts models enabled for this protocol. If the model and endpoint are incompatible, the server returns HTTP `400` with error details. + +### Request Body | Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `model` | string | **Yes** | ID of the model to use (e.g. `gpt-5.2`). | -| `messages` | array | **Yes** | List of messages in the conversation. See [ChatMessage](#chatmessage). | -| `stream` | boolean | No | If true, partial message deltas will be sent as server-sent events. Default `false`. | -| `max_tokens` | integer | No | Maximum number of tokens that can be generated in the completion. | -| `temperature` | number | No | Sampling temperature between 0 and 2. Higher = more random. Default `1`. | -| `top_p` | number | No | Nucleus sampling: consider tokens with top_p probability mass. Default `1`. | -| `stop` | string \| string[] | No | Up to 4 sequences where the API will stop generating. | -| `n` | integer | No | How many chat completion choices to generate. Default `1`. | -| `frequency_penalty` | number | No | -2.0 to 2.0. Penalize repeated tokens. Default `0`. | -| `presence_penalty` | number | No | -2.0 to 2.0. Penalize tokens that appear in the text so far. Default `0`. | -| `seed` | integer | No | Random seed for deterministic sampling (if supported by model). | -| `response_format` | object | No | Specify output format: `{ "type": "text" }` or `{ "type": "json_object" }` or `json_schema`. | -| `tools` | array | No | List of tools the model may call. See [ChatTool](#chattool). | -| `tool_choice` | string \| object | No | `"auto"`, `"none"`, `"required"`, or `{ "type": "function", "function": { "name": "..." } }`. | -| `user` | string | No | Optional end-user identifier for abuse monitoring. | -| `web_search_options` | object | No | Enables web search for supported models. See [WebSearchOptions](#websearchoptions). | - -#### Request Example +|---|---|---:|---| +| `model` | string | Yes | The model ID to use. | +| `input` | string \| array | Yes | Input content as a string or an array of Responses input items. | +| `instructions` | string | No | System-level or developer-level instructions. | +| `stream` | boolean | No | Whether to return an SSE stream. Default `false`. | +| `max_output_tokens` | integer | No | Maximum output tokens, including visible output and reasoning tokens. The allowed range depends on the selected model; values outside the range return `400` with the allowed range in the error. | +| `reasoning` | object | No | Reasoning configuration, such as `effort` and `summary`; available values depend on the model. | +| `tools` | array | No | Tools the model can call, such as functions or web search. | +| `tool_choice` | string \| object | No | Controls whether and how the model selects a tool. | +| `parallel_tool_calls` | boolean | No | Whether parallel tool calls are allowed. | +| `text` | object | No | Text output configuration, including structured output format; availability depends on the model. | +| `temperature` | number | No | Sampling temperature; some reasoning models do not support it. | +| `top_p` | number | No | Nucleus sampling parameter; some reasoning models do not support it. | + +#### Unsupported Parameters + +| Parameter | API behavior | +|---|---| +| `max_tokens` | Returns `400`; use `max_output_tokens` instead. | +| `max_completion_tokens` | Returns `400`; use `max_output_tokens` instead. | + +### Simple Text Input ```json { - "model": "gpt-5.2", - "messages": [ - { "role": "system", "content": "You are a helpful assistant." }, - { "role": "user", "content": "Hello" } - ], - "stream": false, - "max_tokens": 1024, - "temperature": 1 + "model": "your-model-id", + "input": "Summarize the three core concepts of quantum computing." } ``` -#### Response (Non-stream) +### Input with Instructions ```json { - "id": "chatcmpl-xxx", - "object": "chat.completion", - "created": 1677652288, - "model": "gpt-5.2", - "choices": [ + "model": "your-model-id", + "instructions": "You are a professional and concise technical writing assistant.", + "input": [ { - "index": 0, - "message": { - "role": "assistant", - "content": "Hello! How can I help you?", - "refusal": null, - "annotations": [] - }, - "finish_reason": "stop" + "role": "user", + "content": "Explain vector databases in a way a beginner can understand." + } + ] +} +``` + +Input items can use roles such as `system`, `developer`, `user`, and `assistant`. The supported content block types depend on the selected model. + +### Non-Streaming Request + +When `stream` is `false` or omitted, the API returns the complete JSON response after the model finishes generating. + +#### cURL + +```bash +curl https://api.b.ai/v1/responses \ + -H "Authorization: Bearer $BAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "your-model-id", + "input": "Explain the Responses API in three sentences.", + "max_output_tokens": 512 + }' +``` + +#### Response Example + +```json +{ + "id": "resp_01HXYZ...", + "object": "response", + "created_at": 1787587200, + "status": "completed", + "model": "your-model-id", + "output": [ + { + "id": "msg_01HXYZ...", + "type": "message", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "The Responses API is a unified model response interface...", + "annotations": [] + } + ] } ], "usage": { - "prompt_tokens": 12, - "completion_tokens": 8, - "total_tokens": 20, - "prompt_tokens_details": { "cached_tokens": 0, "audio_tokens": 0 }, - "completion_tokens_details": { - "reasoning_tokens": 0, - "audio_tokens": 0, - "accepted_prediction_tokens": 0, - "rejected_prediction_tokens": 0 - } + "input_tokens": 18, + "output_tokens": 42, + "output_tokens_details": { + "reasoning_tokens": 12 + }, + "total_tokens": 60 } } ``` -#### Response (Stream) +`output` may contain several item types at the same time, including reasoning, message, function call, and web search call items. `output[0]` is not guaranteed to be the assistant's text. -Each SSE chunk has `object: "chat.completion.chunk"` with `choices[].delta.content` containing incremental text. The final chunk includes `usage` and `finish_reason`. +The OpenAI SDK's `response.output_text` aggregates all `output_text` content blocks under `output` items whose `type` is `message`. -| Status | Description | -|--------|-------------| -| 200 | Success | -| 400 | Bad Request - invalid parameters, malformed body, or invalid request | -| 401 | Unauthorized - invalid or missing authentication | -| 403 | Forbidden - access denied, insufficient quota, or model access restricted | -| 429 | Too Many Requests - rate limit exceeded | -| 500 | Internal Server Error | -| 502 | Bad Gateway - upstream service error | -| 503 | Service Unavailable - overloaded or no available channel | +### Streaming Request ---- +When `stream: true`, the API continuously returns events over SSE while the model generates a response. -### 3. Messages (Claude Compatible) +```bash +curl -N https://api.b.ai/v1/responses \ + -H "Authorization: Bearer $BAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "your-model-id", + "input": "Write a short introduction to the development of artificial intelligence.", + "stream": true, + "max_output_tokens": 512 + }' +``` -`POST /v1/messages` +Common events: -Accepts a list of messages and returns a model-generated response. Supports both single-turn and multi-turn conversations. Authenticate via `x-api-key` header or Bearer token. Responses can be streamed (SSE) or returned as a single JSON object. +| Event type | Description | +|---|---| +| `response.created` | The Response was created. | +| `response.in_progress` | The Response is being generated. | +| `response.output_item.added` | A new output item was added. | +| `response.content_part.added` | A new content part was added. | +| `response.output_text.delta` | A text delta. | +| `response.output_text.done` | Text output is complete. | +| `response.output_item.done` | The current output item is complete. | +| `response.completed` | The Response completed successfully. | +| `response.incomplete` | The Response ended early, for example because of an output limit. | +| `response.failed` | Response generation failed. | -**Auth:** API Key (`x-api-key`) or Bearer Token +The table lists common events. Clients should handle recognized event types and ignore events they do not need. -#### Request Body +Event example: -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `model` | string | **Yes** | ID of the model (e.g. `claude-sonnet-4-6`, `claude-opus-4-6`, `claude-haiku-4-5`). | -| `max_tokens` | integer | **Yes** | Maximum number of tokens to generate. Different models have different maximum values. | -| `messages` | array | **Yes** | Input messages. Alternating user/assistant turns. Limit: 100,000 messages. See [MessagesMessageItem](#messagesmessageitem). | -| `system` | string \| array | No | System prompt. Can be a plain string or an array of text blocks (for `cache_control`). | -| `stream` | boolean | No | Whether to stream the response using SSE. Default `false`. | -| `temperature` | number | No | Randomness (0.0 - 1.0). Use ~0.0 for analytical tasks, ~1.0 for creative tasks. Default `1`. | -| `top_p` | number | No | Nucleus sampling. Default `1`. | -| `top_k` | integer | No | Only sample from the top K options. Default disabled. | -| `stop_sequences` | string[] | No | Custom text sequences that cause the model to stop generating. | -| `metadata` | object | No | Request metadata. Supports `user_id` (opaque identifier). | -| `thinking` | object | No | Extended thinking config. See [ThinkingConfig](#thinkingconfig). | -| `tools` | array | No | Tool definitions the model may use. See [Tool](#tool-anthropic). | -| `tool_choice` | object | No | How the model should use tools: `auto`, `any`, `tool`, or `none`. | - -#### Request Example +```text +event: response.output_text.delta +data: {"type":"response.output_text.delta","delta":"Responses"} -```json -{ - "model": "claude-sonnet-4-6", - "max_tokens": 1024, - "messages": [ - { "role": "user", "content": "Hello, Claude!" } - ], - "system": "You are a helpful assistant.", - "temperature": 1.0 -} +event: response.output_text.delta +data: {"type":"response.output_text.delta","delta":" API"} + +event: response.completed +data: {"type":"response.completed","response":{"id":"resp_...","status":"completed"}} ``` -#### Response (Non-stream) +> If a streaming request fails before the SSE connection is established, the server returns a JSON error object with `Content-Type: application/json`. -```json -{ - "id": "chatcmpl-xxx", - "type": "message", - "role": "assistant", - "content": [ - { "type": "text", "text": "Hello! How can I help you?" } - ], - "stop_reason": "end_turn", - "model": "gpt-5", - "usage": { - "input_tokens": 4, - "cache_creation_input_tokens": 0, - "cache_read_input_tokens": 0, - "output_tokens": 12, - "claude_cache_creation_5_m_tokens": 0, - "claude_cache_creation_1_h_tokens": 0 - } -} +### Python SDK + +Install the OpenAI Python SDK: + +```bash +pip install openai ``` -#### Response (Stream - SSE Events) +Call the Responses API: -Stream responses emit the following event types: +```python +import os +from openai import OpenAI -| Event Type | Description | Key Fields | -|------------|-------------|------------| -| `message_start` | Initial message metadata | `message` (id, model, role, usage) | -| `content_block_start` | New content block begins | `index`, `content_block` (type, text) | -| `content_block_delta` | Incremental content | `index`, `delta` (type: `text_delta`, text) | -| `content_block_stop` | Content block ends | `index` | -| `message_stop` | Message complete | - | +client = OpenAI( + api_key=os.environ["BAI_API_KEY"], + base_url="https://api.b.ai/v1", +) -| Status | Description | -|--------|-------------| -| 200 | Success | -| 400 | Bad Request - invalid parameters, malformed body, or invalid request | -| 401 | Unauthorized - invalid or missing API key | -| 403 | Forbidden - access denied, insufficient quota, or model access restricted | -| 429 | Too Many Requests - rate limit exceeded | -| 500 | Internal Server Error | -| 502 | Bad Gateway - upstream service error | -| 503 | Service Unavailable - overloaded or no available channel | +response = client.responses.create( + model="your-model-id", + input="Explain the Responses API in three sentences.", +) ---- +print(response.output_text) +``` -## Data Models +### JavaScript SDK -### ChatMessage +Install the OpenAI JavaScript SDK: -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `role` | string | **Yes** | `"system"`, `"user"`, `"assistant"`, or `"tool"` | -| `content` | string | **Yes** | Message content. For tool role, the result of the tool call. | -| `name` | string | No | Optional name for the message author. | -| `tool_call_id` | string | No | When role is `"tool"`, the ID of the tool call this result is for. | -| `tool_calls` | array | No | When role is `"assistant"` and the model called tools. Array of `{ id, type, function: { name, arguments } }`. | +```bash +npm install openai +``` -### MessagesMessageItem +Call the Responses API: -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `role` | string | **Yes** | `"user"` or `"assistant"` (no `"system"` - use top-level `system` parameter). | -| `content` | string \| array | **Yes** | Text string or array of content blocks (text, image, tool_use, tool_result). | +```javascript +import OpenAI from "openai"; -### Content Block Types (Messages API) +const client = new OpenAI({ + apiKey: process.env.BAI_API_KEY, + baseURL: "https://api.b.ai/v1", +}); -#### TextBlockParam +const response = await client.responses.create({ + model: "your-model-id", + input: "Explain the Responses API in three sentences.", +}); -```json -{ "type": "text", "text": "Hello, Claude!", "cache_control": { "type": "ephemeral" } } +console.log(response.output_text); ``` -#### ImageBlockParam +### Reasoning Configuration + +Models that support reasoning can use `reasoning` to configure reasoning effort and summaries: -Base64 source: ```json { - "type": "image", - "source": { - "type": "base64", - "media_type": "image/jpeg", - "data": "/9j/4AAQSkZJRg..." + "model": "your-model-id", + "input": "Analyze the performance bottlenecks in this system design.", + "reasoning": { + "effort": "high", + "summary": "auto" } } ``` -URL source: +Available reasoning levels depend on the selected model. Unsupported configurations may return HTTP `400`. + +Reasoning token usage is available at: + +```text +usage.output_tokens_details.reasoning_tokens +``` + +Reasoning tokens count toward `max_output_tokens`. If the value is too low, the model may exhaust its budget before producing visible text and return a response with `status` set to `incomplete`. + +### Function Calling + +#### Step 1: Declare a Function + ```json { - "type": "image", - "source": { - "type": "url", - "url": "https://example.com/image.jpg" - } + "model": "your-model-id", + "max_output_tokens": 512, + "input": [ + { + "role": "user", + "content": "What's the weather like in Shenzhen today?" + } + ], + "tools": [ + { + "type": "function", + "name": "get_weather", + "description": "Get the weather for a specified city", + "parameters": { + "type": "object", + "properties": { + "city": { + "type": "string", + "description": "City name" + } + }, + "required": ["city"], + "additionalProperties": false + }, + "strict": true + } + ], + "tool_choice": "auto" } ``` -Supported media types: `image/jpeg`, `image/png`, `image/gif`, `image/webp` - -#### ToolUseBlockParam (from assistant) +When the model decides to call the function, a `function_call` item appears in `output`: ```json { - "type": "tool_use", - "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", - "name": "get_stock_price", - "input": { "ticker": "AAPL" } + "type": "function_call", + "call_id": "call_01HXYZ...", + "name": "get_weather", + "arguments": "{\"city\":\"Shenzhen\"}" } ``` -#### ToolResultBlockParam (from user) +#### Step 2: Submit the Function Result + +In the next request's `input`, include the original conversation, the `function_call` returned by the model, and the `function_call_output` result in order: ```json { - "type": "tool_result", - "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", - "content": "259.75 USD", - "is_error": false + "model": "your-model-id", + "max_output_tokens": 512, + "tools": [ + { + "type": "function", + "name": "get_weather", + "description": "Get the weather for a specified city", + "parameters": { + "type": "object", + "properties": { + "city": { + "type": "string", + "description": "City name" + } + }, + "required": ["city"], + "additionalProperties": false + }, + "strict": true + } + ], + "input": [ + { + "role": "user", + "content": "What's the weather like in Shenzhen today?" + }, + { + "type": "function_call", + "call_id": "call_01HXYZ...", + "name": "get_weather", + "arguments": "{\"city\":\"Shenzhen\"}" + }, + { + "type": "function_call_output", + "call_id": "call_01HXYZ...", + "output": "Shenzhen: Clear, 28°C" + } + ] } ``` -### ThinkingConfig +`call_id` must match the value returned by the model. Include the tool definition in subsequent requests as well. + +### Web Search -Enable extended thinking to let Claude show its reasoning process. +Models that support web search can use the `web_search` tool: -**Enabled:** ```json -{ "type": "enabled", "budget_tokens": 1024 } +{ + "model": "your-model-id", + "input": "Summarize three noteworthy artificial intelligence news stories from today.", + "tools": [ + { + "type": "web_search" + } + ] +} ``` -- `budget_tokens`: Must be >= 1024 and less than `max_tokens`. -**Disabled:** +Web search availability and fees depend on the selected model and request configuration. + +### Multi-Turn Conversations + +The example below organizes a multi-turn conversation as stateless requests. Include the context required for the next response in the subsequent request's `input`: + ```json -{ "type": "disabled" } +{ + "model": "your-model-id", + "input": [ + { + "role": "user", + "content": "What is a vector database?" + }, + { + "role": "assistant", + "content": "A vector database is a database designed to store and retrieve vector representations." + }, + { + "role": "user", + "content": "What are its three most common applications?" + } + ] +} +``` + +Each subsequent request only needs the context required to generate the next response. + +--- + +## Chat Completions API (OpenAI-Compatible) + +`POST /v1/chat/completions` + +Accepts a list of messages and returns a model-generated response. It is suitable for applications that already use the OpenAI Chat Completions protocol. + +### Main Request Parameters + +| Parameter | Type | Required | Description | +|---|---|---:|---| +| `model` | string | Yes | Model ID. | +| `messages` | array | Yes | Conversation message list. | +| `stream` | boolean | No | Whether to return an SSE stream. Default `false`. | +| `max_tokens` | integer | No | Maximum output tokens. Some models also support `max_completion_tokens`. | +| `temperature` | number | No | Sampling temperature; the supported range depends on the model. | +| `top_p` | number | No | Nucleus sampling parameter. | +| `stop` | string \| string[] | No | Stop sequences. | +| `response_format` | object | No | Text, JSON Object, or JSON Schema output configuration. | +| `tools` | array | No | Function tool definitions. | +| `tool_choice` | string \| object | No | Tool selection mode. | +| `web_search_options` | object | No | Web search configuration for supported models. | +| `user` | string | No | End-user identifier. | + +### Request Example + +```bash +curl https://api.b.ai/v1/chat/completions \ + -H "Authorization: Bearer $BAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "your-model-id", + "messages": [ + {"role": "system", "content": "You are a helpful assistant."}, + {"role": "user", "content": "Hello"} + ], + "stream": false, + "max_tokens": 512 + }' ``` -### Tool (Anthropic) +### Non-Streaming Response Example ```json { - "name": "get_stock_price", - "description": "Get the current stock price for a given ticker symbol.", - "input_schema": { - "type": "object", - "properties": { - "ticker": { "type": "string" } - }, - "required": ["ticker"] + "id": "chatcmpl-xxx", + "object": "chat.completion", + "created": 1787587200, + "model": "your-model-id", + "choices": [ + { + "index": 0, + "message": { + "role": "assistant", + "content": "Hello! How can I help you?" + }, + "finish_reason": "stop" + } + ], + "usage": { + "prompt_tokens": 12, + "completion_tokens": 8, + "total_tokens": 20 } } ``` -### ToolChoice (Anthropic) +### Streaming Response + +When `stream: true`, the server returns `text/event-stream`. Each chunk has `object` set to `chat.completion.chunk`, and incremental text is available at: + +```text +choices[].delta.content +``` + +--- + +## Messages API (Anthropic-Compatible) + +`POST /v1/messages` -| Type | Description | -|------|-------------| -| `{ "type": "auto" }` | Model decides whether to use tools. Supports `disable_parallel_tool_use`. | -| `{ "type": "any" }` | Model will use any available tool. Supports `disable_parallel_tool_use`. | -| `{ "type": "tool", "name": "..." }` | Model will use the specified tool. Supports `disable_parallel_tool_use`. | -| `{ "type": "none" }` | Model will not use tools. | +The Messages API is compatible with the Anthropic message format and is suitable for the Anthropic SDK, Claude Code, and other clients that use the Messages protocol. + +### Main Request Parameters + +| Parameter | Type | Required | Description | +|---|---|---:|---| +| `model` | string | Yes | Model ID. | +| `max_tokens` | integer | Yes | Maximum output tokens. | +| `messages` | array | Yes | User and assistant message list. | +| `system` | string \| array | No | System prompt. | +| `stream` | boolean | No | Whether to return an SSE stream. Default `false`. | +| `temperature` | number | No | Sampling temperature, usually from `0.0` to `1.0`. | +| `top_p` | number | No | Nucleus sampling parameter. | +| `top_k` | integer | No | Sample only from the top K candidates by probability. | +| `stop_sequences` | string[] | No | Custom stop sequences. | +| `thinking` | object | No | Extended thinking configuration. | +| `tools` | array | No | Anthropic-format tool definitions. | +| `tool_choice` | object | No | Tool selection mode. | + +### Request Example + +```bash +curl https://api.b.ai/v1/messages \ + -H "x-api-key: $BAI_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "your-model-id", + "max_tokens": 512, + "messages": [ + {"role": "user", "content": "Hello, Claude!"} + ] + }' +``` -### ChatTool +### Non-Streaming Response Example ```json { - "type": "function", - "function": { - "name": "get_weather", - "description": "Get weather for a location", - "parameters": { - "type": "object", - "properties": { - "location": { "type": "string" } - }, - "required": ["location"] + "id": "msg_xxx", + "type": "message", + "role": "assistant", + "content": [ + { + "type": "text", + "text": "Hello! How can I help you?" } + ], + "stop_reason": "end_turn", + "model": "your-model-id", + "usage": { + "input_tokens": 4, + "output_tokens": 12 } } ``` -### WebSearchOptions +### Streaming Events -| Field | Type | Description | -|-------|------|-------------| -| `search_context_size` | string | `"low"`, `"medium"`, or `"high"` - how much context window for web search results. | -| `user_location` | object | Approximate user location (country ISO 3166-1 alpha-2, city, region, timezone). | +When `stream: true`, common events include: -### ChatResponseFormat +| Event type | Description | +|---|---| +| `message_start` | Initial message metadata. | +| `content_block_start` | A new content block begins. | +| `content_block_delta` | Incremental text or thinking content. | +| `content_block_stop` | The current content block ends. | +| `message_delta` | Incremental stop reason and usage data. | +| `message_stop` | The message is complete. | -| Field | Type | Description | -|-------|------|-------------| -| `type` | string | `"text"` or `"json_object"` | -| `json_schema` | object | When type is `json_schema`, optional schema for the output. | +--- + +## Codex CLI Integration + +The B.AI Responses API can be used as a custom model provider for Codex. The following configuration applies to Codex versions that support custom model providers. + +### 1. Set the API Key + +```bash +export BAI_API_KEY="sk-..." +``` + +### 2. Edit the Codex Configuration + +Edit the user-level configuration file: + +```text +~/.codex/config.toml +``` + +Add the following configuration: + +```toml +model = "your-model-id" +model_provider = "bai" + +[model_providers.bai] +name = "B.AI" +base_url = "https://api.b.ai/v1" +env_key = "BAI_API_KEY" +wire_api = "responses" +requires_openai_auth = false +``` + +If the file already contains configuration, append the complete `[model_providers.bai]` block and change the top-level `model` and `model_provider` values as shown above. See the Codex documentation at the end of this page for a full explanation of the configuration fields. + +After saving, start Codex from a terminal where `BAI_API_KEY` is set: + +```bash +codex +``` + +To change models, edit the top-level `model` value: + +```toml +model = "your-model-id" +``` + +### Codex FAQ + +| Issue | Check | +|---|---| +| Environment variable not found | Make sure `env_key` exactly matches the environment variable name, and start Codex from the terminal where the variable is set. | +| Requests go to OpenAI instead of B.AI | Confirm the top-level `model_provider = "bai"` and that a `[model_providers.bai]` block exists. | +| `401` response | Check whether the API Key is valid and whether a Key from another environment was used accidentally. | +| `403` response | Check the account status and model permissions. | +| Model not supported | Confirm that the model ID is spelled correctly and is enabled for the configured endpoint. | --- -## Error Response +## Choosing an Endpoint -All error responses follow this format: +| Item | Chat Completions | Responses | Messages | +|---|---|---|---| +| Endpoint | `/v1/chat/completions` | `/v1/responses` | `/v1/messages` | +| Compatible protocol | OpenAI Chat Completions | OpenAI Responses | Anthropic Messages | +| Main input field | `messages` | `input` | `messages` | +| Output limit field | `max_tokens` / `max_completion_tokens` | `max_output_tokens` | `max_tokens` | +| Text output location | `choices[].message.content` | `output[].content[].text` | `content[].text` | +| Input tokens | `usage.prompt_tokens` | `usage.input_tokens` | `usage.input_tokens` | +| Output tokens | `usage.completion_tokens` | `usage.output_tokens` | `usage.output_tokens` | +| Reasoning tokens | `completion_tokens_details.reasoning_tokens` | `output_tokens_details.reasoning_tokens` | Depends on the model and response content blocks | +| Streaming format | SSE chunks | SSE events | SSE events | +| Recommended use | Existing OpenAI-compatible applications | New projects, agents, Codex, and tool use | Anthropic SDK and Claude Code | + +Choose the endpoint that matches the client's protocol and request structure. + +--- + +## Error Responses + +Errors from non-streaming requests and errors that occur before an SSE connection is established are returned as JSON: ```json { "error": { - "message": "Error message", + "message": "model \"example-model\" is not supported on /v1/responses", "type": "invalid_request_error", - "param": null, - "code": null + "param": "", + "code": "model_not_supported_on_endpoint" } } ``` | Field | Type | Description | -|-------|------|-------------| -| `message` | string | Error message | -| `type` | string | Error type (e.g. `invalid_request_error`) | -| `param` | string \| null | Related parameter | -| `code` | string \| null | Error code | +|---|---|---| +| `message` | string | Developer-facing error description; some errors include a request ID. | +| `type` | string | Error type; more than one value may be used. | +| `param` | string | Request parameter that caused the error; may be empty. | +| `code` | string | Machine-readable error code. | + +Error responses include an HTTP status code and an `error` object. Applications can use `code` and `message` for error handling and troubleshooting. + +### HTTP Status Codes + +| Status code | Description | Handling | +|---:|---|---| +| `200` | Request succeeded | Parse the response according to the endpoint format. | +| `400` | The request cannot be processed because of its format, parameters, or endpoint compatibility | Read `code` and `message` from the error object. | +| `401` | API Key is missing, invalid, or expired | Check the authentication header and the environment being used. | +| `403` | Model permission, subscription, or account status restriction | Check the account status and model permissions. | +| `404` | The requested resource or model was not found | Check the request path and model ID. | +| `413` | Request body exceeds the platform limit | Shorten the input or reduce the request content. | +| `429` | Rate limit triggered | Retry with exponential backoff and reduce concurrency. | +| `500` | Internal server error | Record the request ID and retry later. | +| `502` | Upstream service error | Retry with exponential backoff. | +| `503` | Service temporarily unavailable | Retry later or choose another model. | + +### Common Responses Errors + +| Scenario | Status code | Handling | +|---|---:|---| +| Model and endpoint are incompatible | `400` | Select a model enabled for the endpoint or use another endpoint. | +| `max_tokens` or `max_completion_tokens` is used | `400` | Use `max_output_tokens` instead. | +| `max_output_tokens` exceeds the model limit | `400` | Adjust the value to the range stated in the error. | +| Request uses an unavailable tool | `400` | Remove the tool or choose a compatible model configuration. | +| Key is invalid or the environment does not match | `401` | Use a Key issued for the production environment to call the production domain. | +| Streaming request fails before the stream is established | `4xx` / `5xx` | Parse the JSON error object instead of treating it as SSE. | + +### Retry Recommendations + +- `400`, `401`, `403`, and `404` require a request or account-status change and should not usually be retried automatically. +- `429`, `500`, `502`, and `503` can be retried with exponential backoff and random jitter. +- Use the request ID in the response when contacting technical support. + +--- + +## Security Recommendations + +An API Key is equivalent to an account credential and can make billable requests directly. + +- Keep the Key on a server or in a protected local environment. Inject it through environment variables or a secret manager; do not put it in browser frontends, mobile app packages, or public code repositories. +- Use different Keys for development, testing, and production. +- Revoke a leaked Key immediately. Keep only masked forms in logs and support tickets, such as `sk-****abcd`. + +--- + +## Related Resources + +- B.AI documentation: +- B.AI website: +- OpenAI API documentation: +- Codex documentation: diff --git a/docs/llmservice/models/glm-5-3-flash.md b/docs/llmservice/models/glm-5-3-flash.md new file mode 100644 index 00000000..40db3b8b --- /dev/null +++ b/docs/llmservice/models/glm-5-3-flash.md @@ -0,0 +1,64 @@ +import ActivityCard from '@site/src/components/ActivityCard'; + +# GLM-5.3-Flash + +## Overview + +GLM-5.3-Flash is an open-weight, natively multimodal model released by Z.AI on August 26, 2026 as the Flash-tier member of the GLM-5 family. It combines 320 billion total parameters with 18 billion activated parameters, a 1M-token context window, and a hybrid sparse-and-linear-attention architecture for coding, agentic, and visual knowledge-work workloads. + + +This offer covers B.AI API and Chat: + +* **API:** GLM-5.3-Flash API usage is currently billed at `0 Credits`. No input, cache write, cache read, or output token fees apply. +* **Chat:** Free access begins when GLM-5.3-Flash becomes available in B.AI Chat. The availability time is subject to the actual model listing. Once available, Chat usage is billed at `0 Credits`. + +After the offer ends, GLM-5.3-Flash will return to the prices shown on this page. + + +## Key Features + +* **Efficient Hybrid Architecture**: Uses sparse attention, linear attention, Manifold-Constrained Hyper-Connections (mHC), and IndexPool. Z.AI reports 3.0x lower attention compute and 4.4x smaller KV-cache size than GLM-5.3 in its architecture comparison. +* **Native Multimodal Understanding**: Accepts text, images, videos, and files, allowing agents to inspect interfaces, rendered outputs, documents, and other visual evidence during a task. +* **Coding and Agent Evaluation**: Z.AI reports 84.3 on Terminal-Bench 2.1, 63.4 on DeepSWE v1.1, 78.4 on Toolathlon Verified, and 48.8 on AutomationBench v1.0.6. +* **Configurable Always-On Reasoning**: Supports `low`, `high`, and `max` reasoning effort, with `max` as the default. Thinking cannot be disabled. + +## Best Use Cases + +* **Visual Software Engineering**: Building and refining frontends, games, 3D scenes, and other interfaces by combining code changes with screenshot or rendered-output inspection. +* **Long-Horizon Coding Agents**: Repository-scale implementation, debugging, testing, and multi-step automation that require reasoning, function calls, and large working contexts. +* **Multimodal Professional Workflows**: Extracting and reasoning over documents, charts, dashboards, presentations, spreadsheets, and video before producing structured text or office deliverables through an agent environment. +* **Cost-Sensitive API Workloads**: High-volume text and multimodal tasks that benefit from low per-token pricing, cached-input discounts, and a 1M-token context window. + +## Capabilities and Limitations + +| Capability | Description | +| :--- | :--- | +| **Reasoning** | Thinking is always enabled. `reasoning_effort` supports `low`, `high`, and `max`; the default is `max`. | +| **Creative Writing** | Supports general and long-form text generation. | +| **Coding** | Z.AI reports Terminal-Bench 2.1: 84.3, DeepSWE v1.1: 63.4, NL2Repo: 56.3, Toolathlon Verified: 78.4, and AutomationBench v1.0.6: 48.8. | +| **Multimodal** | Accepts text, image, video, and file input and produces text output. | +| **Context Window** | 1,000,000 tokens. | +| **Max Output** | 131,072 tokens; the default `max_tokens` value is 65,536. | +| **Tool Use** | Supports function calling, streamed tool calls, context caching, and JSON structured output. ZCode can pair the model with Browser Use and Computer Use for visually grounded agent workflows. | +| **Multilingual** | The official model repository identifies English and Chinese support. | + +### Known Limitations + +* `thinking.type` only supports `enabled`; applications that require lighter reasoning should use `reasoning_effort: "low"` rather than disabling thinking. + +## Credits Usage + +| Model | Input (Credits/Token) | Cache Write (Credits/Token) | Cache Read (Credits/Token) | Output (Credits/Token) | Web Search (Credits/Use) | +| :--- | --------------------: | --------------------------: | -------------------------: | ---------------------: | -----------------------: | +| **GLM-5.3-Flash** | `0.075` | `0.075` | `0.015` | `0.25` | `-` | + +**Limited-time pricing:** The 50% token-price promotion ends at 24:00 on September 9, 2026 (UTC+8, Singapore time). + +:::info Pricing note +Prices shown in the documentation are B.AI standard reference prices for base billing purposes. B.AI may provide lower actual usage costs through limited-time offers, top-up bonuses, and account benefits. Specific prices, bonus Credits, account benefits, and final billing are subject to the platform display and billing records. +::: diff --git a/docs/llmservice/models/qwen3-8-flash.md b/docs/llmservice/models/qwen3-8-flash.md new file mode 100644 index 00000000..c248f0e0 --- /dev/null +++ b/docs/llmservice/models/qwen3-8-flash.md @@ -0,0 +1,70 @@ +import ActivityCard from '@site/src/components/ActivityCard'; + +# Qwen3.8-Flash + +## Overview + +Qwen3.8-Flash is a hosted multimodal model from Alibaba's Qwen team, announced on August 26, 2026. It is the production version based on Qwen3.8-Flash-Next, adding a default 1M-token context window and hosted tools for cost-sensitive coding, agentic, and visual knowledge-work applications. + + +Free access is available in phases across B.AI API and Chat: + +* **API:** Qwen3.8-Flash API usage is currently billed at `0 Credits`. No input, cache write, cache read, or output token fees apply. +* **Chat:** Free access begins when Qwen3.8-Flash becomes available in B.AI Chat. The availability date is subject to the actual model listing. Once available, Chat usage is billed at `0 Credits`. + +After the offer ends, Qwen3.8-Flash will return to the prices shown on this page. + + +## Key Features + +* **Production Flash-Next Lineage:** Qwen identifies `qwen3.8-flash` as the production version based on Qwen3.8-Flash-Next. The related open-weight architecture uses Gated DeltaNet, Qwen Sparse Attention, Gated Residual, and N-gram Embedding; QwenCloud does not separately publish the production model's parameter count. +* **Native Multimodal Input:** Accepts text, images, and video and produces text output, supporting visual coding, document analysis, charts, and long-video understanding. +* **1M-Token Hosted Context:** Supports up to 991K input tokens without thinking, 983K input tokens with thinking, and 131K output tokens in either mode. +* **Thinking and Agent Controls:** QwenCloud documents thinking as enabled by default for the Qwen3.8 series, exposes the `enable_thinking` control, and lists a maximum reasoning budget of 262K tokens. +* **Agent-Oriented API Features:** Supports prefix completion, function calling, context caching, structured output, Batch API processing, fine-tuning, and built-in tools through QwenCloud's Responses API. +* **Published Flash-Next Evaluation:** The related open-weight foundation reports 62.5 on SWE-bench Pro, 58.7 on DeepSWE 1.1, 73.9 on CoWorkBench, and 73.5 on Toolathlon Verified. Qwen has not published a separate benchmark table for the hosted production endpoint. + +## Best Use Cases + +* **Cost-Sensitive Coding Agents:** Repository analysis, code generation, debugging, and tool-driven development where low token prices and high account-level rate limits matter. +* **Long-Context Knowledge Work:** Reviewing large document sets, codebases, conversation histories, and research materials within a 1M-token hosted context. +* **Multimodal Analysis:** Understanding screenshots, charts, scanned documents, interfaces, and video together with text instructions. +* **Structured Agent Workflows:** Applications that combine function calling, JSON structured output, code execution, search, extraction, and cached shared prompts. +* **Asynchronous Bulk Processing:** Classification, extraction, evaluation, and dataset processing through the Batch API at half the real-time input and output rates. + +## Capabilities and Limitations + +| Capability | Description | +| :--- | :--- | +| **Reasoning** | Thinking is enabled by default for the Qwen3.8 series and can be controlled with `enable_thinking`. QwenCloud lists a 262K-token maximum reasoning budget but does not publish a model-specific reasoning-effort mapping on the model page. | +| **Creative Writing** | Supports general, long-form, and structured text generation. | +| **Coding** | The related Qwen3.8-Flash-Next evaluation reports SWE-bench Pro: 62.5, DeepSWE 1.1: 58.7, SWE-bench Multilingual: 81.0, and NL2Repo-Bench: 48.1. These are not hosted-endpoint SLA results. | +| **Multimodal** | Accepts text, image, and video input and produces text output. | +| **Context Window** | 1M tokens. | +| **Maximum Input** | 991K tokens in non-thinking mode and 983K tokens in thinking mode. | +| **Max Output** | 131K tokens in both thinking and non-thinking modes. | +| **Tool Use** | Supports function calling, structured output, prefix completion, caching, and Batch API processing. Responses API tools include `code_interpreter`, `i2i_search`, `t2i_search`, `web_extractor`, and `web_search`. | +| **Multilingual** | The related Flash-Next evaluation includes multilingual reasoning and coding benchmarks. | + +### Known Limitations + +* `qwen3.8-flash` is the hosted production model, while `Qwen/Qwen3.8-Flash-Next` is the related open-weight architecture release. Parameter counts, self-hosting behavior, and Flash-Next benchmark results should not be treated as hosted-endpoint guarantees. +* QwenCloud does not publish a model-specific knowledge cutoff or complete supported-language list. +* Thinking tokens are billed at the output-token rate and consume context. Applications should enable thinking according to task needs rather than assuming that a larger reasoning budget is always more efficient. + +## Pricing + +| Model | Input (Credits/Token) | Cache Write (Credits/Token) | Cache Read (Credits/Token) | Output (Credits/Token) | Web Search (Credits/Use) | +| :--- | --------------------: | --------------------------: | -------------------------: | ---------------------: | -----------------------: | +| **Qwen3.8-Flash** | `0.16` | `0.16` | `0.016` | `0.47` | `-` | + +Explicit cache creation costs `0.20 Credits/Token`. Both explicit and implicit cache hits cost `0.016 Credits/Token`. + +:::info Pricing note +Prices shown in the documentation are B.AI standard reference prices for base billing purposes. B.AI may provide lower actual usage costs through limited-time offers, top-up bonuses, and account benefits. Specific prices, bonus Credits, account benefits, and final billing are subject to the platform display and billing records. +::: diff --git a/docs/llmservice/pricing-and-usage.md b/docs/llmservice/pricing-and-usage.md index 51377e4f..620754d6 100644 --- a/docs/llmservice/pricing-and-usage.md +++ b/docs/llmservice/pricing-and-usage.md @@ -29,6 +29,7 @@ The table below lists standard reference prices only. For current limited-time o | Kimi K3 | 3.00 | 3.00 | 0.30 | 15.00 | - | | Kimi K2.6 | 0.95 | 0.95 | 0.1615 | 4.00 | - | | Kimi K2.5 | 0.59 | 0.59 | 0.10 | 3.00 | - | +| Qwen3.8-Flash | 0.16 | 0.16 | 0.016 | 0.47 | - | | Qwen3.8-27B | 0.22 | 0.22 | 0.022 | 1.60 | - | | Qwen3.8-Max | 2.00 | 2.00 | 0.25 | 6.00 | - | | Qwen3.7-Max | 1.65 | 1.65 | 0.33 | 4.951 | - | @@ -36,6 +37,7 @@ The table below lists standard reference prices only. For current limited-time o | Hy3 | 0.132 | 0.132 | 0.033 | 0.528 | - | | MiMo-V2.5-Pro | 0.435 | 0.435 | 0.0036 | 0.87 | - | | MiMo-V2.5 | 0.14 | 0.14 | 0.0028 | 0.28 | - | +| GLM-5.3-Flash | 0.075 | 0.075 | 0.015 | 0.25 | - | | GLM-5.3 | 1.40 | 1.40 | 0.28 | 4.40 | - | | GLM-5.2 | 1.40 | 1.40 | 0.28 | 4.40 | - | | GLM-5.1 | 1.40 | 1.40 | 0.28 | 4.40 | - | diff --git a/docs/llmservice/promotions-and-pricing-notices.md b/docs/llmservice/promotions-and-pricing-notices.md index e7906f62..9793f976 100644 --- a/docs/llmservice/promotions-and-pricing-notices.md +++ b/docs/llmservice/promotions-and-pricing-notices.md @@ -69,6 +69,34 @@ MiMo-V2.5 free access is available in phases: After the offer ends, MiMo-V2.5 will return to standard pricing. See the [model details](./models/mimo-v2.5.md). + +This offer covers B.AI API and Chat: + +* **API:** GLM-5.3-Flash API usage is currently billed at `0 Credits`. No input, cache write, cache read, or output token fees apply. +* **Chat:** Free access begins when GLM-5.3-Flash becomes available in B.AI Chat. The availability time is subject to the actual model listing. Once available, Chat usage is billed at `0 Credits`. + +After the offer ends, GLM-5.3-Flash will return to the prices shown in the [model details](./models/glm-5-3-flash.md). + + + +Free access is available in phases across B.AI API and Chat: + +* **API:** Qwen3.8-Flash API usage is currently billed at `0 Credits`. No input, cache write, cache read, or output token fees apply. +* **Chat:** Free access begins when Qwen3.8-Flash becomes available in B.AI Chat. The availability date is subject to the actual model listing. Once available, Chat usage is billed at `0 Credits`. + +After the offer ends, Qwen3.8-Flash will return to the prices shown in the [model details](./models/qwen3-8-flash.md). + + ` -- **示例：** `Bearer sk-xxx` +```http +Authorization: Bearer +``` + +示例： + +```bash +-H "Authorization: Bearer $BAI_API_KEY" +``` + +### x-api-key -### API Key（仅 Messages 端点支持） +```http +x-api-key: +``` + +示例： + +```bash +-H "x-api-key: $BAI_API_KEY" +``` -- **类型：** API Key -- **请求头：** `x-api-key: ` +> 两种请求头等价。Codex、OpenAI SDK 及多数 OpenAI 兼容客户端使用 `Authorization`。 --- -## 端点 +## 端点概览 + +| 方法 | 端点 | 协议 | 用途 | +|---|---|---|---| +| `GET` | `/models` | OpenAI 兼容 | 获取与当前凭证关联的模型列表 | +| `POST` | `/responses` | OpenAI Responses | Agent、推理、工具调用及 Codex 等场景 | +| `POST` | `/chat/completions` | OpenAI Chat Completions | 通用聊天补全及现有 OpenAI 兼容应用 | +| `POST` | `/messages` | Anthropic Messages | Claude SDK、Claude Code 等 Anthropic 兼容应用 | + +--- -### 1. 获取模型列表 +## 获取模型列表 `GET /v1/models` -获取可用模型列表。认证方式：Bearer Token。 +返回与当前 API 凭证关联的模型列表。 -**认证：** Bearer Token +### 请求示例 -**200 响应：** +```bash +curl https://api.b.ai/v1/models \ + -H "Authorization: Bearer $BAI_API_KEY" +``` + +### 响应示例 ```json { @@ -41,385 +108,713 @@ "success": true, "data": [ { - "id": "gpt-5.2", + "id": "your-model-id", "object": "model", - "created": 1626777600, - "owned_by": "openai", - "supported_endpoint_types": ["openai", "anthropic"] + "created": 1626777600 } ] } ``` -| 状态码 | 描述 | -|--------|------| -| 200 | 成功 - 返回模型列表 | -| 400 | 错误请求 - 参数无效或请求体格式错误 | -| 401 | 未授权 - 认证无效或缺失 | -| 403 | 禁止访问 - 无权限、额度不足或账号被封禁 | -| 429 | 请求过多 - 超出速率限制 | -| 500 | 服务器内部错误 | - --- -### 2. 聊天补全（OpenAI 兼容） +## Responses API（OpenAI 兼容） -`POST /v1/chat/completions` +`POST /v1/responses` + +Responses API 用于提交模型输入并获取生成结果。根据所选模型和配置，请求可使用流式输出、推理、函数调用和网页搜索等能力，也可用于 Codex 等采用 Responses 协议的客户端。 + +- **完整地址：** `https://api.b.ai/v1/responses` +- **认证方式：** Bearer Token 或 `x-api-key` +- **非流式响应：** JSON +- **流式响应：** SSE + +Responses API 与 Chat Completions 的请求结构不同： -接收一组消息并返回模型生成的回复。支持单轮和多轮对话。响应既可以是单个 JSON 对象，也可以通过流式（SSE）返回。 +- 使用 `input`，而不是 `messages`； +- 使用 `max_output_tokens`，而不是 `max_tokens`； +- 使用 `output` 数组返回消息、推理和工具调用等输出 item； +- 流式模式返回具名 Responses 事件，而不是 Chat Completion chunk。 -**认证：** Bearer Token +### 模型与端点兼容性 -#### 请求体 +Responses 端点接受已启用该协议的模型。模型与端点不兼容时，服务器返回 HTTP `400` 及对应错误信息。 + +### 请求体 | 参数 | 类型 | 必填 | 描述 | -|------|------|------|------| -| `model` | string | **是** | 要使用的模型 ID（例如 `gpt-5.2`）。 | -| `messages` | array | **是** | 对话中的消息列表。参见 [ChatMessage](#chatmessage)。 | -| `stream` | boolean | 否 | 若为 true，将通过 Server-Sent Events 返回部分消息增量。默认值为 `false`。 | -| `max_tokens` | integer | 否 | 本次补全最多可生成的 token 数。 | -| `temperature` | number | 否 | 采样温度，范围 0 到 2。值越高，结果越随机。默认 `1`。 | -| `top_p` | number | 否 | Nucleus Sampling，仅考虑累计概率达到 top_p 的 token。默认 `1`。 | -| `stop` | string \| string[] | 否 | 最多 4 个停止序列，命中后 API 将停止生成。 | -| `n` | integer | 否 | 生成多少个补全选项。默认 `1`。 | -| `frequency_penalty` | number | 否 | 范围 -2.0 到 2.0。用于惩罚重复 token。默认 `0`。 | -| `presence_penalty` | number | 否 | 范围 -2.0 到 2.0。用于惩罚已在文本中出现过的 token。默认 `0`。 | -| `seed` | integer | 否 | 随机种子，用于确定性采样（如果模型支持）。 | -| `response_format` | object | 否 | 指定输出格式：`{ "type": "text" }`、`{ "type": "json_object" }` 或 `json_schema`。 | -| `tools` | array | 否 | 模型可调用的工具列表。参见 [ChatTool](#chattool)。 | -| `tool_choice` | string \| object | 否 | 可选值：`"auto"`、`"none"`、`"required"`，或 `{ "type": "function", "function": { "name": "..." } }`。 | -| `user` | string | 否 | 可选的终端用户标识，用于滥用监控。 | -| `web_search_options` | object | 否 | 为支持的模型开启网页搜索。参见 [WebSearchOptions](#websearchoptions)。 | - -#### 请求示例 +|---|---|---:|---| +| `model` | string | 是 | 要使用的模型 ID。 | +| `input` | string \| array | 是 | 输入内容，可以是字符串或 Responses input item 数组。 | +| `instructions` | string | 否 | 系统级或开发者级指令。 | +| `stream` | boolean | 否 | 是否使用 SSE 流式返回，默认 `false`。 | +| `max_output_tokens` | integer | 否 | 最大输出 token 数，包含可见输出 token 和推理 token。取值范围取决于所选模型；超出范围时返回 `400`，错误信息会说明允许的范围。 | +| `reasoning` | object | 否 | 推理配置，例如 `effort` 和 `summary`；可用值取决于模型。 | +| `tools` | array | 否 | 模型可调用的工具列表，例如函数或网页搜索。 | +| `tool_choice` | string \| object | 否 | 控制模型是否以及如何选择工具。 | +| `parallel_tool_calls` | boolean | 否 | 是否允许并行工具调用。 | +| `text` | object | 否 | 文本输出配置，包括结构化输出格式；能力取决于模型。 | +| `temperature` | number | 否 | 采样温度；部分推理模型不支持。 | +| `top_p` | number | 否 | Nucleus Sampling 参数；部分推理模型不支持。 | + +#### 不支持的参数 + +| 参数 | API 行为 | +|---|---| +| `max_tokens` | 返回 `400`；请改用 `max_output_tokens`。 | +| `max_completion_tokens` | 返回 `400`；请改用 `max_output_tokens`。 | + +### 简单文本输入 ```json { - "model": "gpt-5.2", - "messages": [ - { "role": "system", "content": "You are a helpful assistant." }, - { "role": "user", "content": "Hello" } - ], - "stream": false, - "max_tokens": 1024, - "temperature": 1 + "model": "your-model-id", + "input": "总结量子计算的三个核心概念。" } ``` -#### 响应（非流式） +### 带指令的输入 ```json { - "id": "chatcmpl-xxx", - "object": "chat.completion", - "created": 1677652288, - "model": "gpt-5.2", - "choices": [ + "model": "your-model-id", + "instructions": "你是一名专业、简洁的技术写作助手。", + "input": [ { - "index": 0, - "message": { - "role": "assistant", - "content": "Hello! How can I help you?", - "refusal": null, - "annotations": [] - }, - "finish_reason": "stop" + "role": "user", + "content": "用初学者能理解的方式解释向量数据库。" + } + ] +} +``` + +输入 item 可使用 `system`、`developer`、`user` 或 `assistant` 等角色。具体内容块能力取决于所选模型。 + +### 非流式调用 + +当 `stream` 为 `false` 或未提供时，API 在模型生成结束后一次性返回完整 JSON。 + +#### cURL + +```bash +curl https://api.b.ai/v1/responses \ + -H "Authorization: Bearer $BAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "your-model-id", + "input": "请用三句话解释什么是 Responses API。", + "max_output_tokens": 512 + }' +``` + +#### 响应示例 + +```json +{ + "id": "resp_01HXYZ...", + "object": "response", + "created_at": 1787587200, + "status": "completed", + "model": "your-model-id", + "output": [ + { + "id": "msg_01HXYZ...", + "type": "message", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "Responses API 是一个统一的模型响应接口……", + "annotations": [] + } + ] } ], "usage": { - "prompt_tokens": 12, - "completion_tokens": 8, - "total_tokens": 20, - "prompt_tokens_details": { "cached_tokens": 0, "audio_tokens": 0 }, - "completion_tokens_details": { - "reasoning_tokens": 0, - "audio_tokens": 0, - "accepted_prediction_tokens": 0, - "rejected_prediction_tokens": 0 - } + "input_tokens": 18, + "output_tokens": 42, + "output_tokens_details": { + "reasoning_tokens": 12 + }, + "total_tokens": 60 } } ``` -#### 响应（流式） +`output` 可能同时包含 reasoning、message、function call 或 web search call 等多种 item。`output[0]` 不保证是助手文本。 -每个 SSE 分块的 `object` 都是 `"chat.completion.chunk"`，其中 `choices[].delta.content` 包含增量文本。最后一个分块会包含 `usage` 和 `finish_reason`。 +OpenAI SDK 的 `response.output_text` 是 `output` 中 `type` 为 `message` 的 item 下所有 `output_text` 内容块的聚合结果。 -| 状态码 | 描述 | -|--------|------| -| 200 | 成功 | -| 400 | 错误请求 - 参数无效、请求体格式错误或请求非法 | -| 401 | 未授权 - 认证无效或缺失 | -| 403 | 禁止访问 - 无权限、额度不足或模型访问受限 | -| 429 | 请求过多 - 超出速率限制 | -| 500 | 服务器内部错误 | -| 502 | 网关错误 - 上游服务错误 | -| 503 | 服务不可用 - 服务过载或无可用通道 | +### 流式调用 ---- +设置 `stream: true` 后，API 使用 SSE 在模型生成过程中持续返回事件。 -### 3. Messages（Claude 兼容） +```bash +curl -N https://api.b.ai/v1/responses \ + -H "Authorization: Bearer $BAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "your-model-id", + "input": "写一段关于人工智能发展的简短介绍。", + "stream": true, + "max_output_tokens": 512 + }' +``` -`POST /v1/messages` +常见事件： -接收一组消息并返回模型生成的回复。支持单轮和多轮对话。可通过 `x-api-key` 请求头或 Bearer Token 进行认证。响应既可以是单个 JSON 对象，也可以通过流式（SSE）返回。 +| 事件类型 | 描述 | +|---|---| +| `response.created` | Response 已创建。 | +| `response.in_progress` | Response 正在生成。 | +| `response.output_item.added` | 新的输出 item 已加入。 | +| `response.content_part.added` | 新的内容块已加入。 | +| `response.output_text.delta` | 文本增量。 | +| `response.output_text.done` | 文本输出完成。 | +| `response.output_item.done` | 当前输出 item 完成。 | +| `response.completed` | Response 成功完成。 | +| `response.incomplete` | Response 因输出上限等原因提前结束。 | +| `response.failed` | Response 生成失败。 | -**认证：** API Key（`x-api-key`）或 Bearer Token +上表列出常见事件。客户端应按事件类型处理已识别事件，并忽略不需要的其他事件。 -#### 请求体 +事件示例： -| 参数 | 类型 | 必填 | 描述 | -|------|------|------|------| -| `model` | string | **是** | 模型 ID（例如 `claude-sonnet-4-6`、`claude-opus-4-6`、`claude-haiku-4-5`）。 | -| `max_tokens` | integer | **是** | 最多生成的 token 数。不同模型的最大值不同。 | -| `messages` | array | **是** | 输入消息。用户与助手轮流出现。上限：100,000 条消息。参见 [MessagesMessageItem](#messagesmessageitem)。 | -| `system` | string \| array | 否 | 系统提示词。可以是纯字符串，也可以是文本块数组（用于 `cache_control`）。 | -| `stream` | boolean | 否 | 是否使用 SSE 流式返回。默认 `false`。 | -| `temperature` | number | 否 | 随机性（0.0 - 1.0）。分析型任务建议接近 0.0，创意型任务建议接近 1.0。默认 `1`。 | -| `top_p` | number | 否 | Nucleus Sampling。默认 `1`。 | -| `top_k` | integer | 否 | 仅从概率最高的前 K 个选项中采样。默认关闭。 | -| `stop_sequences` | string[] | 否 | 自定义停止文本序列，命中后停止生成。 | -| `metadata` | object | 否 | 请求元数据。支持 `user_id`（不透明标识符）。 | -| `thinking` | object | 否 | 扩展思考配置。参见 [ThinkingConfig](#thinkingconfig)。 | -| `tools` | array | 否 | 模型可调用的工具定义。参见 [Tool](#tool-anthropic)。 | -| `tool_choice` | object | 否 | 模型如何使用工具：`auto`、`any`、`tool` 或 `none`。 | - -#### 请求示例 +```text +event: response.output_text.delta +data: {"type":"response.output_text.delta","delta":"Responses"} -```json -{ - "model": "claude-sonnet-4-6", - "max_tokens": 1024, - "messages": [ - { "role": "user", "content": "Hello, Claude!" } - ], - "system": "You are a helpful assistant.", - "temperature": 1.0 -} +event: response.output_text.delta +data: {"type":"response.output_text.delta","delta":" API"} + +event: response.completed +data: {"type":"response.completed","response":{"id":"resp_...","status":"completed"}} ``` -#### 响应（非流式） +> 流式请求在 SSE 连接建立前失败时，服务器返回 JSON 错误对象，`Content-Type` 为 `application/json`。 -```json -{ - "id": "chatcmpl-xxx", - "type": "message", - "role": "assistant", - "content": [ - { "type": "text", "text": "Hello! How can I help you?" } - ], - "stop_reason": "end_turn", - "model": "gpt-5", - "usage": { - "input_tokens": 4, - "cache_creation_input_tokens": 0, - "cache_read_input_tokens": 0, - "output_tokens": 12, - "claude_cache_creation_5_m_tokens": 0, - "claude_cache_creation_1_h_tokens": 0 - } -} +### Python SDK + +安装 OpenAI Python SDK： + +```bash +pip install openai ``` -#### 响应（流式 - SSE 事件） +调用 Responses API： -流式响应会发出以下事件类型： +```python +import os +from openai import OpenAI -| 事件类型 | 描述 | 关键字段 | -|----------|------|----------| -| `message_start` | 初始消息元数据 | `message`（id、model、role、usage） | -| `content_block_start` | 开始新的内容块 | `index`、`content_block`（type、text） | -| `content_block_delta` | 增量内容 | `index`、`delta`（type: `text_delta`、text） | -| `content_block_stop` | 内容块结束 | `index` | -| `message_stop` | 消息完成 | - | +client = OpenAI( + api_key=os.environ["BAI_API_KEY"], + base_url="https://api.b.ai/v1", +) -| 状态码 | 描述 | -|--------|------| -| 200 | 成功 | -| 400 | 错误请求 - 参数无效、请求体格式错误或请求非法 | -| 401 | 未授权 - API Key 无效或缺失 | -| 403 | 禁止访问 - 无权限、额度不足或模型访问受限 | -| 429 | 请求过多 - 超出速率限制 | -| 500 | 服务器内部错误 | -| 502 | 网关错误 - 上游服务错误 | -| 503 | 服务不可用 - 服务过载或无可用通道 | +response = client.responses.create( + model="your-model-id", + input="请用三句话解释什么是 Responses API。", +) ---- +print(response.output_text) +``` -## 数据模型 +### JavaScript SDK -### ChatMessage +安装 OpenAI JavaScript SDK： -| 字段 | 类型 | 必填 | 描述 | -|------|------|------|------| -| `role` | string | **是** | `"system"`、`"user"`、`"assistant"` 或 `"tool"` | -| `content` | string | **是** | 消息内容。对于 `tool` 角色，这里是工具调用结果。 | -| `name` | string | 否 | 消息作者的可选名称。 | -| `tool_call_id` | string | 否 | 当 `role` 为 `"tool"` 时，对应的工具调用 ID。 | -| `tool_calls` | array | 否 | 当 `role` 为 `"assistant"` 且模型调用了工具时使用。格式为 `{ id, type, function: { name, arguments } }` 的数组。 | +```bash +npm install openai +``` -### MessagesMessageItem +调用 Responses API： -| 字段 | 类型 | 必填 | 描述 | -|------|------|------|------| -| `role` | string | **是** | `"user"` 或 `"assistant"`（不支持 `"system"`，请使用顶层 `system` 参数）。 | -| `content` | string \| array | **是** | 文本字符串，或内容块数组（text、image、tool_use、tool_result）。 | +```javascript +import OpenAI from "openai"; -### 内容块类型（Messages API） +const client = new OpenAI({ + apiKey: process.env.BAI_API_KEY, + baseURL: "https://api.b.ai/v1", +}); -#### TextBlockParam +const response = await client.responses.create({ + model: "your-model-id", + input: "请用三句话解释什么是 Responses API。", +}); -```json -{ "type": "text", "text": "Hello, Claude!", "cache_control": { "type": "ephemeral" } } +console.log(response.output_text); ``` -#### ImageBlockParam +### 推理配置 -Base64 来源： +支持推理的模型可以通过 `reasoning` 配置推理强度和摘要： ```json { - "type": "image", - "source": { - "type": "base64", - "media_type": "image/jpeg", - "data": "/9j/4AAQSkZJRg..." + "model": "your-model-id", + "input": "分析这个系统设计中的性能瓶颈。", + "reasoning": { + "effort": "high", + "summary": "auto" } } ``` -URL 来源： +可用的推理档位取决于所选模型。不支持的配置可能返回 HTTP `400`。 + +推理 token 使用量位于： + +```text +usage.output_tokens_details.reasoning_tokens +``` + +推理 token 计入 `max_output_tokens`。如果该值设置过低，模型可能在产生可见文本之前就耗尽预算，返回 `status` 为 `incomplete` 的响应。 + +### 函数调用 + +#### 第一步：声明函数 ```json { - "type": "image", - "source": { - "type": "url", - "url": "https://example.com/image.jpg" - } + "model": "your-model-id", + "max_output_tokens": 512, + "input": [ + { + "role": "user", + "content": "深圳今天的天气怎么样？" + } + ], + "tools": [ + { + "type": "function", + "name": "get_weather", + "description": "查询指定城市的天气", + "parameters": { + "type": "object", + "properties": { + "city": { + "type": "string", + "description": "城市名称" + } + }, + "required": ["city"], + "additionalProperties": false + }, + "strict": true + } + ], + "tool_choice": "auto" } ``` -支持的媒体类型：`image/jpeg`、`image/png`、`image/gif`、`image/webp` - -#### ToolUseBlockParam（来自 assistant） +当模型决定调用函数时，`output` 中会出现 `function_call` item： ```json { - "type": "tool_use", - "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", - "name": "get_stock_price", - "input": { "ticker": "AAPL" } + "type": "function_call", + "call_id": "call_01HXYZ...", + "name": "get_weather", + "arguments": "{\"city\":\"深圳\"}" } ``` -#### ToolResultBlockParam（来自 user） +#### 第二步：提交函数执行结果 + +新请求的 `input` 中依次放入原有对话、模型返回的 `function_call`，以及执行结果 `function_call_output`： ```json { - "type": "tool_result", - "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", - "content": "259.75 USD", - "is_error": false + "model": "your-model-id", + "max_output_tokens": 512, + "tools": [ + { + "type": "function", + "name": "get_weather", + "description": "查询指定城市的天气", + "parameters": { + "type": "object", + "properties": { + "city": { + "type": "string", + "description": "城市名称" + } + }, + "required": ["city"], + "additionalProperties": false + }, + "strict": true + } + ], + "input": [ + { + "role": "user", + "content": "深圳今天的天气怎么样？" + }, + { + "type": "function_call", + "call_id": "call_01HXYZ...", + "name": "get_weather", + "arguments": "{\"city\":\"深圳\"}" + }, + { + "type": "function_call_output", + "call_id": "call_01HXYZ...", + "output": "深圳：晴，28°C" + } + ] } ``` -### ThinkingConfig +`call_id` 必须与模型返回的值一致。工具定义需要在后续请求中一并带上。 -启用扩展思考，让 Claude 展示其推理过程。 +### 网页搜索 -**启用：** +支持网页搜索的模型可以使用 `web_search` 工具： ```json -{ "type": "enabled", "budget_tokens": 1024 } +{ + "model": "your-model-id", + "input": "总结今天值得关注的三条人工智能新闻。", + "tools": [ + { + "type": "web_search" + } + ] +} ``` -- `budget_tokens`：必须大于等于 1024，并且小于 `max_tokens`。 +网页搜索能力和费用取决于所选模型及请求配置。 + +### 多轮对话 -**禁用：** +以下示例按无状态请求方式组织多轮对话。后续请求可在 `input` 中携带生成下一次响应所需的上下文： ```json -{ "type": "disabled" } +{ + "model": "your-model-id", + "input": [ + { + "role": "user", + "content": "什么是向量数据库？" + }, + { + "role": "assistant", + "content": "向量数据库是专门用于存储和检索向量表示的数据库。" + }, + { + "role": "user", + "content": "它最常见的三个应用是什么？" + } + ] +} ``` -### Tool（Anthropic） +后续请求只需携带生成下一次响应所需的上下文。 + +--- + +## Chat Completions API（OpenAI 兼容） + +`POST /v1/chat/completions` + +接收消息列表并返回模型生成的回复，适合已经使用 OpenAI Chat Completions 协议的应用。 + +### 主要请求参数 + +| 参数 | 类型 | 必填 | 描述 | +|---|---|---:|---| +| `model` | string | 是 | 模型 ID。 | +| `messages` | array | 是 | 对话消息列表。 | +| `stream` | boolean | 否 | 是否使用 SSE 流式返回，默认 `false`。 | +| `max_tokens` | integer | 否 | 最大输出 token 数。部分模型也支持 `max_completion_tokens`。 | +| `temperature` | number | 否 | 采样温度，支持范围取决于模型。 | +| `top_p` | number | 否 | Nucleus Sampling 参数。 | +| `stop` | string \| string[] | 否 | 停止序列。 | +| `response_format` | object | 否 | 文本、JSON Object 或 JSON Schema 输出配置。 | +| `tools` | array | 否 | 函数工具定义。 | +| `tool_choice` | string \| object | 否 | 工具选择方式。 | +| `web_search_options` | object | 否 | 为支持的模型配置网页搜索。 | +| `user` | string | 否 | 终端用户标识。 | + +### 请求示例 + +```bash +curl https://api.b.ai/v1/chat/completions \ + -H "Authorization: Bearer $BAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "your-model-id", + "messages": [ + {"role": "system", "content": "You are a helpful assistant."}, + {"role": "user", "content": "Hello"} + ], + "stream": false, + "max_tokens": 512 + }' +``` + +### 非流式响应示例 ```json { - "name": "get_stock_price", - "description": "Get the current stock price for a given ticker symbol.", - "input_schema": { - "type": "object", - "properties": { - "ticker": { "type": "string" } - }, - "required": ["ticker"] + "id": "chatcmpl-xxx", + "object": "chat.completion", + "created": 1787587200, + "model": "your-model-id", + "choices": [ + { + "index": 0, + "message": { + "role": "assistant", + "content": "Hello! How can I help you?" + }, + "finish_reason": "stop" + } + ], + "usage": { + "prompt_tokens": 12, + "completion_tokens": 8, + "total_tokens": 20 } } ``` -### ToolChoice（Anthropic） +### 流式响应 -| 类型 | 描述 | -|------|------| -| `{ "type": "auto" }` | 模型自行决定是否使用工具。支持 `disable_parallel_tool_use`。 | -| `{ "type": "any" }` | 模型将使用任意可用工具。支持 `disable_parallel_tool_use`。 | -| `{ "type": "tool", "name": "..." }` | 模型将使用指定工具。支持 `disable_parallel_tool_use`。 | -| `{ "type": "none" }` | 模型不会使用工具。 | +设置 `stream: true` 时，服务器返回 `text/event-stream`。每个分块的 `object` 为 `chat.completion.chunk`，增量文本位于： -### ChatTool +```text +choices[].delta.content +``` + +--- + +## Messages API（Anthropic 兼容） + +`POST /v1/messages` + +Messages API 兼容 Anthropic 消息格式，适合 Anthropic SDK、Claude Code 及其他使用 Messages 协议的客户端。 + +### 主要请求参数 + +| 参数 | 类型 | 必填 | 描述 | +|---|---|---:|---| +| `model` | string | 是 | 模型 ID。 | +| `max_tokens` | integer | 是 | 最大输出 token 数。 | +| `messages` | array | 是 | 用户与助手消息列表。 | +| `system` | string \| array | 否 | 系统提示词。 | +| `stream` | boolean | 否 | 是否使用 SSE 流式返回，默认 `false`。 | +| `temperature` | number | 否 | 采样温度，通常为 `0.0` 至 `1.0`。 | +| `top_p` | number | 否 | Nucleus Sampling 参数。 | +| `top_k` | integer | 否 | 仅从概率最高的前 K 个候选项采样。 | +| `stop_sequences` | string[] | 否 | 自定义停止序列。 | +| `thinking` | object | 否 | 扩展思考配置。 | +| `tools` | array | 否 | Anthropic 格式的工具定义。 | +| `tool_choice` | object | 否 | 工具选择方式。 | + +### 请求示例 + +```bash +curl https://api.b.ai/v1/messages \ + -H "x-api-key: $BAI_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "your-model-id", + "max_tokens": 512, + "messages": [ + {"role": "user", "content": "Hello, Claude!"} + ] + }' +``` + +### 非流式响应示例 ```json { - "type": "function", - "function": { - "name": "get_weather", - "description": "Get weather for a location", - "parameters": { - "type": "object", - "properties": { - "location": { "type": "string" } - }, - "required": ["location"] + "id": "msg_xxx", + "type": "message", + "role": "assistant", + "content": [ + { + "type": "text", + "text": "Hello! How can I help you?" } + ], + "stop_reason": "end_turn", + "model": "your-model-id", + "usage": { + "input_tokens": 4, + "output_tokens": 12 } } ``` -### WebSearchOptions +### 流式事件 -| 字段 | 类型 | 描述 | -|------|------|------| -| `search_context_size` | string | `"low"`、`"medium"` 或 `"high"`，表示网页搜索结果占用的上下文大小。 | -| `user_location` | object | 用户的大致位置（国家 ISO 3166-1 alpha-2、城市、地区、时区）。 | +设置 `stream: true` 时，常见事件包括： -### ChatResponseFormat +| 事件类型 | 描述 | +|---|---| +| `message_start` | 返回初始消息元数据。 | +| `content_block_start` | 开始新的内容块。 | +| `content_block_delta` | 返回文本或思考内容增量。 | +| `content_block_stop` | 当前内容块结束。 | +| `message_delta` | 返回停止原因及使用量增量。 | +| `message_stop` | 消息完成。 | -| 字段 | 类型 | 描述 | -|------|------|------| -| `type` | string | `"text"` 或 `"json_object"` | -| `json_schema` | object | 当 `type` 为 `json_schema` 时，指定可选的输出结构 schema。 | +--- + +## Codex CLI 接入 + +B.AI Responses API 可以作为 Codex 的自定义模型提供商使用。以下配置适用于支持自定义模型提供商的 Codex 版本。 + +### 1. 设置 API Key + +```bash +export BAI_API_KEY="sk-..." +``` + +### 2. 编辑 Codex 配置 + +编辑用户级配置文件： + +```text +~/.codex/config.toml +``` + +写入以下配置： + +```toml +model = "your-model-id" +model_provider = "bai" + +[model_providers.bai] +name = "B.AI" +base_url = "https://api.b.ai/v1" +env_key = "BAI_API_KEY" +wire_api = "responses" +requires_openai_auth = false +``` + +如果该文件已有内容，把 `[model_providers.bai]` 整块追加进去，并将顶层的 `model` 与 `model_provider` 改成上面的取值。各配置项的完整说明见文末的 Codex 文档。 + +保存后，在已经设置 `BAI_API_KEY` 的终端中启动 Codex： + +```bash +codex +``` + +要更换模型，修改配置中的顶层 `model`： + +```toml +model = "your-model-id" +``` + +### Codex 常见问题 + +| 问题 | 检查方法 | +|---|---| +| 提示环境变量不存在 | 确认 `env_key` 与环境变量名称完全一致，并从设置该变量的终端启动 Codex。 | +| 请求发往 OpenAI 而不是 B.AI | 确认顶层 `model_provider = "bai"`，并存在 `[model_providers.bai]` 配置块。 | +| 返回 `401` | 检查 API Key 是否有效，以及是否误用了其他环境的 Key。 | +| 返回 `403` | 检查账户状态与模型权限。 | +| 返回模型不支持 | 确认模型 ID 拼写正确，并已为所配置的端点启用。 | + +--- + +## 如何选择接口 + +| 项目 | Chat Completions | Responses | Messages | +|---|---|---|---| +| 端点 | `/v1/chat/completions` | `/v1/responses` | `/v1/messages` | +| 兼容协议 | OpenAI Chat Completions | OpenAI Responses | Anthropic Messages | +| 主要输入字段 | `messages` | `input` | `messages` | +| 输出上限字段 | `max_tokens` / `max_completion_tokens` | `max_output_tokens` | `max_tokens` | +| 文本输出位置 | `choices[].message.content` | `output[].content[].text` | `content[].text` | +| 输入 token | `usage.prompt_tokens` | `usage.input_tokens` | `usage.input_tokens` | +| 输出 token | `usage.completion_tokens` | `usage.output_tokens` | `usage.output_tokens` | +| 推理 token | `completion_tokens_details.reasoning_tokens` | `output_tokens_details.reasoning_tokens` | 取决于模型和响应内容块 | +| 流式格式 | SSE chunks | SSE events | SSE events | +| 推荐场景 | 现有 OpenAI 兼容应用 | 新项目、Agent、Codex、工具调用 | Anthropic SDK、Claude Code | + +请选择与客户端协议及请求结构匹配的端点。 --- ## 错误响应 -所有错误响应都遵循以下格式： +非流式请求以及建立 SSE 连接前发生的错误，统一返回 JSON： ```json { "error": { - "message": "Error message", + "message": "model \"example-model\" is not supported on /v1/responses", "type": "invalid_request_error", - "param": null, - "code": null + "param": "", + "code": "model_not_supported_on_endpoint" } } ``` | 字段 | 类型 | 描述 | -|------|------|------| -| `message` | string | 错误信息 | -| `type` | string | 错误类型（例如 `invalid_request_error`） | -| `param` | string \| null | 相关参数 | -| `code` | string \| null | 错误代码 | +|---|---|---| +| `message` | string | 面向开发者的错误说明，部分错误会附带 request ID。 | +| `type` | string | 错误类型，取值不止一种。 | +| `param` | string | 导致错误的请求参数，可能为空。 | +| `code` | string | 机器可读错误代码。 | + +错误响应包含 HTTP 状态码及 `error` 对象。应用可以结合 `code` 和 `message` 进行错误处理与排查。 + +### HTTP 状态码 + +| 状态码 | 描述 | 处理方式 | +|---:|---|---| +| `200` | 请求成功 | 按对应端点格式解析响应。 | +| `400` | 请求因格式、参数或端点兼容性而无法处理 | 读取错误对象的 `code` 与 `message`。 | +| `401` | API Key 缺失、无效或已过期 | 检查认证请求头和所使用的环境。 | +| `403` | 模型权限、订阅或账户状态限制 | 检查账户状态与模型权限。 | +| `404` | 请求的资源或模型不存在 | 检查请求路径和模型 ID。 | +| `413` | 请求体超过平台限制 | 缩短输入或减少请求内容。 | +| `429` | 触发速率限制 | 使用指数退避重试并降低并发。 | +| `500` | 服务器内部错误 | 记录 request ID，稍后重试。 | +| `502` | 上游服务错误 | 使用指数退避重试。 | +| `503` | 服务暂时不可用 | 稍后重试或选择其他模型。 | + +### Responses 常见错误 + +| 场景 | 状态码 | 处理方式 | +|---|---:|---| +| 模型与端点不兼容 | `400` | 选择已为该端点启用的模型，或改用其他端点。 | +| 使用 `max_tokens` 或 `max_completion_tokens` | `400` | 改用 `max_output_tokens`。 | +| `max_output_tokens` 超出模型允许范围 | `400` | 按错误信息给出的范围调整取值。 | +| 请求使用了不可用的工具 | `400` | 移除该工具，或选择兼容的模型配置。 | +| Key 无效或环境不匹配 | `401` | 使用生产环境签发的 Key 请求生产域名。 | +| 流式请求在建流前失败 | `4xx` / `5xx` | 按 JSON 错误对象解析，不要按 SSE 解析。 | + +### 重试建议 + +- `400`、`401`、`403`、`404` 需要修改请求或账户状态，不建议自动重试； +- `429`、`500`、`502`、`503` 可以使用带随机抖动的指数退避重试； +- 响应中的 request ID 可用于技术支持排查。 + +--- + +## 安全建议 + +API Key 等同于账户凭证，可以直接发起计费请求。 + +- Key 应保存在服务端或受保护的本地环境中，通过环境变量或密钥管理服务注入，不要写入浏览器前端、移动端安装包或公开代码仓库； +- 开发、测试与生产环境使用不同的 Key； +- 泄露的 Key 应立即撤销，日志与支持工单中只保留掩码形式，例如 `sk-****abcd`。 + +--- + +## 相关资源 + +- B.AI 文档： +- B.AI 官网： +- OpenAI API 文档： +- Codex 文档： diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/llmservice/models/glm-5-3-flash.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/llmservice/models/glm-5-3-flash.md new file mode 100644 index 00000000..81527e6b --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/llmservice/models/glm-5-3-flash.md @@ -0,0 +1,64 @@ +import ActivityCard from '@site/src/components/ActivityCard'; + +# GLM-5.3-Flash + +## 概述 + +GLM-5.3-Flash 是 Z.AI 于 2026 年 8 月 26 日发布的开放权重原生多模态模型，也是 GLM-5 系列的 Flash 级模型。该模型拥有 3200 亿总参数和 180 亿激活参数，支持 1M Token 上下文，并采用稀疏注意力与线性注意力相结合的混合架构，面向编程、Agent 和视觉知识工作负载。 + + +本活动覆盖 B.AI API 和 Chat： + +* **API：** GLM-5.3-Flash API 调用目前按 `0 Credits` 结算，不收取输入、缓存写入、缓存读取或输出 Token 费用。 +* **Chat：** GLM-5.3-Flash 在 B.AI Chat 上架后免费开放，具体开放时间以模型实际上架为准；开放后，Chat 使用按 `0 Credits` 结算。 + +活动结束后，GLM-5.3-Flash 将恢复本页展示的价格。 + + +## 主要特性 + +* **高效混合架构**：采用稀疏注意力、线性注意力、流形约束超连接（mHC）和 IndexPool。Z.AI 在架构对比中表示，与 GLM-5.3 相比，该模型的注意力计算量降低至约三分之一，KV Cache 体积缩小至约四分之一。 +* **原生多模态理解**：支持文本、图片、视频和文件输入，使 Agent 能够在任务中检查界面、渲染结果、文档及其他视觉信息。 +* **编程与 Agent 评测**：Z.AI 公布的评测结果包括 Terminal-Bench 2.1 为 84.3、DeepSWE v1.1 为 63.4、Toolathlon Verified 为 78.4，以及 AutomationBench v1.0.6 为 48.8。 +* **可配置的始终开启推理**：支持 `low`、`high` 和 `max` 推理强度，默认使用 `max`，不支持关闭推理。 + +## 适用场景 + +* **可视化软件工程**：结合截图或渲染结果检查，构建和优化前端、游戏、3D 场景及其他交互界面。 +* **长周期编程 Agent**：适用于需要推理、函数调用和大上下文的代码库级实现、调试、测试及多步骤自动化任务。 +* **多模态专业工作流**：对文档、图表、仪表盘、演示文稿、电子表格和视频进行提取与推理，再通过 Agent 环境生成结构化文本或办公交付物。 +* **成本敏感型 API 工作负载**：适用于重视低 Token 成本、缓存输入价格和 1M Token 上下文的大规模文本及多模态任务。 + +## 能力与限制 + +| 能力 | 说明 | +| :--- | :--- | +| **推理** | 推理始终开启。`reasoning_effort` 支持 `low`、`high` 和 `max`，默认值为 `max`。 | +| **创意写作** | 支持通用文本和长文本生成。 | +| **编程** | Z.AI 公布的评测结果包括 Terminal-Bench 2.1：84.3、DeepSWE v1.1：63.4、NL2Repo：56.3、Toolathlon Verified：78.4，以及 AutomationBench v1.0.6：48.8。 | +| **多模态** | 支持文本、图片、视频和文件输入，输出文本。 | +| **上下文窗口** | 1,000,000 Token。 | +| **最大输出** | 最高 131,072 Token；`max_tokens` 默认值为 65,536。 | +| **工具调用** | 支持函数调用、流式工具调用、上下文缓存和 JSON 结构化输出。ZCode 可结合 Browser Use 和 Computer Use，用于需要视觉信息支撑的 Agent 工作流。 | +| **多语言** | 官方模型仓库标明支持英文和中文。 | + +### 已知限制 + +* `thinking.type` 仅支持 `enabled`；需要降低推理强度时，应使用 `reasoning_effort: "low"`，而不是关闭推理。 + +## Credits 用量 + +| 模型 | 输入（Credits/Token） | 缓存写入（Credits/Token） | 缓存读取（Credits/Token） | 输出（Credits/Token） | 联网搜索（Credits/次） | +| :--- | --------------------: | ------------------------: | ------------------------: | --------------------: | ----------------------: | +| **GLM-5.3-Flash** | `0.075` | `0.075` | `0.015` | `0.25` | `-` | + +**限时价格说明：** 50% Token 价格活动将于 2026 年 9 月 9 日 24:00（UTC+8，新加坡时间）结束。 + +:::info 价格说明 +文档价格为 B.AI 平台模型标准参考价，仅供基础计费说明使用。B.AI 可能会通过限时活动、充值赠送及账户权益等方式，为用户提供更低的实际使用成本。具体价格、赠送 Credits、账户权益及最终结算请以平台页面和账单记录为准。 +::: diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/llmservice/models/qwen3-8-flash.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/llmservice/models/qwen3-8-flash.md new file mode 100644 index 00000000..d21b515e --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/llmservice/models/qwen3-8-flash.md @@ -0,0 +1,70 @@ +import ActivityCard from '@site/src/components/ActivityCard'; + +# Qwen3.8-Flash + +## 概述 + +Qwen3.8-Flash 是阿里巴巴 Qwen 团队于 2026 年 8 月 26 日发布的托管多模态模型。该模型是基于 Qwen3.8-Flash-Next 构建的生产版本，提供默认 100 万 Token 上下文窗口和托管工具，面向成本敏感的编程、Agent 与视觉知识工作场景。 + + +B.AI API 和 Chat 分阶段开放免费使用： + +* **API：** Qwen3.8-Flash API 调用目前按 `0 Credits` 结算，不收取输入、缓存写入、缓存读取或输出 Token 费用。 +* **Chat：** Qwen3.8-Flash 在 B.AI Chat 上架后免费开放，具体免费开放日期以模型实际上架为准；开放后，Chat 使用按 `0 Credits` 结算。 + +活动结束后，Qwen3.8-Flash 将恢复本页展示的价格。 + + +## 核心特性 + +* **基于 Flash-Next 的生产版本：** Qwen 将 `qwen3.8-flash` 定义为基于 Qwen3.8-Flash-Next 构建的生产版本。相关开放权重架构采用 Gated DeltaNet、Qwen Sparse Attention、Gated Residual 和 N-gram Embedding；QwenCloud 未单独公布生产模型的参数量。 +* **原生多模态输入：** 支持文本、图像和视频输入，输出为文本，适用于视觉编程、文档分析、图表理解和长视频理解。 +* **100 万 Token 托管上下文：** 非 Thinking 模式最多支持 991K 输入 Token，Thinking 模式最多支持 983K 输入 Token；两种模式均支持最高 131K 输出 Token。 +* **Thinking 与 Agent 控制：** QwenCloud 文档说明 Qwen3.8 系列默认启用 Thinking，可通过 `enable_thinking` 控制，并列出最高 262K Token 的推理预算。 +* **面向 Agent 的 API 能力：** 支持前缀续写、函数调用、上下文缓存、结构化输出、Batch API 批处理、微调，以及 QwenCloud Responses API 提供的内置工具。 +* **Flash-Next 评测结果：** 相关开放权重基础模型在 SWE-bench Pro、DeepSWE 1.1、CoWorkBench 和 Toolathlon Verified 上分别报告 62.5、58.7、73.9 和 73.5。Qwen 尚未单独发布托管生产端点的基准测试表。 + +## 适用场景 + +* **成本敏感的编程 Agent：** 适用于代码仓库分析、代码生成、调试和工具驱动开发等关注 Token 成本与账户级速率限制的场景。 +* **长上下文知识工作：** 在 100 万 Token 托管上下文中处理大型文档集、代码库、对话历史和研究资料。 +* **多模态分析：** 结合文本指令理解截图、图表、扫描文档、界面和视频。 +* **结构化 Agent 工作流：** 适用于结合函数调用、JSON 结构化输出、代码执行、搜索、提取和共享提示词缓存的应用。 +* **异步批量处理：** 通过 Batch API 执行分类、提取、评估和数据集处理，批处理输入与输出价格为实时调用价格的一半。 + +## 能力与限制 + +| 能力维度 | 说明 | +| :--- | :--- | +| **推理能力** | Qwen3.8 系列默认启用 Thinking，并可通过 `enable_thinking` 控制。QwenCloud 列出最高 262K Token 的推理预算，但模型页面未公布该模型专属的推理强度映射。 | +| **创意写作** | 支持通用、长篇和结构化文本生成。 | +| **编程能力** | 相关 Qwen3.8-Flash-Next 评测报告 SWE-bench Pro 62.5、DeepSWE 1.1 58.7、SWE-bench Multilingual 81.0 和 NL2Repo-Bench 48.1；这些结果不代表托管端点的 SLA。 | +| **多模态能力** | 支持文本、图像和视频输入，输出为文本。 | +| **上下文窗口** | 100 万 Token。 | +| **最大输入** | 非 Thinking 模式为 991K Token，Thinking 模式为 983K Token。 | +| **最大输出** | Thinking 和非 Thinking 模式均为 131K Token。 | +| **工具调用** | 支持函数调用、结构化输出、前缀续写、缓存和 Batch API。Responses API 工具包括 `code_interpreter`、`i2i_search`、`t2i_search`、`web_extractor` 和 `web_search`。 | +| **多语言能力** | 相关 Flash-Next 评测覆盖多语言推理和编程基准。 | + +### 已知限制 + +* `qwen3.8-flash` 是托管生产模型，`Qwen/Qwen3.8-Flash-Next` 则是相关的开放权重架构版本。参数量、自托管行为和 Flash-Next 基准测试结果不应视为托管端点的保证。 +* QwenCloud 未公布该模型专属的知识截止时间或完整支持语言列表。 +* Thinking Token 按输出 Token 价格计费并占用上下文。应用应根据任务需要启用 Thinking，不应假设更大的推理预算一定更高效。 + +## 价格 + +| 模型名称 | 输入（Credits/Token） | 缓存写入（Credits/Token） | 缓存读取（Credits/Token） | 输出（Credits/Token） | 网页搜索（Credits/次） | +| :--- | --------------------: | -------------------------: | -------------------------: | --------------------: | ---------------------: | +| **Qwen3.8-Flash** | `0.16` | `0.16` | `0.016` | `0.47` | `-` | + +该模型的显式缓存创建价格为 `0.20 Credits/Token`；显式缓存命中与隐式缓存命中的价格均为 `0.016 Credits/Token`。 + +:::info 价格说明 +文档价格为 B.AI 平台模型标准参考价，仅供基础计费说明使用。B.AI 可能会通过限时活动、充值赠送及账户权益等方式，为用户提供更低的实际使用成本。具体价格、赠送积分、账户权益及最终账单请以平台页面展示和账单记录为准。 +::: diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/llmservice/pricing-and-usage.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/llmservice/pricing-and-usage.md index 6224f21c..da05361a 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/llmservice/pricing-and-usage.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/llmservice/pricing-and-usage.md @@ -29,6 +29,7 @@ | Kimi K3 | 3.00 | 3.00 | 0.30 | 15.00 | - | | Kimi K2.6 | 0.95 | 0.95 | 0.1615 | 4.00 | - | | Kimi K2.5 | 0.59 | 0.59 | 0.10 | 3.00 | - | +| Qwen3.8-Flash | 0.16 | 0.16 | 0.016 | 0.47 | - | | Qwen3.8-27B | 0.22 | 0.22 | 0.022 | 1.60 | - | | Qwen3.8-Max | 2.00 | 2.00 | 0.25 | 6.00 | - | | Qwen3.7-Max | 1.65 | 1.65 | 0.33 | 4.951 | - | @@ -36,6 +37,7 @@ | Hy3 | 0.132 | 0.132 | 0.033 | 0.528 | - | | MiMo-V2.5-Pro | 0.435 | 0.435 | 0.0036 | 0.87 | - | | MiMo-V2.5 | 0.14 | 0.14 | 0.0028 | 0.28 | - | +| GLM-5.3-Flash | 0.075 | 0.075 | 0.015 | 0.25 | - | | GLM-5.3 | 1.40 | 1.40 | 0.28 | 4.40 | - | | GLM-5.2 | 1.40 | 1.40 | 0.28 | 4.40 | - | | GLM-5.1 | 1.40 | 1.40 | 0.28 | 4.40 | - | diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/llmservice/promotions-and-pricing-notices.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/llmservice/promotions-and-pricing-notices.md index 8e1e5cb2..7961a7ea 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/llmservice/promotions-and-pricing-notices.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/llmservice/promotions-and-pricing-notices.md @@ -69,6 +69,34 @@ MiMo-V2.5 免费分阶段开放： 活动结束后，MiMo-V2.5 将恢复标准价格。详见[模型详情](./models/mimo-v2.5.md)。 + +本活动覆盖 B.AI API 和 Chat： + +* **API：** GLM-5.3-Flash API 调用目前按 `0 Credits` 结算，不收取输入、缓存写入、缓存读取或输出 Token 费用。 +* **Chat：** GLM-5.3-Flash 在 B.AI Chat 上架后免费开放，具体开放时间以模型实际上架为准；开放后，Chat 使用按 `0 Credits` 结算。 + +活动结束后，GLM-5.3-Flash 将恢复[模型详情](./models/glm-5-3-flash.md)中展示的价格。 + + + +B.AI API 和 Chat 分阶段开放免费使用： + +* **API：** Qwen3.8-Flash API 调用目前按 `0 Credits` 结算，不收取输入、缓存写入、缓存读取或输出 Token 费用。 +* **Chat：** Qwen3.8-Flash 在 B.AI Chat 上架后免费开放，具体免费开放日期以模型实际上架为准；开放后，Chat 使用按 `0 Credits` 结算。 + +活动结束后，Qwen3.8-Flash 将恢复[模型详情](./models/qwen3-8-flash.md)中展示的价格。 + +