### Development Setup Commands

Source: https://github.com/tiarabasori/opencode2api/blob/main/CONTRIBUTING.md

Commands to clone the repository, install dependencies, and start the project locally.

```bash
# Clone and install
git clone https://github.com/TiaraBasori/opencode2api.git
cd opencode2api
npm install

# Run tests
npm test

# Start locally
npm start
```

--------------------------------

### API Authentication Examples

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

Examples of how to authenticate API requests using a Bearer Token. The first example shows a request with authentication, while the second is for when no API key is configured.

```bash
# 带认证
curl -H "Authorization: Bearer YOUR_API_KEY" ...
```

```bash
# 不带认证 (未配置 API_KEY 时)
curl ...
```

--------------------------------

### Responses API Request Example

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

Example cURL command to send a request to the Responses API. This example uses 'input' and enables streaming.

```bash
curl -N -X POST http://127.0.0.1:10000/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "opencode/big-pickle",
    "input": "打招呼",
    "reasoning": {"effort": "high"},
    "stream": true
  }'
```

--------------------------------

### List Models Response Example

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

Example JSON response from the /v1/models endpoint, showing a list containing one model.

```json
{
  "object": "list",
  "data": [
    {
      "id": "opencode/big-pickle",
      "object": "model",
      "created": 1704067200,
      "owned_by": "opencode"
    }
  ]
}
```

--------------------------------

### Chat Completions Request Example

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

Example cURL command to send a chat completion request. It includes the model, messages, and specifies no streaming.

```bash
curl -X POST http://127.0.0.1:10000/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "opencode/big-pickle",
    "messages": [{"role": "user", "content": "你好!"}],
    "stream": false
  }'
```

--------------------------------

### Chat Completions with External Tool Example

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

Example cURL command for chat completions that includes an external tool definition for fetching web content. The model can then use this tool to fulfill the request.

```bash
curl -X POST http://127.0.0.1:10000/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "opencode/big-pickle",
    "messages": [
      {"role": "user", "content": "读取 https://example.com 并告诉我标题"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "web_fetch",
          "description": "Fetch a web page and summarize it",
          "parameters": {
            "type": "object",
            "properties": {
              "url": {"type": "string"}
            },
            "required": ["url"]
          }
        }
      }
    ]  }'
```

--------------------------------

### Conventional Commits Example

Source: https://github.com/tiarabasori/opencode2api/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification for different types of changes.

```text
feat(api): add streaming support for Responses API
fix(proxy): resolve memory leak in long-running sessions
docs: update configuration documentation
```

--------------------------------

### Health Check Response Example

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

Example JSON response from the /health endpoint, indicating the service is operational.

```json
{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

--------------------------------

### Responses API with External Tool Example

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

Example cURL command for the Responses API that includes an external tool definition for weather lookups. This allows the model to fetch real-time weather information.

```bash
curl -X POST http://127.0.0.1:10000/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "opencode/big-pickle",
    "input": "东京现在天气怎么样？",
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "weather_lookup",
          "description": "Look up weather by city",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {"type": "string"},
              "unit": {"type": "string"}
            },
            "required": ["city"]
          }
        }
      }
    ]  }'
