> 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/ja/api-reference/ai-gateway.md).

# AI Gateway

AI Gateway は OpenAI 互換のエンドポイントを提供します。既存の OpenAI SDK やツールで URL と API キーを変更するだけで、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
    }
  ]
}
```

**ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**

***

### チャット補完（ストリーミングとツール呼び出しに対応） <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` など）と同じです。プラットフォームのスキーマにはこれらのフィールドを記載していません。パラメータと使用例については、技術マニュアルの[チャット補完パラメータ](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                                                      | はい  | GET /v1/models から取得するモデル ID です                                                                  |
| 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 // GET /v1/models から取得するモデル ID です
  "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"?: { // total_tokens は課金に使用されるトークン総数（入力＋出力＋prompt cache の書き込み＋読み取り）です (任意)
  {
    "prompt_tokens"?: integer // 入力トークンの総数。prompt cache の読み取り（cached_tokens）と書き込み（cache_write_tokens）を含みます (任意)
    "completion_tokens"?: integer // 任意
    "total_tokens"?: integer // prompt_tokens + completion_tokens (任意)
    "prompt_tokens_details"?: { // 任意
    {
      "cached_tokens"?: integer // prompt_tokens のうち、prompt cache の読み取り価格で課金される量。cache の読み取りを通常の入力として課金するモデル（Vertex Gemini など）ではこの値は 0 です (任意)
      "cache_write_tokens"?: integer // prompt_tokens のうち、prompt cache に書き込まれた量 (任意)
    }
    }
  }
  }
}
```

**レスポンスの値の例**

```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": "レスポンスの説明例"
  }
}
```

**ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**

***

### テキストの埋め込み生成 <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 の場合はリトルエンディアンの 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": "レスポンスの説明例"
  }
}
```

**ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**

***

### 音声からテキストへ <a href="#audio-transcriptions-create" id="audio-transcriptions-create"></a>

POST `/api/v1/audio/transcriptions`

