OpenAI 互換の AI Gateway (ベータ)

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);

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)

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 とは何かを一文で説明してください。" }
    ]
  }'

{
  "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
  }
}

string

必須

アカウントの API キーです。これはアカウント設定で確認できます。

ai:chat スコープを持つ 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 キー (アカウントページで取得する、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 以上にアップグレードすると利用できるようになります。

リクエストの仕様

string

SDK との互換性のために受け付けます。ゲートウェイは常に cubic として応答します。

array

必須

OpenAI 形式のメッセージで、ロールは system、user、assistant、tool です。内容は文字列である必要があります。このエンドポイントはテキスト専用のため、マルチパートの配列 (image_url、input_audio、file) は 400 multimodal_not_supported で拒否されます。1 回のリクエストあたり最大 100 メッセージです。

number

プランの出力上限に合わせて自動的に切り詰められます。

number

0 から 2 まで。

array

標準的な OpenAI 形式の関数呼び出しで、最大 32 個のツール定義を指定できます。ツール呼び出しは finish_reason: "tool_calls" として返され、結果は role: "tool" のメッセージで送り返します。

string | object

標準的な OpenAI の tool_choice の値です。

未知のパラメーターは無視されますが、意図的な例外が 2 つあります。audio と、["text"] 以外の modalities の値は、無視されるのではなく拒否されます。そのため、音声出力を求めたリクエストが無音のテキストとして返ってくることはありません。 テキストを送り、テキストを受け取ります。 画像、音声、ファイルはどのプランでも受け付けません。これは一時的な制約ではなく、プロダクトとしての判断です。テキストを送信し、テキストを受け取ってください。 未対応の機能: ストリーミング (stream: true は 400 stream_not_supported を返します)。

組み込みの Web 検索

会話が最新の情報や外部の情報を必要とする場合、モデルは自ら判断して Web を検索します。検索はサーバー側で実行され、返されるのは結果の URL を引用した最終的な回答だけです。web_search という名前のツールを自分で宣言すると、組み込みのものの代わりにそのツールが使われます。

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);

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)

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 とは何かを一文で説明してください。" }
    ]
  }'

{
  "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 との互換性のために受け付けています。

Square Cloud でホストしているアプリケーションから呼び出せますか?

はい、それが主な用途です。通常の HTTPS API なので、どこからでも利用できます。

ゲートウェイの利用はダッシュボードの AI アシスタントに影響しますか?

はい。どちらも同じ 1 日あたりの AI トークン枠を消費するため、ゲートウェイを多く使うとダッシュボードのアシスタントで使える枠が減り、その逆も同様です。

はじめに

アカウント

アプリケーション

データベース

ワークスペース

AI

OpenAI 互換の AI Gateway (ベータ)

接続方法

プランと制限

リクエストの仕様

組み込みの Web 検索

エラー

よくある質問

関連項目

​接続方法

​プランと制限

​リクエストの仕様

​組み込みの Web 検索

​エラー

​よくある質問

​関連項目

接続方法

プランと制限

リクエストの仕様

組み込みの Web 検索

エラー

よくある質問

関連項目