```

--------------------------------

### Recommended First-Turn Prompt for Tool Use (English)

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

This prompt is recommended for the first turn when you want the model to reliably output a tool call. It explicitly instructs the model to call a tool and not to answer directly.

```text
Call weather_lookup for Tokyo now. Do not answer directly.
```

--------------------------------

### 复制 Docker 配置文件

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/getting-started.md

复制示例 .env 文件以创建用于 Docker 部署的实际配置文件。

```bash
cp .env.example .env
```

--------------------------------

### Recommended First-Turn Prompt for Tool Use (Chinese)

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

This prompt is recommended for the first turn when you want the model to reliably output a tool call. It explicitly instructs the model to call a tool and not to answer directly.

```text
现在调用 weather_lookup 查询 Tokyo。不要直接回答。
```

--------------------------------

### 进入项目目录

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/getting-started.md

导航到已克隆的 opencode2api 项目目录。

```bash
cd opencode2api
```

--------------------------------

### Recommended Second-Turn Prompt for Tool Use (Chinese)

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

After receiving a tool call, use this prompt to instruct the model to use the tool's result to answer the original request. This is part of a recommended two-step process for stable tool integration.

```text
很好，现在基于工具结果回答原始问题。
```

--------------------------------

### Recommended Second-Turn Prompt for Tool Use

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

After receiving a tool call, use this prompt to instruct the model to use the tool's result to answer the original request. This is part of a recommended two-step process for stable tool integration.

```text
Great, now answer the original request using the tool result.
```

--------------------------------

### 复制本地 Node.js 配置文件

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/getting-started.md

复制示例 config.json 文件以创建用于本地 Node.js 部署的实际配置文件。

```bash
cp config.json.example config.json
```

--------------------------------

### 启动 Docker 服务

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/getting-started.md

使用 Docker Compose 在后台启动 opencode2api 服务。

```bash
docker compose up -d
```

--------------------------------

### 克隆项目

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/getting-started.md

使用 Git 克隆 opencode2api 项目仓库。

```bash
git clone https://github.com/TiaraBasori/opencode2api.git
```

--------------------------------

### 获取模型列表

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/getting-started.md

通过向 /v1/models 端点发送请求来检索可用模型列表。需要提供 API 密钥。

```bash
# 获取模型列表
curl -H "Authorization: Bearer $API_KEY" http://127.0.0.1:10000/v1/models
```

--------------------------------

### 启动本地 Node.js 服务

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/getting-started.md

启动本地 Node.js 环境中的 opencode2api 服务。

```bash
npm start
```

--------------------------------

### Streaming Tool Call with cURL

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

Demonstrates how to make a streaming tool call to the API using cURL. Ensure to replace YOUR_API_KEY with your actual API key.

```bash
curl -N -X POST http://127.0.0.1:10000/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "opencode/big-pickle",
    "input": "查询东京天气",
    "stream": true,
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "weather_lookup",
          "description": "Look up weather by city",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {"type": "string"}
            },
            "required": ["city"]
          }
        }
      }
    ]
  }'
```

--------------------------------

### 安装 opencode-ai CLI

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/getting-started.md

全局安装 opencode-ai 命令行界面工具。

```bash
npm install -g opencode-ai
```

--------------------------------

### 安装本地 Node.js 依赖

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/getting-started.md

在本地 Node.js 环境中安装项目依赖项。

```bash
npm install
```

--------------------------------

### 测试 Responses API (带推理)

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/getting-started.md

使用 cURL 向 /v1/responses 端点发送 POST 请求以测试响应生成功能，支持流式输出。需要 API 密钥、输入和推理参数。

```bash
curl -N -X POST http://127.0.0.1:10000/v1/responses \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt5-nano",
    "input": "Say hi in one sentence.",
    "reasoning": {"effort": "high"},
    "stream": true
  }'
```

--------------------------------

### List Models

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

Retrieves a list of available models.

```APIDOC
## GET /v1/models

### Description
Retrieves a list of available models that can be used for API requests.

### Method
GET

### Endpoint
/v1/models

### Response
#### Success Response (200)
- **object** (string) - The type of the returned object, usually "list".
- **data** (array) - An array of model objects.
  - **id** (string) - The unique identifier of the model.
  - **object** (string) - The type of the object, usually "model".
  - **created** (integer) - The timestamp when the model was created.
  - **owned_by** (string) - The owner of the model.

### Response Example
```json
{
  "object": "list",
  "data": [
    {
      "id": "opencode/big-pickle",
      "object": "model",
      "created": 1704067200,
      "owned_by": "opencode"
    }
  ]
}
```
```

--------------------------------

### 测试 Chat Completions API

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/getting-started.md

使用 cURL 向 /v1/chat/completions 端点发送 POST 请求以测试聊天完成功能。需要 API 密钥和 JSON 数据。

```bash
curl -X POST http://127.0.0.1:10000/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "opencode/big-pickle",
    "messages": [{"role": "user", "content": "hi"}],
    "stream": false
  }'