{% hint style="info" %}
音声ファイル全体をアップロードして文字起こしを取得します（同期呼び出しで、ストリーミングには対応していません）。リクエスト本文は `multipart/form-data` です。`file` は必須で、音声ファイルを指定します。上限は 25 MB で、形式はファイル名の拡張子で判断され、`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm` を受け付けます。`model` は必須で、`type` が `transcription` のモデル（例：`openai/gpt-transcribe`、`azure/speech-to-text`）を指定します。`language` は任意で、例えば `zh` を指定します。省略した場合はモデルが自動判定します。`response_format` は任意で、`json`（デフォルト）または `text` を指定します。`text` の場合、レスポンスは JSON ではなく `text/plain` の文字起こしになります。`language` のルールと、一部のモデルのみ対応、または単一の値のみ受け付けるフィールド（`prompt`、`temperature`、`stream`）については、技術マニュアルの[音声からテキストへ](https://docs.maiagent.ai/tech/api-integration/ai-gateway-openai-compatible#audio-transcriptions)をご覧ください。料金はプロバイダーが報告する音声の長さに基づいて秒単位で課金され、整数秒に切り上げられ、最低 1 秒です。詳しくは[利用量と Credits の課金](https://docs.maiagent.ai/tech/api-integration/ai-gateway-openai-compatible#billing)をご覧ください。モデルの許可リストを設定した API Key では音声モデルを利用できず（`404 model_not_found` を返します）、文字数課金プランの組織も利用できません（`403` を返します）。詳しくは[利用可能な音声モデル](https://docs.maiagent.ai/tech/api-integration/ai-gateway-openai-compatible#audio-models)をご覧ください。タイムアウト、エラー、ポイントが差し引かれないケースについては、[音声エンドポイントの共通動作](https://docs.maiagent.ai/tech/api-integration/ai-gateway-openai-compatible#audio-behavior)をご覧ください。
{% endhint %}

#### コード例

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

```bash
# API 呼び出しの例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/audio/transcriptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@example_file.mp3" \
  -F "model=openai/gpt-transcribe" \
  -F "language=zh" \
  -F "response_format=json"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');
const FormData = require('form-data');

// FormData オブジェクトを作成
const formData = new FormData();
// 実際のファイルに置き換えてください
formData.append('file', /* 実際のファイルオブジェクト */, 'example_file.mp3');
formData.append('model', 'openai/gpt-transcribe');
formData.append('language', 'zh');
formData.append('response_format', 'json');

// リクエストヘッダーを設定
const config = {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    ...formData.getHeaders()
  }
};

axios.post("https://api.maiagent.ai/api/v1/audio/transcriptions", formData, 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/audio/transcriptions"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

# ファイルとフォームデータを作成
files = {
    'file': ('example_file.mp3', open('example_file.mp3', 'rb'), 'audio/mpeg'),
    'model': (None, 'openai/gpt-transcribe'),
    'language': (None, 'zh'),
    'response_format': (None, 'json')
}

response = requests.post(url, files=files, 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/audio/transcriptions", [
        'headers' => [
            'Authorization' => 'Bearer YOUR_API_KEY'
        ],
        'multipart' => [
            [
                'name' => 'file',
                'contents' => fopen('example_file.mp3', 'r'),
                'filename' => 'example_file.mp3'
            ],
            [
                'name' => 'model',
                'contents' => 'openai/gpt-transcribe'
            ],
            [
                'name' => 'language',
                'contents' => 'zh'
            ],
            [
                'name' => 'response_format',
                'contents' => 'json'
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンス

**ステータスコード: 200 - 成功。response\_format が json（デフォルト）の場合は JSON を返し、usage.seconds は今回課金された秒数です。text の場合は text/plain; charset=utf-8 を返し、本文がそのまま文字起こしになります**

**レスポンススキーマの例**

```typescript
{
  "text"?: string // 文字起こし (任意)
  "usage"?: { // 任意
  {
    "type"?: string (enum: duration) // 任意
    "seconds"?: integer // 課金秒数。整数秒に切り上げ、最低 1 秒 (任意)
  }
  }
}
```

**レスポンスの例**

```json
{
  "text": "文字起こしの内容",
  "usage": {
    "type": "duration",
    "seconds": 6
  }
}
```

**ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**

***

### テキストから音声へ <a href="#audio-speech-create" id="audio-speech-create"></a>

POST `/api/v1/audio/speech`

{% hint style="info" %}
テキストを送信して完全な音声ファイルを取得します（同期呼び出しで、ストリーミングには対応していません）。リクエスト本文は JSON です。`model` は必須で、`type` が `speech` のモデル（例：`openai/gpt-4o-mini-tts`）を指定します。`input` は必須で、空にはできず、上限は 4,096 文字です。`voice` は必須で、そのモデルが `GET /api/v1/models` で一覧表示している `voices`（例：`alloy`）のいずれかを指定します。`response_format` は任意で、`mp3` または `wav` を指定します。省略した場合は、そのモデルの最初の形式が使用されます。`speed` は任意で、現在の OpenAI モデルでは `0.25`〜`4.0` です。一部のモデルのみ対応する `instructions` と、`audio` のみ受け付ける `stream_format` については、技術マニュアルの[テキストから音声へ](https://docs.maiagent.ai/tech/api-integration/ai-gateway-openai-compatible#audio-speech)をご覧ください。レスポンス本文は音声ファイルそのもの（`audio/mpeg` または `audio/wav`）で、JSON ではありません。サンプルコードではこれをファイルとして保存します。料金は `input` の文字数に基づき 1,000 文字単位で課金されます。詳しくは[利用量と Credits の課金](https://docs.maiagent.ai/tech/api-integration/ai-gateway-openai-compatible#billing)をご覧ください。キーの許可リストと文字数課金プランの制限は、音声からテキストへの場合と同じです。詳しくは[利用可能な音声モデル](https://docs.maiagent.ai/tech/api-integration/ai-gateway-openai-compatible#audio-models)をご覧ください。タイムアウトとエラーについては[音声エンドポイントの共通動作](https://docs.maiagent.ai/tech/api-integration/ai-gateway-openai-compatible#audio-behavior)、呼び出し上限については[制限](https://docs.maiagent.ai/tech/api-integration/ai-gateway-openai-compatible#limits)をご覧ください。
{% endhint %}

#### リクエスト本文

**リクエストパラメータ**

| フィールド            | 型                       | 必須  | 説明                                                             |
| ---------------- | ----------------------- | --- | -------------------------------------------------------------- |
| model            | string                  | はい  | type が speech のモデルの識別子                                         |
| input            | string                  | はい  | 合成するテキスト。空にはできず、上限は 4,096 文字                                   |
| voice            | string                  | はい  | そのモデルの voices に含まれる音声である必要があります                                |
| response\_format | string (enum: mp3, wav) | いいえ | そのモデルの response\_formats に含まれる形式である必要があります。省略した場合は最初の形式が使用されます |
| speed            | number                  | いいえ | 読み上げ速度。現在の OpenAI モデルでは 0.25〜4.0                               |

**リクエストスキーマの例**

```typescript
{
  "model": string // type が speech のモデルの識別子
  "input": string // 合成するテキスト。空にはできず、上限は 4,096 文字
  "voice": string // そのモデルの voices に含まれる音声である必要があります
  "response_format"?: string (enum: mp3, wav) // そのモデルの response_formats に含まれる形式である必要があります。省略した場合は最初の形式が使用されます (任意)
  "speed"?: number // 読み上げ速度。現在の OpenAI モデルでは 0.25〜4.0 (任意)
}
```

**リクエストの例**

```json
{
  "model": "openai/gpt-4o-mini-tts",
  "input": "MaiAgent へようこそ。",
  "voice": "alloy",
  "response_format": "mp3"
}
```

#### コード例

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

```bash
# API 呼び出しの例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/audio/speech" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini-tts",
    "input": "MaiAgent へようこそ。",
    "voice": "alloy",
    "response_format": "mp3"
  }' \
  -o speech.mp3

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

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

