よく使うツールの接続

カスタムの OpenAI 互換アドレスをサポートするクライアントは、通常 Base URL、API Key、モデル ID を設定するだけで済みます。モデルカタログは /v1/models のリアルタイムの結果を基準とします。

OpenAI 互換クライアントは、モデルカタログ、テキスト対話、画像生成、動画タスク、テキスト読み上げのインターフェースをカバーします。素材ライブラリのインターフェースはプラットフォーム独自の /api/v1/materials/... パスを使用するため、素材ライブラリインターフェースに従って HTTP リクエストを直接送信してください。クライアントはこの部分を担当しません。

共通設定

ツールが完全な URL の入力を求める場合は https://locopalai.com/v1/chat/completions を使用し、Base URL を求める場合は /v1 まで入力すれば十分です。

プラットフォームは https://us-api.locopalai.com など、海外モデルや特定のネットワーク環境向けのアドレスも表示する場合があります。接続時にはコンソールに現在表示されているアドレスを使用してください。2 つのドメインを同時に同じクライアント設定に書き込まないでください。

OpenAI JavaScript SDK

npm install openai

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.LOCOPAL_API_KEY,
  baseURL: 'https://locopalai.com/v1',
})

const models = await client.models.list()
const result = await client.chat.completions.create({
  model: models.data[0].id,
  messages: [{ role: 'user', content: '你好' }],
})
console.log(result.choices[0].message.content)

OpenAI Python SDK

pip install openai

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LOCOPAL_API_KEY"],
    base_url="https://locopalai.com/v1",
)
models = client.models.list()
response = client.chat.completions.create(
    model=models.data[0].id,
    messages=[{"role": "user", "content": "你好"}],
)
print(response.choices[0].message.content)

Cherry Studio

1. モデルサービスの設定を開き、OpenAI 互換サービスを追加します。
2. API アドレスに https://locopalai.com/v1 を入力します。
3. API Key にコンソールで作成したキーを入力します。
4. モデルの取得をクリックするか、/v1/models が返すモデル ID を手動で入力します。
5. 保存後、新しい会話を作成して検証します。

モデル一覧が空の場合は、まず curl で同じ Key の /v1/models を検証してください。curl が正常であれば、クライアントが /v1 を重複して連結していないか確認します。

OpenCode

ユーザーレベルまたはプロジェクトレベルの opencode.json で OpenAI 互換 Provider を設定します：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "locopal": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LocoPal Ai",
      "options": {
        "baseURL": "https://locopalai.com/v1",
        "apiKey": "{env:LOCOPAL_API_KEY}"
      },
      "models": {
        "你的模型ID": { "name": "你的模型ID" }
      }
    }
  },
  "model": "locopal/你的模型ID"
}

設定構文はクライアントのバージョンによって変わる場合があります。現在のクライアントの設定仕様を基準にしてください。重要なのは、Base URL、API Key、モデル ID の 3 項目が一致していることです。

Trae とその他の IDE

「設定 → モデル → モデルを追加」で OpenAI 互換形式を選択します：

1. 「完全な URL」をオフにする場合は https://locopalai.com/v1 を入力します。
2. 「完全な URL」をオンにする場合は https://locopalai.com/v1/chat/completions を入力します。
3. API Key を入力します。
4. 現在利用可能なモデル ID を入力します。
5. モデルの実際の機能に応じて、ビジョンやツール呼び出しのオプションを有効にします。

Postman / Apifox

base_url=https://locopalai.com、api_key=你的APIKey、model=从 /v1/models 获取的模型 ID の 3 つの環境変数を作成します。各リクエストに次を追加します：

Authorization: Bearer {{api_key}}
Content-Type: application/json

動画タスクでは、まず作成レスポンスの ID を保存し、次に GET で {{base_url}}/v1/video/generations/{{task_id}} を照会します。

サーバー側プロキシの推奨事項

ブラウザやモバイルアプリがプラットフォームの API Key を直接保持しないでください。推奨アーキテクチャは「Web ページまたは App → あなたの業務バックエンド → LocoPal Ai」です。業務バックエンドがユーザー認証、パラメータ検証、リクエストログ、タスク ID の永続化、クォータ制御、結果の保存し直しを担当します。

接続のセルフチェック

1. GET /v1/models が少なくとも 1 つのモデルを返す。
2. テキスト呼び出しで choices を取得できる。
3. 動画作成でタスク ID を取得できる。
4. 動画照会がステータスを返し、重複作成されない。
5. 現在のグループがテキスト読み上げモデルを提供している場合、POST /v1/audio/speech が再生可能なバイナリ音声を返す。
6. 401 の場合は Key を確認し、429 の場合は案内に従って待機し、5xx の場合は RequestId を保存してから再試行可能か判断する。