```

--------------------------------

### Streaming Tool Calls

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

This endpoint allows for streaming tool calls by sending a POST request to the /v1/responses endpoint. It supports specifying a model, input, and a list of tools to be used. When streaming is enabled, tool call arguments and output items are returned in chunks.

```APIDOC
## POST /v1/responses

### Description
Initiates a streaming tool call. This endpoint processes a request to a specified model, utilizing provided tools, and returns results in a streaming fashion.

### Method
POST

### Endpoint
http://127.0.0.1:10000/v1/responses

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Content-Type** (string) - Required - Must be `application/json`.

#### Request Body
- **model** (string) - Required - The model to use for the request (e.g., "opencode/big-pickle").
- **input** (string) - Required - The user's input query (e.g., "查询东京天气").
- **stream** (boolean) - Required - Set to `true` to enable streaming.
- **tools** (array) - Required - A list of tools to be used for the call. Each tool object should have:
  - **type** (string) - Must be `"function"`.
  - **function** (object) - Defines the function to be called:
    - **name** (string) - The name of the function (e.g., "weather_lookup").
    - **description** (string) - A description of what the function does.
    - **parameters** (object) - The JSON schema for the function's parameters:
      - **type** (string) - Must be `"object"`.
      - **properties** (object) - Defines the parameters of the function (e.g., `{"city": {"type": "string"}}`).
      - **required** (array) - A list of required parameter names (e.g., `["city"]`).

### Request Example
```json
{
  "model": "opencode/big-pickle",
  "input": "查询东京天气",
  "stream": true,
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "weather_lookup",
        "description": "Look up weather by city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string"}
          },
          "required": ["city"]
        }
      }
    }
  ]
}
```

### Response
When `stream` is enabled, responses are returned in chunks. Key events include:
- `delta.tool_calls` in `chat.completion.chunk`
- `response.output_item.added`, `response.function_call_arguments.delta`, `response.function_call_arguments.done`, `response.output_item.done` in Responses API.

#### Error Responses
- **401 Unauthorized**: Returned if the API key is invalid.
  ```json
  {
    "error": {
      "message": "Invalid API key",
      "type": "invalid_request_error",
      "code": "invalid_api_key"
    }
  }
  ```
- **404 Not Found**: Returned if the specified model is not found.
  ```json
  {
    "error": {
      "message": "Model not found",
      "type": "invalid_request_error",
      "code": "model_not_found"
    }
  }
  ```
- **500 Internal Server Error**: Returned for general server errors.
  ```json
  {
    "error": {
      "message": "Internal server error",
      "type": "server_error",
      "code": "internal_error"
    }
  }
  ```
```

--------------------------------

### List Models Endpoint

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

This endpoint retrieves a list of available models. The response includes model details such as ID, object type, creation timestamp, and owner.

```http
GET /v1/models
```

--------------------------------

### 健康检查服务

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/getting-started.md

通过发送 HTTP 请求到 /health 端点来检查服务是否正在运行。

```bash
# 健康检查
curl http://127.0.0.1:10000/health
```

--------------------------------

### Chat Completions

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

Generates chat completions based on provided messages and model.

```APIDOC
## POST /v1/chat/completions

### Description
Generates chat completions by sending messages to a specified model. Supports streaming and tool usage.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Request Body
- **model** (string) - Required - The ID of the model to use for generating completions.
- **messages** (array) - Required - An array of message objects representing the conversation history.
- **tools** (array) - Optional - An array of external tool definitions, following OpenAI-compatible function tools structure.
- **tool_choice** (string/object) - Optional - The tool selection strategy; will be processed according to agent bridge semantics.
- **stream** (boolean) - Optional - Whether to stream the output. Defaults to false.
- **temperature** (number) - Optional - Controls randomness. Lower values make output more focused and deterministic (0-2).
- **top_p** (number) - Optional - Controls diversity via nucleus sampling. Values closer to 1.0 are more diverse (0-1).
- **max_tokens** (number) - Optional - The maximum number of tokens to generate in the completion.
- **reasoning_effort** (string) - Optional - Specifies the intensity of reasoning.

