> ## Documentation Index > Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt > Use this file to discover all available pages before exploring further. # OpenAI 互換の AI Gateway (ベータ) > OpenAI 互換の POST /v2/ai/chat/completions で、Square Cloud がホストする cubic モデルを自社プロダクトから利用できます。ツール呼び出しと Web 検索に対応しています。 アカウントの API キーです。これは[アカウント設定](https://squarecloud.app/ja/account/security)で確認できます。 `ai:chat` [スコープ](/ja/api-reference/authentication#スコープ)を持つ API キーが必要です。 AI Gateway を使うと、Square Cloud がホストする AI モデルを、**自社の**プロダクト (チャットボット、アシスタント、自動化) の中で **OpenAI 互換**のチャット補完エンドポイントから利用できます。すでに OpenAI API を使うコードであれば、そのまま AI Gateway でも動きます。SDK のベース URL を Square Cloud に向け、アカウントの API キーを使い、モデルに `cubic` を指定してください。 AI Gateway は**無料の先行アクセス付きのベータ版**です。ベータ期間中は、プランの 1 日あたりの AI トークン枠を超える追加料金はかかりません。ベータ終了時に、制限や利用できるプランが変更される場合があります。 ## 接続方法 * **ベース URL:** `https://api.squarecloud.app/v2/ai` * **API キー:** アカウントの API キー ([アカウントページ](https://squarecloud.app/ja/account)で取得する、Square Cloud API や CLI と同じもの)。`Authorization` ヘッダーは `Bearer ` プレフィックスの有無を問わず受け付けます。 * **モデル:** `cubic`。Square Cloud がホストするモデルで、ダッシュボードの AI アシスタントと同じものです。 ## プランと制限 すべてのリクエストは、実際に使用したトークン分がプランの **1 日あたりの AI トークン枠**から差し引かれます (ダッシュボードのアシスタントと同じ枠で、00:00 UTC にリセットされます)。Standard と Pro には 1 日あたりのリクエスト上限もあり、さらにすべてのプランに、適度な利用を想定したゲートウェイの 1 日あたりのフェアユース枠があります (放置されたキーへの安全策で、リクエストの処理コストに基づきます)。どちらも同じ時刻にリセットされます。 | プラン | 1 日あたりのリクエスト数 | フェアユース枠 | コンテキストウィンドウ | 最大出力 | 同時リクエスト数 | リクエスト間隔 | | - | - | - | - | - | - | - | | Standard | 1,000 | 基本 | 16,384 トークン | 4,096 | 1 | 5 秒 | | Pro | 5,000 | 基本 | 24,576 トークン | 6,144 | 1 | 2 秒 | | Enterprise | 無制限 | 基本の 5 倍 | 32,768 トークン | 8,192 | 2 | なし | Hobby プラン (およびプランのないアカウント) は AI Gateway を利用できません。Standard 以上にアップグレードすると利用できるようになります。 ## リクエストの仕様 SDK との互換性のために受け付けます。ゲートウェイは常に `cubic` として応答します。 OpenAI 形式のメッセージで、ロールは `system`、`user`、`assistant`、`tool` です。内容は**文字列**である必要があります。このエンドポイントはテキスト専用のため、マルチパートの配列 (`image_url`、`input_audio`、`file`) は `400 multimodal_not_supported` で拒否されます。1 回のリクエストあたり最大 **100 メッセージ**です。 プランの出力上限に合わせて自動的に切り詰められます。 0 から 2 まで。 標準的な OpenAI 形式の関数呼び出しで、最大 **32 個のツール定義**を指定できます。ツール呼び出しは `finish_reason: "tool_calls"` として返され、結果は `role: "tool"` のメッセージで送り返します。 標準的な OpenAI の `tool_choice` の値です。 未知のパラメーターは無視されますが、意図的な例外が 2 つあります。`audio` と、`["text"]` 以外の `modalities` の値は、無視されるのではなく**拒否されます**。そのため、音声出力を求めたリクエストが無音のテキストとして返ってくることはありません。 **テキストを送り、テキストを受け取ります。** 画像、音声、ファイルはどのプランでも受け付けません。これは一時的な制約ではなく、プロダクトとしての判断です。テキストを送信し、テキストを受け取ってください。 **未対応の機能:** ストリーミング (`stream: true` は `400 stream_not_supported` を返します)。 ### 組み込みの Web 検索 会話が最新の情報や外部の情報を必要とする場合、モデルは自ら判断して Web を検索します。検索はサーバー側で実行され、返されるのは結果の URL を引用した最終的な回答だけです。`web_search` という名前のツールを自分で宣言すると、組み込みのものの代わりにそのツールが使われます。 ```javascript JavaScript (OpenAI SDK) theme={"system"} import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.squarecloud.app/v2/ai", apiKey: process.env.SQUARECLOUD_API_KEY, }); const completion = await client.chat.completions.create({ model: "cubic", messages: [ { role: "system", content: "You are a helpful assistant." }, { role: "user", content: "Square Cloud とは何かを一文で説明してください。" }, ], }); console.log(completion.choices[0].message.content); ``` ```python Python (OpenAI SDK) theme={"system"} from openai import OpenAI client = OpenAI( base_url="https://api.squarecloud.app/v2/ai", api_key="YOUR_API_KEY", ) completion = client.chat.completions.create( model="cubic", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Square Cloud とは何かを一文で説明してください。"}, ], ) print(completion.choices[0].message.content) ``` ```bash cURL theme={"system"} curl --request POST \ --url https://api.squarecloud.app/v2/ai/chat/completions \ --header 'Authorization: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "model": "cubic", "messages": [ { "role": "user", "content": "Square Cloud とは何かを一文で説明してください。" } ] }' ``` ```json theme={"system"} { "id": "chatcmpl-9f2c1a7e4b3d8f6a0c5e2d1b", "object": "chat.completion", "created": 1754179200, "model": "cubic", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Square Cloud は、インフラの設定なしでアプリケーション、ボット、Web サイト、データベースをホストできるクラウドプラットフォームです。" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 28, "completion_tokens": 24, "total_tokens": 52 } } ``` ## エラー 認証、スコープ、レート制限、不正なボディ、`500`、`503` のエラーを含め、すべてのエラーは OpenAI 形式の `{ "error": { "message", "type", "param", "code" } }` を使い、`code` は常に小文字です。 | ステータス | コード | 意味と対処 | | - | - | - | | 401 | `access_denied` | API キーがない、無効、失効済み、または期限切れです。 | | 403 | `upgrade_required` | プランで AI Gateway を利用できません (Hobby またはプランなし)。Standard 以上にアップグレードしてください。 | | 403 | `missing_scope` | API キーに、このエンドポイントに必要なスコープがありません。 | | 403 | `resource_not_allowed` | API キーは、このリクエストの対象を含まないリソースに制限されています。 | | 400 | `invalid_json_body` / `invalid_messages` / `invalid_tools` / `invalid_tool_choice` / `invalid_temperature` / `invalid_max_tokens` | リクエストボディの形式が不正です。指摘されたフィールドを修正してください。 | | 400 | `stream_not_supported` | `stream: true` を削除してください。ストリーミングはまだ利用できません。 | | 400 | `multimodal_not_supported` | このエンドポイントはテキスト専用です。各メッセージの `content` を文字列で送信し、`audio` や `["text"]` 以外の `modalities` を削除してください。 | | 400 | `context_length_exceeded` | メッセージとツール定義の合計がプランのコンテキストウィンドウを超えています。履歴を短くするか、アップグレードしてください。 | | 400 | `invalid_request` | モデルのバックエンドがリクエストを拒否しました。ほとんどの場合、ツール呼び出しのプロトコルの誤りです (直前の `tool_calls` に対応しない `tool` メッセージ、重複した呼び出し id など)。 | | 413 | `payload_too_large` | リクエストボディが、このエンドポイントが受け付けるサイズを超えています。履歴を短くしてください。 | | 429 | `concurrent_limit_reached` | すでに処理中のリクエストがあります。完了を待ってください (Enterprise は同時に 2 件まで可能です)。 | | 429 | `rate_limit_exceeded` | プランのリクエスト間隔より速く送信されました。クライアント側で待機時間を入れてください。 | | 429 | `daily_request_limit_reached` | プランの 1 日あたりのリクエスト上限 (Standard 1,000 / Pro 5,000) に達しました。00:00 UTC にリセットされます。Enterprise には上限がありません。 | | 429 | `daily_spend_limit_reached` | ゲートウェイでのプランの 1 日あたりのフェアユース枠に達しました。00:00 UTC にリセットされます。Enterprise の枠は基本の 5 倍です。 | | 429 | `daily_limit_reached` | 1 日あたりの AI トークン枠を使い切りました。00:00 UTC にリセットされます。アップグレードすると枠が増えます。 | | 429 | `rate_limited` | アカウントまたは API キーのリクエスト上限に達しました。待ってから再試行してください。 | | 500 | `internal_server_error` | 予期しないエラーです。再試行してください。 | | 503 | `server_overloaded` | 処理能力が一時的に満杯か、リクエストが合計 90 秒の期限を超えました。少し待って再試行してください (OpenAI SDK はこれを自動的に再試行します)。 | | 503 | `daily_capacity_reached` | プラットフォーム全体で共有する AI Gateway の 1 日あたりの処理能力を使い切りました。00:00 UTC にリセットされ、それまでに再試行しても効果はありません。 | | 503 | `database_unavailable` | プラットフォームが一時的に利用できません。数秒後に再試行してください。 | 次の 3 つは似ていますが、意味が異なります。 * `429 daily_spend_limit_reached`: プランで決まる、**あなたの**キーの 1 日あたりの上限です。 * `503 daily_capacity_reached`: すべての顧客が共有する、ゲートウェイの**プラットフォーム**全体の 1 日あたりの処理能力です。 * `503 server_overloaded`: 一時的な過負荷、または合計 90 秒 (プロバイダーの待ち行列、再試行、検索ラウンドを含む) を超えたリクエストです。数秒後に再試行してください。 ## よくある質問 いいえ。API は OpenAI と同じくステートレスです。リクエストのたびに、会話の履歴を `messages` で送信してください。 Square Cloud がホストするモデル `cubic` です。選択できるモデルの一覧はなく、`model` フィールドは SDK との互換性のために受け付けています。 はい、それが主な用途です。通常の HTTPS API なので、どこからでも利用できます。 はい。どちらも同じ 1 日あたりの AI トークン枠を消費するため、ゲートウェイを多く使うとダッシュボードのアシスタントで使える枠が減り、その逆も同様です。 ## 関連項目 * SDK: [`api.ai.chat()`](/ja/sdks/js/ai) (JavaScript), [`client.ai.chat()`](/ja/sdks/py/ai) (Python), [`c.AI.Chat()`](/ja/sdks/go/ai) (Go)