From 2dbed57777e6829da0cabbd6bc3392b1ede9e1ea Mon Sep 17 00:00:00 2001 From: ai-bankofai Date: Mon, 30 Mar 2026 19:03:21 +0800 Subject: [PATCH 1/5] Update API.md Add /messages end point --- docs/llmservice/api/API.md | 454 +++++++++++++++++++++++-------------- 1 file changed, 280 insertions(+), 174 deletions(-) diff --git a/docs/llmservice/api/API.md b/docs/llmservice/api/API.md index 6f67b862..f1ef9387 100644 --- a/docs/llmservice/api/API.md +++ b/docs/llmservice/api/API.md @@ -1,236 +1,342 @@ -# AI API (OpenAI Compatible) +# AI API + Chat completion. Auth: Bearer token. Non-stream: JSON with choices[].content. Stream: SSE chunks with choices[].delta.content. -## Version: 1.0 +- **Version:** 1.0 + +## Servers + +| URL | Description | +|-----|-------------| +| `https://api.ainft.com` | Production | + +## Authentication + +### Bearer Auth -### BaseURL -https://api.bankofai.io/ +- **Type:** HTTP Bearer +- **Format:** JWT +- **Description:** Bearer \, e.g. `Bearer sk-xxx` -### Available authorizations -#### bearerAuth (HTTP, bearer) -Bearer ``, e.g. Bearer sk-xxx -Bearer format: JWT +### API Key Auth + +- **Type:** API Key +- **In:** Header +- **Name:** `x-api-key` +- **Description:** API Key authentication, e.g. `x-api-key: your-api-key` --- -## Model List -### [GET] /v1/models -**List models (OpenAI compatible)** +## Endpoints + +### Model List + +#### `GET /v1/models` - List models (OpenAI compatible) List available models. Auth: Bearer token. Response: object, success, data. -#### Responses +**Authentication:** Bearer Auth + +**Responses:** -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | object: list; success: true; data: array of { id, object, created, owned_by } | **application/json**: [V1ModelsResponse](#v1modelsresponse)
| -| 400 | Bad Request - invalid parameters or malformed body | **application/json**: [ErrorResponse](#errorresponse)
| -| 401 | Unauthorized - invalid or missing authentication | **application/json**: [ErrorResponse](#errorresponse)
| -| 403 | Forbidden - access denied, insufficient quota, or banned | **application/json**: [ErrorResponse](#errorresponse)
| -| 429 | Too Many Requests - rate limit exceeded | **application/json**: [ErrorResponse](#errorresponse)
| -| 500 | Internal Server Error | **application/json**: [ErrorResponse](#errorresponse)
| +| Status Code | Description | +|-------------|-------------| +| 200 | object: list; success: true; data: array of { id, object, created, owned_by } | +| 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 | -##### Security +**200 Response Schema:** [V1ModelsResponse](#v1modelsresponse) -| Security Schema | Scopes | -| --------------- | ------ | -| bearerAuth | | +**Error Response Schema:** [ErrorResponse](#errorresponse) --- -## Chat Completions -### [POST] /v1/chat/completions -**Create chat completion (OpenAI compatible)** +### Messages -Chat completion. Auth: Bearer token. Non-stream: JSON with choices[].content. Stream: SSE chunks with choices[].delta.content. +#### `POST /v1/messages` - Send a message (Claude compatible) + +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. Responses can be streamed (SSE) or returned as a single JSON object. + +**Authentication:** API Key Auth (`x-api-key`) + +**Request Body:** [ChatCompletionsRequest](#chatcompletionsrequest) (required, `application/json`) + +**Responses:** + +| Status Code | Description | +|-------------|-------------| +| 200 | Success. Schema differs by stream mode. | +| 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 | + +**200 Response Content Types:** +- `application/json`: [ChatCompletionsResponse](#chatcompletionsresponse) +- `text/event-stream`: [ChatCompletionsResponse](#chatcompletionsresponse) + +**Error Response Schema:** [ErrorResponse](#errorresponse) + +--- + +### Chat Completions + +#### `POST /v1/chat/completions` - Create a chat completion (OpenAI compatible) + +Accepts a list of messages and returns a model-generated response. Supports both single-turn and multi-turn conversations. Authenticate via Bearer token. Responses can be streamed (SSE) or returned as a single JSON object. + +**Authentication:** Bearer Auth + +**Request Body:** [ChatCompletionsRequest](#chatcompletionsrequest) (required, `application/json`) + +**Responses:** + +| Status Code | Description | +|-------------|-------------| +| 200 | Success. Schema differs by stream mode. | +| 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 | + +**200 Response Content Types:** +- `application/json`: [ChatCompletionsResponse](#chatcompletionsresponse) +- `text/event-stream`: [ChatCompletionsResponse](#chatcompletionsresponse) + +**Error Response Schema:** [ErrorResponse](#errorresponse) + +--- + +## Schemas + +### ErrorResponse + +| Field | Type | Description | +|-------|------|-------------| +| `error` | object | Error details | +| `error.message` | string | Error message | +| `error.type` | string | Error type (e.g. invalid_request_error) | +| `error.param` | string \| null | Related parameter | +| `error.code` | string \| null | Error code | -#### Request Body +--- + +### V1ModelsResponse -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [ChatCompletionsRequest](#chatcompletionsrequest)
| +| Field | Type | Example | Description | +|-------|------|---------|-------------| +| `object` | string | `"list"` | | +| `success` | boolean | `true` | | +| `data` | array | | Array of [V1ModelItem](#v1modelitem) | -#### Responses +--- -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Success. Schema differs by stream mode. | **application/json**: [ChatCompletionsResponse](#chatcompletionsresponse)
**text/event-stream**: [ChatCompletionsResponse](#chatcompletionsresponse)
| -| 400 | Bad Request - invalid parameters, malformed body, or invalid request | **application/json**: [ErrorResponse](#errorresponse)
| -| 401 | Unauthorized - invalid or missing authentication | **application/json**: [ErrorResponse](#errorresponse)
| -| 403 | Forbidden - access denied, insufficient quota, or model access restricted | **application/json**: [ErrorResponse](#errorresponse)
| -| 429 | Too Many Requests - rate limit exceeded | **application/json**: [ErrorResponse](#errorresponse)
| -| 500 | Internal Server Error | **application/json**: [ErrorResponse](#errorresponse)
| -| 502 | Bad Gateway - upstream service error | **application/json**: [ErrorResponse](#errorresponse)
| -| 503 | Service Unavailable - overloaded or no available channel | **application/json**: [ErrorResponse](#errorresponse)
| - -##### Security +### V1ModelItem -| Security Schema | Scopes | -| --------------- | ------ | -| bearerAuth | | +| Field | Type | Example | Description | +|-------|------|---------|-------------| +| `id` | string | `"gpt-4"` | | +| `object` | string | `"model"` | | +| `created` | integer | `1626777600` | | +| `owned_by` | string | `"openai"` | | --- -### Schemas -#### ErrorResponse +### ChatCompletionsRequest + +**Required fields:** `model`, `messages` + +| Field | Type | Description | Example | +|-------|------|-------------|---------| +| `model` | string | ID of the model to use (e.g. gpt-4). | `"gpt-4"` | +| `messages` | array | List of messages in the conversation. Array of [ChatMessage](#chatmessage). | | +| `stream` | boolean | If true, partial message deltas will be sent as server-sent events. Default false. | | +| `max_tokens` | integer | Maximum number of tokens that can be generated in the completion. | | +| `temperature` | number | Sampling temperature between 0 and 2. Higher = more random. Default 1. | | +| `top_p` | number | Nucleus sampling: consider tokens with top_p probability mass. Default 1. | | +| `stop` | string \| string[] | Up to 4 sequences where the API will stop generating. String or array of strings. | | +| `n` | integer | How many chat completion choices to generate. Default 1. | | +| `frequency_penalty` | number | -2.0 to 2.0. Penalize repeated tokens. Default 0. | | +| `presence_penalty` | number | -2.0 to 2.0. Penalize tokens that appear in the text so far. Default 0. | | +| `seed` | integer | Random seed for deterministic sampling (if supported by model). | | +| `response_format` | object | [ChatResponseFormat](#chatresponseformat). Specify output format. | | +| `tools` | array | List of tools the model may call. Array of [ChatTool](#chattool). Each has type "function" and function { name, description?, parameters? }. | | +| `tool_choice` | string \| object | `"auto"` \| `"none"` \| `"required"` \| [ToolChoiceObject](#toolchoiceobject). | | +| `user` | string | Optional end-user identifier for abuse monitoring. | | +| `web_search_options` | object | [WebSearchOptions](#websearchoptions). Optional web search configuration. | | -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| error | { **"message"**: string, **"type"**: string, **"param"**: string, null, **"code"**: string, null } | | No | +--- -#### V1ModelsResponse +### WebSearchOptions -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| object | string | *Example:* `"list"` | No | -| success | boolean | *Example:* `true` | No | -| data | [ [V1ModelItem](#v1modelitem) ] | | No | +Optional. Enables web search for models that support it (OpenAI Chat Completions). When present, this gateway treats the request as web-search-enabled; model allowlists may apply. Field names align with OpenAI `web_search_options`. -#### V1ModelItem +| Field | Type | Description | Example | +|-------|------|-------------|---------| +| `search_context_size` | string | Guidance for how much context window space to use for web search results. Enum: `"low"`, `"medium"`, `"high"`. | `"medium"` | +| `user_location` | object | Approximate user location to refine search results (e.g. country as ISO 3166-1 alpha-2, city, region, timezone). Structure follows OpenAI documentation. | | -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| id | string | *Example:* `"gpt-4"` | No | -| object | string | *Example:* `"model"` | No | -| created | integer | *Example:* `1626777600` | No | -| owned_by | string | *Example:* `"openai"` | No | +--- -#### ChatCompletionsRequest +### ChatMessage -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| model | string | ID of the model to use (e.g. gpt-4).
*Example:* `"gpt-4"` | Yes | -| messages | [ [ChatMessage](#chatmessage) ] | List of messages in the conversation. | Yes | -| stream | boolean | If true, partial message deltas will be sent as server-sent events. Default false. | No | -| max_tokens | integer | Maximum number of tokens that can be generated in the completion. | No | -| temperature | number | Sampling temperature between 0 and 2. Higher = more random. Default 1. | No | -| top_p | number | Nucleus sampling: consider tokens with top_p probability mass. Default 1. | No | -| stop | | Up to 4 sequences where the API will stop generating. String or array of strings. | No | -| n | integer | How many chat completion choices to generate. Default 1. | No | -| frequency_penalty | number | -2.0 to 2.0. Penalize repeated tokens. Default 0. | No | -| presence_penalty | number | -2.0 to 2.0. Penalize tokens that appear in the text so far. Default 0. | No | -| seed | integer | Random seed for deterministic sampling (if supported by model). | No | -| response_format | [ChatResponseFormat](#chatresponseformat) | | No | -| tools | [ [ChatTool](#chattool) ] | List of tools the model may call. Each has type "function" and function { name, description?, parameters? }. | No | -| tool_choice | | | No | -| user | string | Optional end-user identifier for abuse monitoring. | No | +| Field | Type | Description | Example | +|-------|------|-------------|---------| +| `role` | string | `"system"` \| `"user"` \| `"assistant"` \| `"tool"`. System sets behavior; user/assistant are conversation; tool is tool result. | `"user"` | +| `content` | string | Message content. For tool role, the result of the tool call. | `"Hello"` | +| `name` | string | Optional name for the message author (e.g. to disambiguate multiple users). | | +| `tool_call_id` | string | When role is "tool", the id of the tool call this result is for. Required for tool messages. | | +| `tool_calls` | array | When role is "assistant" and the model called tools, array of [ChatToolCallItem](#chattoolcallitem). | | -#### ChatMessage +--- -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| role | string | "system" \| "user" \| "assistant" \| "tool". System sets behavior; user/assistant are conversation; tool is tool result.
*Example:* `"user"` | No | -| content | string | Message content. For tool role, the result of the tool call.
*Example:* `"Hello"` | No | -| name | string | Optional name for the message author (e.g. to disambiguate multiple users). | No | -| tool_call_id | string | When role is "tool", the id of the tool call this result is for. Required for tool messages. | No | -| tool_calls | [ [ChatToolCallItem](#chattoolcallitem) ] | When role is "assistant" and the model called tools, array of { id, type, function: { name, arguments } }. | No | +### ChatResponseFormat -#### ChatResponseFormat +Specify output format: `{ "type": "text" }` or `{ "type": "json_object" }` or json_schema. -Specify output format: { "type": "text" } or { "type": "json_object" } or json_schema. +| Field | Type | Description | +|-------|------|-------------| +| `type` | string | `"text"` or `"json_object"`. | +| `json_schema` | any | When type is json_schema, optional schema for the output. | -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| type | string | "text" or "json_object". | No | -| json_schema | | When type is json_schema, optional schema for the output. | No | +--- -#### ChatTool +### ChatTool -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| type | string | Must be "function".
*Example:* `"function"` | No | -| function | [ChatToolFunction](#chattoolfunction) | Function definition (name, description, parameters). | No | +| Field | Type | Description | Example | +|-------|------|-------------|---------| +| `type` | string | Must be `"function"`. | `"function"` | +| `function` | object | [ChatToolFunction](#chattoolfunction). Function definition (name, description, parameters). | | -#### ChatToolFunction +--- -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| name | string | Name of the function. | No | -| description | string | Optional description for the model. | No | -| parameters | | Optional JSON schema for the function arguments. | No | +### ChatToolFunction -#### ChatToolCallItem - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| id | string | ID of the tool call. | No | -| type | string | "function".
*Example:* `"function"` | No | -| function | [ChatToolCallFunction](#chattoolcallfunction) | Name and arguments of the call. | No | +| Field | Type | Description | +|-------|------|-------------| +| `name` | string | Name of the function. | +| `description` | string | Optional description for the model. | +| `parameters` | any | Optional JSON schema for the function arguments. | -#### ChatToolCallFunction +--- -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| name | string | Name of the function to call. | No | -| arguments | string | JSON string of the arguments. | No | +### ChatToolCallItem -#### ToolChoiceObject +| Field | Type | Description | Example | +|-------|------|-------------|---------| +| `id` | string | ID of the tool call. | | +| `type` | string | `"function"`. | `"function"` | +| `function` | object | [ChatToolCallFunction](#chattoolcallfunction). Name and arguments of the call. | | + +--- + +### ChatToolCallFunction + +| Field | Type | Description | +|-------|------|-------------| +| `name` | string | Name of the function to call. | +| `arguments` | string | JSON string of the arguments. | + +--- + +### ToolChoiceObject Precise mode: specifies the particular function to call. -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| type | string,
**Available values:** "function" | Must be "function".
*Enum:* `"function"`
*Example:* `"function"` | Yes | -| function | [ToolChoiceFunction](#toolchoicefunction) | Function definition to call. | Yes | +**Required fields:** `type`, `function` -#### ToolChoiceFunction +| Field | Type | Description | Example | +|-------|------|-------------|---------| +| `type` | string | Must be `"function"`. Enum: `"function"`. | `"function"` | +| `function` | object | [ToolChoiceFunction](#toolchoicefunction). Function definition to call. | | -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| name | string | Name of the function to call. | Yes | +--- -#### ChatCompletionsResponse +### ToolChoiceFunction + +**Required fields:** `name` + +| Field | Type | Description | +|-------|------|-------------| +| `name` | string | Name of the function to call. | + +--- + +### ChatCompletionsResponse Non-stream: object=chat.completion, choices[].message, usage. Stream: object=chat.completion.chunk, choices[].delta; final chunk has usage. -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| id | string | *Example:* `"chatcmpl-xxx"` | No | -| object | string,
**Available values:** "chat.completion", "chat.completion.chunk" | "chat.completion" (non-stream) or "chat.completion.chunk" (stream).
*Enum:* `"chat.completion"`, `"chat.completion.chunk"` | No | -| created | integer | *Example:* `1677652288` | No | -| model | string | *Example:* `"gpt-4"` | No | -| service_tier | string | *Example:* `"default"` | No | -| system_fingerprint | string, null | | No | -| choices | [ [ChatChoice](#chatchoice) ] | Empty in final usage chunk. | No | -| usage | | Non-stream: always present. Stream: null until final chunk. | No | -| obfuscation | string | | No | +| Field | Type | Description | Example | +|-------|------|-------------|---------| +| `id` | string | | `"chatcmpl-xxx"` | +| `object` | string | `"chat.completion"` (non-stream) or `"chat.completion.chunk"` (stream). | | +| `created` | integer | | `1677652288` | +| `model` | string | | `"gpt-4"` | +| `service_tier` | string | | `"default"` | +| `system_fingerprint` | string \| null | | | +| `choices` | array | Empty in final usage chunk. Array of [ChatChoice](#chatchoice). | | +| `usage` | null \| object | [ChatUsage](#chatusage). Non-stream: always present. Stream: null until final chunk. | | +| `obfuscation` | string | | | + +--- -#### ChatMessageContent +### ChatMessageContent Non-stream choices[].message. Full assistant message with role, content, refusal, annotations. -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| role | string | *Example:* `"assistant"` | No | -| content | string | Assistant reply text. | No | -| refusal | string, null | Refusal reason when model declines; null otherwise. | No | -| annotations | [ ] | Citations, references, etc. | No | +| Field | Type | Description | Example | +|-------|------|-------------|---------| +| `role` | string | | `"assistant"` | +| `content` | string | Assistant reply text. | | +| `refusal` | string \| null | Refusal reason when model declines; null otherwise. | | +| `annotations` | array | Citations, references, etc. | | + +--- -#### ChatChoice +### ChatChoice Non-stream: message. Stream: delta. finish_reason null until last content chunk. -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| index | integer | | No | -| message | [ChatMessageContent](#chatmessagecontent) | Non-stream only. Full assistant message. | No | -| delta | [ChatChoiceDelta](#chatchoicedelta) | Stream only. Incremental content; empty {} on stop. | No | -| finish_reason | string, null | Null until done; e.g. "stop", "length", "tool_calls". | No | - -#### ChatChoiceDelta - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| content | string | | No | -| role | string | | No | -| tool_calls | [ [ChatToolCallItem](#chattoolcallitem) ] | | No | - -#### ChatUsage - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| prompt_tokens | integer | Number of tokens in the prompt. | No | -| completion_tokens | integer | Number of tokens in the completion. | No | -| total_tokens | integer | Total tokens (prompt + completion). | No | -| prompt_tokens_details | { **"cached_tokens"**: integer, **"audio_tokens"**: integer } | | No | -| completion_tokens_details | { **"reasoning_tokens"**: integer, **"audio_tokens"**: integer, **"accepted_prediction_tokens"**: integer, **"rejected_prediction_tokens"**: integer } | | No | +| Field | Type | Description | +|-------|------|-------------| +| `index` | integer | | +| `message` | object | [ChatMessageContent](#chatmessagecontent). Non-stream only. Full assistant message. | +| `delta` | object | [ChatChoiceDelta](#chatchoicedelta). Stream only. Incremental content; empty {} on stop. | +| `finish_reason` | string \| null | Null until done; e.g. `"stop"`, `"length"`, `"tool_calls"`. | + +--- + +### ChatChoiceDelta + +| Field | Type | Description | +|-------|------|-------------| +| `content` | string | | +| `role` | string | | +| `tool_calls` | array | Array of [ChatToolCallItem](#chattoolcallitem). | + +--- + +### ChatUsage + +| Field | Type | Description | +|-------|------|-------------| +| `prompt_tokens` | integer | Number of tokens in the prompt. | +| `completion_tokens` | integer | Number of tokens in the completion. | +| `total_tokens` | integer | Total tokens (prompt + completion). | +| `prompt_tokens_details` | object | See below. | +| `prompt_tokens_details.cached_tokens` | integer | | +| `prompt_tokens_details.audio_tokens` | integer | | +| `completion_tokens_details` | object | See below. | +| `completion_tokens_details.reasoning_tokens` | integer | | +| `completion_tokens_details.audio_tokens` | integer | | +| `completion_tokens_details.accepted_prediction_tokens` | integer | | +| `completion_tokens_details.rejected_prediction_tokens` | integer | | From 56176645156794eeda1b2c78c58ddfe58a862063 Mon Sep 17 00:00:00 2001 From: ai-bankofai Date: Tue, 31 Mar 2026 11:15:50 +0800 Subject: [PATCH 2/5] Update API.md replace gpt-4 -> gpt-5.2 --- docs/llmservice/api/API.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/llmservice/api/API.md b/docs/llmservice/api/API.md index f1ef9387..eb4b884c 100644 --- a/docs/llmservice/api/API.md +++ b/docs/llmservice/api/API.md @@ -144,7 +144,7 @@ Accepts a list of messages and returns a model-generated response. Supports both | Field | Type | Example | Description | |-------|------|---------|-------------| -| `id` | string | `"gpt-4"` | | +| `id` | string | `"gpt-5.2"` | | | `object` | string | `"model"` | | | `created` | integer | `1626777600` | | | `owned_by` | string | `"openai"` | | @@ -157,7 +157,7 @@ Accepts a list of messages and returns a model-generated response. Supports both | Field | Type | Description | Example | |-------|------|-------------|---------| -| `model` | string | ID of the model to use (e.g. gpt-4). | `"gpt-4"` | +| `model` | string | ID of the model to use (e.g. gpt-5.2). | `"gpt-5.2"` | | `messages` | array | List of messages in the conversation. Array of [ChatMessage](#chatmessage). | | | `stream` | boolean | If true, partial message deltas will be sent as server-sent events. Default false. | | | `max_tokens` | integer | Maximum number of tokens that can be generated in the completion. | | @@ -280,7 +280,7 @@ Non-stream: object=chat.completion, choices[].message, usage. Stream: object=cha | `id` | string | | `"chatcmpl-xxx"` | | `object` | string | `"chat.completion"` (non-stream) or `"chat.completion.chunk"` (stream). | | | `created` | integer | | `1677652288` | -| `model` | string | | `"gpt-4"` | +| `model` | string | | `"gpt-5.2"` | | `service_tier` | string | | `"default"` | | `system_fingerprint` | string \| null | | | | `choices` | array | Empty in final usage chunk. Array of [ChatChoice](#chatchoice). | | From 3ad439c52f9d842b863ace28e8be1f4742d47d7b Mon Sep 17 00:00:00 2001 From: ai-bankofai Date: Tue, 31 Mar 2026 13:05:41 +0800 Subject: [PATCH 3/5] Update API.md --- docs/llmservice/api/API.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/llmservice/api/API.md b/docs/llmservice/api/API.md index eb4b884c..8c8526e5 100644 --- a/docs/llmservice/api/API.md +++ b/docs/llmservice/api/API.md @@ -8,7 +8,7 @@ Chat completion. Auth: Bearer token. Non-stream: JSON with choices[].content. St | URL | Description | |-----|-------------| -| `https://api.ainft.com` | Production | +| `https://api.bankofai.com` | Production | ## Authentication From e03b329fcacf0450043b20561e1fe3963ba30b7c Mon Sep 17 00:00:00 2001 From: ai-bankofai Date: Tue, 31 Mar 2026 13:16:52 +0800 Subject: [PATCH 4/5] Update API.md --- .../current/llmservice/api/API.md | 330 ++++++++++-------- 1 file changed, 184 insertions(+), 146 deletions(-) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/llmservice/api/API.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/llmservice/api/API.md index b03f16f3..55ecb3df 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/llmservice/api/API.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/llmservice/api/API.md @@ -1,221 +1,259 @@ -# Bank of AI LLM API（兼容 OpenAI） +# AI API -本接口与 **OpenAI API 完全兼容**，你可以直接复用现有 OpenAI SDK，仅需替换 Base URL 即可接入。 +聊天补全。认证：Bearer token。非流式返回：JSON（choices[].content）。流式返回：SSE（choices[].delta.content）。 -支持接口： +- **版本：** 1.0 -- `/v1/chat/completions`：对话生成 -- `/v1/models`：获取模型列表 +## Servers（服务器） + +| URL | 描述 | +|-----|------| +| `https://api.bankofai.com` | 生产环境 | --- -## 基本信息 +## Authentication（认证） + +### Bearer 认证 + +- **类型：** HTTP Bearer +- **格式：** JWT +- **说明：** Bearer \，例如：`Bearer sk-xxx` -- **版本：** 1.0 -- **协议：** https -- **Host：** api.bankofai.io +### API Key 认证 + +- **类型：** API Key +- **位置：** Header +- **字段名：** `x-api-key` +- **说明：** API Key 认证，例如：`x-api-key: your-api-key` --- -# /v1/chat/completions +## Endpoints（接口） -## POST +### 模型列表 -### 功能说明 -创建对话补全（Chat Completion），接口格式与 OpenAI 一致。 +#### `GET /v1/models` - 获取模型列表（OpenAI 兼容） -### 认证方式 -在 Header 中传入： +获取可用模型列表。认证：Bearer token。返回：object，success，data。 -``` -Authorization: Bearer sk-xxxx -``` +**认证方式：** Bearer Auth ---- +**响应：** + +| 状态码 | 描述 | +|--------|------| +| 200 | object: list；success: true；data: 模型数组（包含 id、object、created、owned_by） | +| 400 | 请求错误 - 参数无效或请求体格式错误 | +| 401 | 未授权 - 缺少或无效认证 | +| 403 | 禁止访问 - 权限不足、配额不足或被封禁 | +| 429 | 请求过多 - 触发限流 | +| 500 | 服务器内部错误 | -### 返回方式 +**200 响应结构：** [V1ModelsResponse](#v1modelsresponse) -- **普通模式**：返回完整 JSON（内容在 `choices[].content`） -- **流式模式**：SSE 流（内容在 `choices[].delta.content`） +**错误响应结构：** [ErrorResponse](#errorresponse) --- -## 请求参数 +### Messages（消息接口） -| 参数 | 位置 | 说明 | 必填 | -|-----|-----|-----|-----| -| Authorization | header | Bearer Token，例如 `Bearer sk-xxx` | 是 | -| body | body | 请求体（必须包含 model 和 messages） | 是 | +#### `POST /v1/messages` - 发送消息（Claude 兼容） ---- +接收消息列表并返回模型生成的响应。支持单轮和多轮对话。使用 x-api-key 认证。支持流式（SSE）和非流式返回。 -## 请求体字段说明（body） +**认证方式：** API Key（`x-api-key`） -| 字段 | 类型 | 说明 | -|----|----|----| -| model | string | 模型 ID，例如 `gpt-4` | -| messages | array | 对话消息列表 | -| max_tokens | integer | 最大生成 token 数 | -| temperature | number | 随机性（0~2） | -| top_p | number | 核采样 | -| n | integer | 返回结果数量 | -| stream | boolean | 是否开启流式输出 | -| stop | string / array | 停止词 | -| presence_penalty | number | 主题惩罚 | -| frequency_penalty | number | 频率惩罚 | -| tools | array | 可调用工具 | -| tool_choice | string / object | 工具调用策略 | -| response_format | object | 输出格式 | -| user | string | 用户标识 | +**请求体：** [ChatCompletionsRequest](#chatcompletionsrequest)（必填，`application/json`） ---- +**响应：** -## 返回结果 +| 状态码 | 描述 | +|--------|------| +| 200 | 成功（结构取决于是否使用流式） | +| 400 | 请求错误 - 参数或格式错误 | +| 401 | 未授权 - API Key 无效或缺失 | +| 403 | 禁止访问 - 权限不足或模型受限 | +| 429 | 请求过多 - 限流 | +| 500 | 服务器内部错误 | +| 502 | 网关错误 - 上游服务异常 | +| 503 | 服务不可用 - 系统过载或无可用通道 | -| 状态码 | 说明 | -|------|------| -| 200 | 成功返回结果（普通 / 流式） | -| 401 | 认证失败 | +**200 返回类型：** +- `application/json` +- `text/event-stream` + +**错误响应结构：** [ErrorResponse](#errorresponse) --- -# /v1/models +### Chat Completions（聊天补全） + +#### `POST /v1/chat/completions` - 创建聊天补全（OpenAI 兼容） + +接收消息列表并返回模型生成结果。支持单轮和多轮对话。使用 Bearer token 认证。支持流式和非流式返回。 -## GET +**认证方式：** Bearer Auth -### 功能说明 -获取当前可用模型列表。 +**请求体：** [ChatCompletionsRequest](#chatcompletionsrequest) -### 认证方式 +**响应：** -``` -Authorization: Bearer sk-xxxx -``` +| 状态码 | 描述 | +|--------|------| +| 200 | 成功 | +| 400 | 请求错误 | +| 401 | 未授权 | +| 403 | 禁止访问 | +| 429 | 限流 | +| 500 | 服务器错误 | +| 502 | 网关错误 | +| 503 | 服务不可用 | + +**返回类型：** +- `application/json` +- `text/event-stream` --- -## 返回结果 +## Schemas（数据结构） + +### ErrorResponse（错误响应） + +| 字段 | 类型 | 描述 | +|------|------|------| +| error | object | 错误信息 | +| error.message | string | 错误描述 | +| error.type | string | 错误类型 | +| error.param | string \| null | 相关参数 | +| error.code | string \| null | 错误代码 | -| 状态码 | 说明 | -|------|------| -| 200 | 返回模型列表 | -| 401 | 认证失败 | +--- + +### V1ModelsResponse + +| 字段 | 类型 | 示例 | 描述 | +|------|------|------|------| +| object | string | "list" | | +| success | boolean | true | | +| data | array | | 模型数组 | + +--- -返回结构： +### V1ModelItem -```json -{ - "object": "list", - "success": true, - "data": [ - { - "id": "gpt-4", - "object": "model", - "created": 1626777600, - "owned_by": "openai" - } - ] -} -``` +| 字段 | 类型 | 示例 | 描述 | +|------|------|------|------| +| id | string | "gpt-5.2" | | +| object | string | "model" | | +| created | integer | 1626777600 | | +| owned_by | string | "openai" | | --- -# 数据结构说明 +### ChatCompletionsRequest -## ChatChoice（生成结果） +**必填字段：** `model`, `messages` -| 字段 | 类型 | 说明 | -|----|----|----| -| content | string | AI 返回内容 | -| finish_reason | string | 结束原因，例如 `stop` | -| index | integer | 结果序号 | +| 字段 | 类型 | 描述 | +|------|------|------| +| model | string | 模型 ID | +| messages | array | 对话消息列表 | +| stream | boolean | 是否流式返回 | +| max_tokens | integer | 最大生成 token | +| temperature | number | 随机性（0-2） | +| top_p | number | 核采样 | +| stop | string \| array | 停止词 | +| n | integer | 返回数量 | +| frequency_penalty | number | 重复惩罚 | +| presence_penalty | number | 出现惩罚 | +| seed | integer | 随机种子 | +| response_format | object | 输出格式 | +| tools | array | 工具调用 | +| tool_choice | string \| object | 工具选择 | +| user | string | 用户标识 | +| web_search_options | object | Web 搜索配置 | + +--- + +### WebSearchOptions + +| 字段 | 类型 | 描述 | +|------|------|------| +| search_context_size | string | 上下文大小（low/medium/high） | +| user_location | object | 用户位置 | --- -## ChatMessage（对话消息） +### ChatMessage -| 字段 | 类型 | 说明 | -|----|----|----| +| 字段 | 类型 | 描述 | +|------|------|------| | role | string | system / user / assistant / tool | | content | string | 消息内容 | -| name | string | 可选用户名 | +| name | string | 可选 | | tool_call_id | string | 工具调用 ID | -| tool_calls | array | 工具调用信息 | +| tool_calls | array | 工具调用列表 | --- -## ChatCompletionsResponse（响应结构） +### ChatResponseFormat -| 字段 | 类型 | 说明 | -|----|----|----| -| id | string | 请求 ID | -| object | string | 类型 | -| created | integer | 时间戳 | -| model | string | 模型名称 | -| choices | array | 生成结果 | -| usage | object | Token 使用统计 | +| 字段 | 类型 | 描述 | +|------|------|------| +| type | string | text / json_object | +| json_schema | any | JSON Schema | --- -## Token 使用统计（Usage） +### ChatTool -| 字段 | 类型 | 说明 | -|----|----|----| -| prompt_tokens | integer | 输入 token | -| completion_tokens | integer | 输出 token | -| total_tokens | integer | 总 token | +| 字段 | 类型 | 描述 | +|------|------|------| +| type | string | function | +| function | object | 函数定义 | --- -## 工具调用（Function Calling） - -支持 OpenAI 标准工具调用： +### ChatToolFunction -### 工具定义 - -```json -{ - "type": "function", - "function": { - "name": "get_weather", - "description": "获取天气", - "parameters": {} - } -} -``` +| 字段 | 类型 | 描述 | +|------|------|------| +| name | string | 函数名 | +| description | string | 描述 | +| parameters | any | 参数 | --- -### 模型调用返回 +### ChatToolCallItem -```json -{ - "tool_calls": [ - { - "id": "call_xxx", - "type": "function", - "function": { - "name": "get_weather", - "arguments": "{ \"city\": \"Beijing\" }" - } - } - ] -} -``` +| 字段 | 类型 | 描述 | +|------|------|------| +| id | string | 调用 ID | +| type | string | function | +| function | object | 调用函数 | --- -# 总结 +### ChatCompletionsResponse -- 完全兼容 OpenAI API -- 支持流式输出 -- 支持工具调用（Function Calling） -- 支持多模型统一接入 +| 字段 | 类型 | 描述 | +|------|------|------| +| id | string | 请求 ID | +| object | string | 类型 | +| created | integer | 时间戳 | +| model | string | 模型 | +| choices | array | 返回结果 | +| usage | object | Token 使用情况 | -只需将 Base URL 替换为： +--- -``` -https://api.bankofai.io/v1 -``` +### ChatUsage -即可快速接入 Bank of AI 🚀 +| 字段 | 类型 | 描述 | +|------|------|------| +| prompt_tokens | integer | 输入 token | +| completion_tokens | integer | 输出 token | +| total_tokens | integer | 总 token | +| prompt_tokens_details | object | 输入详情 | +| completion_tokens_details | object | 输出详情 | From 1594cb799ab4b63a76d1e9952ad6a529ed46a3b2 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Tue, 31 Mar 2026 14:24:04 +0800 Subject: [PATCH 5/5] update version --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 6a20518a..a26951ad 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@x402-tron/docs", - "version": "1.2.5", + "version": "1.2.6", "description": "x402-tron documentation", "license": "MIT", "scripts": {