### Request Example
```bash
curl -X POST http://127.0.0.1:10000/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d 
  {
    "model": "opencode/big-pickle",
    "messages": [{"role": "user", "content": "你好!"}],
    "stream": false
  }
```

### Request Example with Tools
```bash
curl -X POST http://127.0.0.1:10000/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d 
  {
    "model": "opencode/big-pickle",
    "messages": [
      {"role": "user", "content": "读取 https://example.com 并告诉我标题"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "web_fetch",
          "description": "Fetch a web page and summarize it",
          "parameters": {
            "type": "object",
            "properties": {
              "url": {"type": "string"}
            },
            "required": ["url"]
          }
        }
      }
    ]
  }
```

### Response
When the model decides to call a tool, non-streaming responses will return a standard `message.tool_calls` object. Streaming responses will return `delta.tool_calls` within `chat.completion.chunk` objects.
```

--------------------------------

### 404 Not Found Error Response

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

This JSON object indicates that the requested model was not found by the API.

```json
{
  "error": {
    "message": "Model not found",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}
```

--------------------------------

### Chat Completions Endpoint

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

This endpoint is used for chat-based interactions, allowing users to send messages and receive model responses. It supports various parameters like model selection, streaming, and temperature control.

```http
POST /v1/chat/completions
```

--------------------------------

### Responses API

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

Generates responses based on input, prompt, or messages, with support for tools and streaming.

```APIDOC
## POST /v1/responses

### Description
Generates responses using a specified model, accepting input text, a prompt, or a message array. Supports external tools and streaming output.

### Method
POST

### Endpoint
/v1/responses

### Parameters
#### Request Body
- **model** (string) - Required - The ID of the model to use.
- **input** (string) - Required* - The input text for the model.
- **prompt** (string) - Required* - The prompt to guide the model's response.
- **messages** (array) - Required* - An array of message objects representing the conversation.
- **tools** (array) - Optional - An array of external tool definitions, following OpenAI-compatible function tools structure.
- **stream** (boolean) - Optional - Whether to stream the output. Defaults to false.
- **reasoning_effort** (string) - Optional - Specifies the intensity of reasoning.

> * At least one of `input`, `prompt`, or `messages` must be provided.

### Request Example
```bash
curl -N -X POST http://127.0.0.1:10000/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d 
  {
    "model": "opencode/big-pickle",
    "input": "打招呼",
    "reasoning": {"effort": "high"},
    "stream": true
  }
```

### Request Example with Tools
```bash
curl -X POST http://127.0.0.1:10000/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d 
  {
    "model": "opencode/big-pickle",
    "input": "东京现在天气怎么样？",
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "weather_lookup",
          "description": "Look up weather by city",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {"type": "string"},
              "unit": {"type": "string"}
            },
            "required": ["city"]
          }
        }
      }
    ]
  }
```

### Response
Non-streaming `responses` will return a `response.output` item of type `function_call` when a tool is invoked. Streaming mode sends function_call lifecycle and parameter increment events.
```

--------------------------------

### Responses API Endpoint

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

This endpoint is used for generating responses based on various inputs like text, prompts, or message arrays. It supports streaming and external tools.

```http
POST /v1/responses
```

--------------------------------

### 401 Unauthorized Error Response

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

This JSON object represents an error response when the provided API key is invalid.

```json
{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}
```

--------------------------------

### Health Check

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

Checks the health status of the API.

```APIDOC
## GET /health

### Description
Checks the health status of the API.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The health status of the API, typically "ok".
- **timestamp** (string) - The timestamp when the health check was performed.

### Response Example
```json
{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```
```

--------------------------------

### Health Check Endpoint

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

This endpoint is used to check the health status of the API. It returns the current status and a timestamp.

```http
GET /health
```

--------------------------------

### 500 Internal Server Error Response

Source: https://github.com/tiarabasori/opencode2api/blob/main/docs/api-reference.md

This JSON object represents a generic internal server error that occurred during the API request.

```json
{
  "error": {
    "message": "Internal server error",
    "type": "server_error",
    "code": "internal_error"
  }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.