// リクエストヘッダーを設定
const config = {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  responseType: 'arraybuffer' // レスポンス本文は音声ファイルのため、バイナリで受け取ります
};

// リクエストペイロード
const data = {
    "model": "openai/gpt-4o-mini-tts",
    "input": "MaiAgent へようこそ。",
    "voice": "alloy",
    "response_format": "mp3"
  };

axios.post("https://api.maiagent.ai/api/v1/audio/speech", data, config)
  .then(response => {
    fs.writeFileSync('speech.mp3', response.data);
    console.log('speech.mp3 に保存しました');
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response ? Buffer.from(error.response.data).toString('utf8') : error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

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

# リクエストペイロード
data = {
    "model": "openai/gpt-4o-mini-tts",
    "input": "MaiAgent へようこそ。",
    "voice": "alloy",
    "response_format": "mp3"
}

response = requests.post(url, json=data, headers=headers)
try:
    response.raise_for_status()
    # レスポンス本文は音声ファイルのため、そのままファイルに書き込みます
    with open('speech.mp3', 'wb') as f:
        f.write(response.content)
    print("speech.mp3 に保存しました")
except requests.HTTPError as e:
    print("リクエストでエラーが発生しました:", e, response.text)
```

{% endtab %}

{% tab title="PHP" %}

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/audio/speech", [
        'headers' => [
            'Authorization' => 'Bearer YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'model' => 'openai/gpt-4o-mini-tts',
            'input' => 'MaiAgent へようこそ。',
            'voice' => 'alloy',
            'response_format' => 'mp3'
        ]
    ]);
    
    // レスポンス本文は音声ファイルのため、そのままファイルに書き込みます
    file_put_contents('speech.mp3', $response->getBody());
    echo "speech.mp3 に保存しました\n";
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンス

| ステータスコード | 説明                                                                                     |
| -------- | -------------------------------------------------------------------------------------- |
| 200      | 成功。レスポンス本文は完全な音声ファイル（JSON ではありません）で、Content-Type は audio/mpeg（mp3）または audio/wav（wav）です |
| 4XX      | Error response; X-Error-Code carries its code (see "Error codes").                     |

***


---

# 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/ja/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.
