> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/api/api-reference/ai-gateway.md).

# AI Gateway

AI Gateway 提供與 OpenAI 相容的端點，讓既有的 OpenAI SDK 或工具只改網址與金鑰就能透過 MaiAgent 呼叫模型。這組端點只在 `/api/v1/` 底下、路徑不以 `/` 結尾；認證用 `Authorization: Bearer <API Key>`（金鑰就是 MaiAgent 的 API Key，但 Gateway 端點只認 `Bearer` 前綴，`Api-Key` 前綴會回 `401`）。AI Gateway 需由 MaiAgent 為組織開通，金鑰可呼叫的模型由管理者在 API Key 管理設定。完整說明見技術手冊 [AI Gateway：OpenAI 相容 API 串接](https://docs.maiagent.ai/tech/api-integration/ai-gateway-openai-compatible)。

### 列出可用模型 <a href="#models-retrieve" id="models-retrieve"></a>

GET `/api/v1/models`

{% hint style="info" %}
回傳這把金鑰可呼叫的模型識別碼與定價，識別碼的規則見技術手冊[模型識別](https://docs.maiagent.ai/tech/api-integration/ai-gateway-openai-compatible#model-ids)。
{% endhint %}

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/models", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/models"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/models", [
        'headers' => [
            'Authorization' => 'Bearer YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "object"?: string (enum: list) // 非必填
  "data"?: [ // 非必填
    {
      "id"?: string // 呼叫時填入 model 的 id (非必填)
      "object"?: string (enum: model) // 非必填
      "created"?: integer // Unix 秒 (非必填)
      "owned_by"?: string // 非必填
      "name"?: string // 非必填
      "icon"?: string // 非必填
      "type"?: string (enum: language) // 非必填
      "tags"?: [ // 非必填
        string (enum: tool-use, multimodal, reasoning, prompt-caching, streaming)
      ]
      "pricing"?: { // 平台模型為 input／output／unit=credits_per_1k_tokens／currency；組織自有模型為 traffic_fee_percent／unit=percent_of_total_tokens／currency (非必填)
      {
        "input"?: string // 非必填
        "output"?: string // 非必填
        "traffic_fee_percent"?: string // 非必填
        "unit"?: string // 非必填
        "currency"?: string // 非必填
      }
      }
      "providers"?: [ // 非必填
        {
          "slug"?: string // 非必填
          "name"?: string // 非必填
          "icon_url"?: string // 非必填
          "color"?: string // 非必填
        }
      ]
      "context_window"?: integer // 模型有設定時才出現 (非必填)
      "max_tokens"?: integer // 模型有設定時才出現 (非必填)
    }
  ]
}
```

**回應範例值**

```json
{
  "object": "list",
  "data": [
    {
      "id": "回應字串",
      "object": "model",
      "created": 456,
      "owned_by": "回應字串",
      "name": "回應字串",
      "icon": "回應字串",
      "type": "language",
      "tags": [
        "tool-use"
      ],
      "pricing": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應範例名稱",
        "description": "回應範例描述"
      },
      "providers": [
        {
          "slug": "回應字串",
          "name": "回應字串",
          "icon_url": "回應字串",
          "color": "回應字串"
        }
      ],
      "context_window": 456,
      "max_tokens": 456
    }
  ]
}
```

***

### 對話補全（支援串流與工具呼叫） <a href="#chat-completions-create" id="chat-completions-create"></a>

POST `/api/v1/chat/completions`

{% hint style="info" %}
請求與回應格式同 OpenAI `chat/completions`（`model`、`messages`、`stream`、`tools` 等），平台 schema 未列欄位；參數與範例見技術手冊[對話補全參數](https://docs.maiagent.ai/tech/api-integration/ai-gateway-openai-compatible#chat-completions-params)與[最小範例](https://docs.maiagent.ai/tech/api-integration/ai-gateway-openai-compatible#minimal-examples)。
{% endhint %}

#### 請求內容

**請求參數**

| 欄位                             | 類型                                                          | 必填 | 說明                                                                       |
| ------------------------------ | ----------------------------------------------------------- | -- | ------------------------------------------------------------------------ |
| model                          | string                                                      | 是  | 模型 id，取自 GET /v1/models                                                  |
| messages                       | array\[object]                                              | 是  |                                                                          |
| stream                         | boolean                                                     | 否  | true 時以 text/event-stream 回傳                                             |
| stream\_options                | object                                                      | 否  |                                                                          |
| stream\_options.include\_usage | boolean                                                     | 否  |                                                                          |
| temperature                    | number                                                      | 否  |                                                                          |
| max\_tokens                    | integer                                                     | 否  |                                                                          |
| top\_p                         | number                                                      | 否  |                                                                          |
| stop                           | object                                                      | 否  |                                                                          |
| n                              | integer                                                     | 否  |                                                                          |
| provider                       | object                                                      | 否  |                                                                          |
| provider.order                 | array\[string]                                              | 否  | 指定後端供應商；目前只採用第一個                                                         |
| tools                          | array\[object]                                              | 否  |                                                                          |
| tool\_choice                   | object                                                      | 否  |                                                                          |
| parallel\_tool\_calls          | boolean                                                     | 否  |                                                                          |
| response\_format               | object                                                      | 否  | type 為 text、json\_object 或 json\_schema；json\_schema 時需帶 json\_schema 物件 |
| reasoning\_effort              | string (enum: none, minimal, low, medium, high, xhigh, max) | 否  |                                                                          |

**請求結構範例**

```typescript
{
  "model": string // 模型 id，取自 GET /v1/models
  "messages": [
    {
      "role": string (enum: system, user, assistant, tool)
      "content": object // 文字，或 OpenAI 多模態 content parts 陣列
      "tool_calls"?: [ // 非必填
        {
          "id"?: string // 非必填
          "type"?: string (enum: function) // 非必填
          "function"?: { // 非必填
          {
            "name"?: string // 非必填
            "arguments"?: string // JSON 字串 (非必填)
          }
          }
        }
      ]
      "tool_call_id"?: string // 非必填
      "name"?: string // 非必填
    }
  ]
  "stream"?: boolean // true 時以 text/event-stream 回傳 (非必填)
  "stream_options"?: { // 非必填
  {
    "include_usage"?: boolean // 非必填
  }
  }
  "temperature"?: number // 非必填
  "max_tokens"?: integer // 非必填
  "top_p"?: number // 非必填
  "stop"?: // 可能有不同的類型 (非必填)
  string // 非必填
  "n"?: integer // 非必填
  "provider"?: { // 非必填
  {
    "order"?: [ // 指定後端供應商；目前只採用第一個 (非必填)
      string
    ]
  }
  }
  "tools"?: [ // 非必填
    {
      "type": string (enum: function)
      "function": {
      {
        "name": string
        "description"?: string // 非必填
        "parameters"?: object // JSON Schema (非必填)
        "strict"?: boolean // 非必填
      }
      }
    }
  ]
  "tool_choice"?: // 可能有不同的類型 (非必填)
  string (enum: auto, none, required) // 非必填
  "parallel_tool_calls"?: boolean // 非必填
  "response_format"?: object // type 為 text、json_object 或 json_schema；json_schema 時需帶 json_schema 物件 (非必填)
  "reasoning_effort"?: string (enum: none, minimal, low, medium, high, xhigh, max) // 非必填
}
```

**請求範例值**

```json
{
  "model": "openai/gpt-5.4-mini",
  "messages": [
    {
      "role": "user",
      "content": "你好，請用一句話介紹你自己。"
    }
  ]
}
```

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "messages": [
      {
        "role": "user",
        "content": "你好，請用一句話介紹你自己。"
      }
    ]
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "model": "openai/gpt-5.4-mini",
    "messages": [
      {
        "role": "user",
        "content": "你好，請用一句話介紹你自己。"
      }
    ]
  };

axios.post("https://api.maiagent.ai/api/v1/chat/completions", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/chat/completions"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "model": "openai/gpt-5.4-mini",
    "messages": [
        {
            "role": "user",
            "content": "你好，請用一句話介紹你自己。"
        }
    ]
}

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/chat/completions", [
        'headers' => [
            'Authorization' => 'Bearer YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'model' => 'openai/gpt-5.4-mini',
            'messages' => [
                [
                    'role' => 'user',
                    'content' => '你好，請用一句話介紹你自己。'
                ]
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200 - stream=false 時回 chat.completion 物件；stream=true 時回 SSE**

**回應結構範例**

```typescript
{
  "id"?: string // 非必填
  "object"?: string (enum: chat.completion) // 非必填
  "created"?: integer // Unix 秒 (非必填)
  "model"?: string // 非必填
  "choices"?: [ // 非必填
    {
      "index"?: integer // 非必填
      "message"?: { // 非必填
      {
        "role"?: string (enum: assistant) // 非必填
        "content"?: string // 非必填
        "tool_calls"?: [ // 非必填
          {
            "id"?: string // 非必填
            "type"?: string (enum: function) // 非必填
            "function"?: { // 非必填
            {
              "name"?: string // 非必填
              "arguments"?: string // JSON 字串 (非必填)
            }
            }
          }
        ]
      }
      }
      "finish_reason"?: string // 非必填
    }
  ]
  "usage"?: { // 非必填
  {
    "prompt_tokens"?: integer // 非必填
    "completion_tokens"?: integer // 非必填
    "total_tokens"?: integer // 非必填
  }
  }
}
```

**回應範例值**

```json
{
  "id": "回應字串",
  "object": "chat.completion",
  "created": 456,
  "model": "回應字串",
  "choices": [
    {
      "index": 456,
      "message": {
        "id": "msg_550e8400e29b41d4a716446655440000",
        "content": "這是回應的訊息內容",
        "timestamp": "2025-01-01T00:00:00.000Z"
      },
      "finish_reason": "回應字串"
    }
  ],
  "usage": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  }
}
```

***

### 產生文字向量 <a href="#embeddings-create" id="embeddings-create"></a>

POST `/api/v1/embeddings`

{% hint style="info" %}
請求與回應格式同 OpenAI `embeddings`（`model`、`input`），範例見技術手冊[向量化](https://docs.maiagent.ai/tech/api-integration/ai-gateway-openai-compatible#embeddings)。
{% endhint %}

#### 請求內容

**請求參數**

| 欄位               | 類型                           | 必填 | 說明          |
| ---------------- | ---------------------------- | -- | ----------- |
| model            | string                       | 是  |             |
| input            | object                       | 是  | 非空字串或非空字串陣列 |
| encoding\_format | string (enum: float, base64) | 否  |             |
| dimensions       | integer                      | 否  |             |
| user             | string                       | 否  |             |

**請求結構範例**

```typescript
{
  "model": string
  "input": // 可能有不同的類型
  string // 非空字串或非空字串陣列
  "encoding_format"?: string (enum: float, base64) // 非必填
  "dimensions"?: integer // 非必填
  "user"?: string // 非必填
}
```

**請求範例值**

```json
{
  "model": "text-embedding-3-large",
  "input": "今天天氣很好"
}
```

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/embeddings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-large",
    "input": "今天天氣很好"
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "model": "text-embedding-3-large",
    "input": "今天天氣很好"
  };

axios.post("https://api.maiagent.ai/api/v1/embeddings", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/embeddings"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "model": "text-embedding-3-large",
    "input": "今天天氣很好"
}

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/embeddings", [
        'headers' => [
            'Authorization' => 'Bearer YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'model' => 'text-embedding-3-large',
            'input' => '今天天氣很好'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "object"?: string (enum: list) // 非必填
  "data"?: [ // 非必填
    {
      "object"?: string (enum: embedding) // 非必填
      "index"?: integer // 非必填
      "embedding"?: // 可能有不同的類型 (非必填)
      array[number] // encoding_format=float 為數字陣列；base64 為 little-endian float32 的 base64 字串 (非必填)
    }
  ]
  "model"?: string // 非必填
  "usage"?: { // 非必填
  {
    "prompt_tokens"?: integer // 非必填
    "total_tokens"?: integer // 非必填
  }
  }
}
```

**回應範例值**

```json
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 456,
      "embedding": [
        456
      ]
    }
  ],
  "model": "回應字串",
  "usage": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  }
}
```

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/api/api-reference/ai-gateway.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.