OpenAI 互換の AI Gateway (ベータ)
OpenAI 互換の POST /v2/ai/chat/completions で、Square Cloud がホストする cubic モデルを自社プロダクトから利用できます。ツール呼び出しと Web 検索に対応しています。
ai:chat スコープを持つ API キーが必要です。
AI Gateway を使うと、Square Cloud がホストする AI モデルを、自社のプロダクト (チャットボット、アシスタント、自動化) の中で OpenAI 互換のチャット補完エンドポイントから利用できます。すでに OpenAI API を使うコードであれば、そのまま AI Gateway でも動きます。SDK のベース URL を Square Cloud に向け、アカウントの API キーを使い、モデルに cubic を指定してください。
AI Gateway は無料の先行アクセス付きのベータ版です。ベータ期間中は追加料金はかからず、利用量はゲートウェイ独自のトークン上限にのみカウントされます。ベータ終了時に、制限や利用できるプランが変更される場合があります。
接続方法
- ベース URL:
https://api.squarecloud.app/v2/ai - API キー: アカウントの API キー (アカウントページで取得する、Square Cloud API や CLI と同じもの)。
AuthorizationヘッダーはBearerプレフィックスの有無を問わず受け付けます。 - モデル:
cubic。Square Cloud がホストするモデルで、ダッシュボードの AI アシスタントと同じものです。
プランと制限
すべてのリクエストは、実際に使用したトークン分がゲートウェイ独自のトークン上限から差し引かれます。1 日あたりの上限 (00:00 UTC にリセット) と、その 4 倍の週あたりの上限 (月曜日の 00:00 UTC にリセット) があります。これらはダッシュボードの AI アシスタントの上限とは別なので、ゲートウェイの利用でアシスタントの枠を使い切ることはなく、その逆もありません。Standard と Pro には 1 日あたりのリクエスト上限もあり、さらにすべてのプランに、適度な利用を想定したゲートウェイの 1 日あたりのフェアユース枠があります (放置されたキーへの安全策で、リクエストの処理コストに基づきます)。どちらも 00:00 UTC にリセットされます。
Standard プランはどのサイズでもゲートウェイの上限が同じで、Pro もすべてのサイズで同じです。Enterprise のトークン上限はプランに応じて増えます。1 日あたり Enterprise 32 で 10M トークン、Enterprise 48 で 12M、Enterprise 64 で 14M、Enterprise 96 で 16M、Enterprise 128 以上で 20M で、週あたりの上限はその 4 倍です。
Hobby プラン (およびプランのないアカウント) は AI Gateway を利用できません。Standard 以上にアップグレードすると利用できるようになります。
リクエストの仕様
string
SDK との互換性のために受け付けます。ゲートウェイは常に
cubic として応答します。array
必須
OpenAI 形式のメッセージで、ロールは
system、user、assistant、tool です。内容は文字列である必要があります。このエンドポイントはテキスト専用のため、マルチパートの配列 (image_url、input_audio、file) は 400 multimodal_not_supported で拒否されます。1 回のリクエストあたり最大 100 メッセージです。number
回答のトークン上限を表す OpenAI の現在の名前で、OpenAI SDK はこちらを送信します。
max_tokens と両方ある場合はこちらが優先されます。プランの出力上限に合わせて自動的に切り詰められます。number
従来の名前で、引き続き使えます。プランの出力上限に合わせて自動的に切り詰められます。
number
0 から 2 まで。
array
標準的な OpenAI 形式の関数呼び出しで、最大 32 個のツール定義を指定できます。ツール呼び出しは
finish_reason: "tool_calls" として返され、結果は role: "tool" のメッセージで送り返します。string | object
標準的な OpenAI の
tool_choice の値です。audio と、["text"] 以外の modalities の値は、無視されるのではなく拒否されます。そのため、音声出力を求めたリクエストが無音のテキストとして返ってくることはありません。
テキストを送り、テキストを受け取ります。 画像、音声、ファイルはどのプランでも受け付けません。これは一時的な制約ではなく、プロダクトとしての判断です。テキストを送信し、テキストを受け取ってください。
未対応の機能: ストリーミング (stream: true は 400 stream_not_supported を返します)。
組み込みの Web 検索
会話が最新の情報や外部の情報を必要とする場合、モデルは自ら判断して Web を検索します。検索はサーバー側で実行され、返されるのは結果の URL を引用した最終的な回答だけです。web_search という名前のツールを自分で宣言すると、組み込みのものの代わりにそのツールが使われます。
エラー
認証、スコープ、レート制限、不正なボディ、500、503 のエラーを含め、すべてのエラーは OpenAI 形式の { "error": { "message", "type", "param", "code" } } を使い、code は常に小文字です。
次の 3 つは似ていますが、意味が異なります。
429 daily_spend_limit_reached: プランで決まる、あなたのキーの 1 日あたりの上限です。503 daily_capacity_reached: すべての顧客が共有する、ゲートウェイのプラットフォーム全体の 1 日あたりの処理能力です。503 server_overloaded: 一時的な過負荷、または合計 90 秒 (プロバイダーの待ち行列、再試行、検索ラウンドを含む) を超えたリクエストです。数秒後に再試行してください。
再試行
ほとんどの429 と 503 の応答は、OpenAI SDK が読み取るヘッダーで、いつ再試行できるかをクライアントに伝えます。
OpenAI SDK は最大 60 秒までの
Retry-After に従います。それより長い待ち時間では SDK 自身のバックオフが使われますが、応答に x-should-retry: false も含まれている場合は自動再試行が無効になります。OpenAI SDK を使わない場合は、Retry-After を自分で読み取り、その秒数だけ待ってから次のリクエストを送ってください。
よくある質問
会話を記憶しますか?
会話を記憶しますか?
いいえ。API は OpenAI と同じくステートレスです。リクエストのたびに、会話の履歴を
messages で送信してください。どのモデルですか?
どのモデルですか?
Square Cloud がホストするモデル
cubic です。選択できるモデルの一覧はなく、model フィールドは SDK との互換性のために受け付けています。Square Cloud でホストしているアプリケーションから呼び出せますか?
Square Cloud でホストしているアプリケーションから呼び出せますか?
はい、それが主な用途です。通常の HTTPS API なので、どこからでも利用できます。
ゲートウェイの利用はダッシュボードの AI アシスタントに影響しますか?
ゲートウェイの利用はダッシュボードの AI アシスタントに影響しますか?
いいえ。ゲートウェイにはダッシュボードのアシスタントとは別の、独自の 1 日あたりと週あたりのトークン上限があるため、ゲートウェイを多く使ってもアシスタントの枠を使い切ることはなく、その逆もありません。
関連項目
- SDK:
api.ai.chat()(JavaScript),client.ai.chat()(Python),c.AI.Chat()(Go)

