クイックスタート

LocoPal には現在 2 つのよく使われる手段があります。直接 LocoPal Creation で制作するか、LocoPal Ai の API で自社サービスに接続するかです。

2 つの方法は同じ LocoPal アカウント、モデルカタログ、課金体系を共有します。本ページでは LocoPal Ai と LocoPal Creation を中心に説明します。

ステップ 1：LocoPal Ai に登録またはログインする

1. LocoPal Ai を開きます。アカウントをお持ちの場合はそのままログインし、お持ちでない場合は登録ページに進みます。
2. 現在の登録ページではユーザー名とパスワードの設定、および携帯電話番号の SMS 認証が必要です。認証方法はセキュリティポリシーにより変わる場合があるため、登録ページに実際に表示される案内に従ってください。
3. ログイン後、アカウント残高、プランのクォータ、または利用可能なポイントを確認します。Creation や API を使用する前に、必ずアカウントの利用可能状態を確認してください。

ステップ 2：LocoPal Creation を直接使う

コンテンツを直接生成することが目的であれば、まず Creation を使うことをおすすめします。コードを書く必要も、API Key を作成する必要もありません。

1. LocoPal Creation を開きます。
2. Creation に独立したアカウントはありません。未ログインの場合、ページは LocoPal のログインへリダイレクトされ、認証が完了すると自動的に Creation に戻ります。パスワードの再入力は不要です。
3. ホームページでスマートモード、AI 描画、AI 動画、AI 音声を選択して要件を入力します。ワークスペースに入った後は、ショートドラマ、作品、素材、プロンプト、語彙集、作品マーケットなどの入口も利用できます。
4. 人物、商品、スタイルの一貫性を保つ必要がある場合は、送信前に参照画像をアップロードするか、既存の素材を選択します。
5. 送信後は現在のページでタスクの状態を確認し、結果をプレビューしてダウンロードまたは引き続き参照します。ページを更新してもタスクが再作成されることはありません。実行中のタスクに対して重複して送信しないでください。

Creation で利用できるモデルの範囲は現在の LocoPal Ai モデルカタログと一致しており、呼び出しの消費はすべて現在の LocoPal アカウントに計上されます。モデルが利用できない場合は、まず LocoPal Ai のモデルマーケットでそのモデルが現在の利用可能なグループに含まれているか確認してください。

ステップ 3：API に接続して API Key を作成する

LocoPal Ai コンソールの「API キー」に入り、作成をクリックします。「本番サービス / テスト環境 / 顧客アプリケーション」ごとに個別にキーを作成することをおすすめします。アプリケーション別にログを確認し、クォータを制限し、漏洩したキーを速やかに無効化できます。

作成時に重点的に確認する項目：

• Key の名前は呼び出し元を区別するために使用します；
• 呼び出しグループはこの Key がどのモデルを表示・呼び出しできるかを決定します；
• クォータと有効期限は異常な消費を制限するために使用します；
• 1 つの Key でモデル、画像、動画、音声、素材のインターフェースを呼び出せます。インターフェースごとに異なる Key を作成する必要はありません。

API Key はサーバー側の環境変数またはシークレット管理サービスにのみ保存し、Web ページのソースコード、モバイルアプリのインストールパッケージ、公開リポジトリ、ログ、スクリーンショットに書き込まないでください。

ステップ 4：ベースアドレスを準備する

デフォルトのベースアドレス：

export LOCOPAL_API_KEY="sk-你的APIKey"
export LOCOPAL_BASE_URL="https://locopalai.com"

プラットフォームのコンソールには、海外モデルや特定のネットワーク環境向けの接続アドレスが表示される場合もあります。例えば：

https://us-api.locopalai.com

実際の接続時には、コンソールに現在表示されているアドレスを使用してください。LOCOPAL_BASE_URL はドメインまでを記述し、/v1 を重複して追加しないでください。インターフェースのパス自体に /v1 または /api/v1 が既に含まれています。

ステップ 5：現在の Key で利用可能なモデルを照会する

curl "$LOCOPAL_BASE_URL/v1/models" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

{
  "object": "list",
  "success": true,
  "data": [
    {
      "id": "doubao-seedance-2.0",
      "object": "model",
      "created": 1626777600,
      "owned_by": "doubaovideo",
      "supported_endpoint_types": ["openai"]
    }
  ]
}

• リクエストの model には必ず data[].id を使用し、ページに表示される名前は使用しないでください；
• "data": [] が返った場合は、現在の Key が属する呼び出しグループに利用可能なモデルがないことを意味します。まずグループ設定を確認するか、プラットフォームサポートに連絡してください；
• モデルカタログはアカウントの認可、接続アドレス、プラットフォームの可用性によって変化します。サービス起動時、ユーザーがモデルを切り替えた時、または「モデルが利用できません」を受信した時に再照会することをおすすめします；
• 同じ Key でも locopalai.com と us-api.locopalai.com で見えるモデル集合が異なる場合があります。どのアドレスを使う場合でも、そのアドレスの /v1/models を基準にしてください；
• モデルを呼び出せるかどうかは現在の Key の /v1/models の結果を基準とし、モデル名をハードコーディングしないでください。

supported_endpoint_types でどのサンプルを使うかを判断する

data[].supported_endpoint_types は、そのモデルがどの種類のインターフェースを使うかを直接示します。これに基づいてサンプルを選択してください：

1 つのモデルの supported_endpoint_types に複数の項目が含まれる場合があり、複数のインターフェースで呼び出せることを意味します。

ステップ 6：最初のテキスト呼び出し

curl -X POST "$LOCOPAL_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的文本模型 ID",
    "messages": [{ "role": "user", "content": "用三句话介绍这个产品" }],
    "stream": false
  }'

成功時は choices[0].message.content からテキストを読み取り、レスポンスの usage を保存して照合に使用します。推論モデルでは max_tokens をすべて completion_tokens_details.reasoning_tokens に消費する場合があり、その際 message.content は空で finish_reason は length になります。出力上限を上げるか、推論以外のモデルに切り替えて再試行してください。stream: true を有効にすると SSE で段階的に読み取り、[DONE] を読んだ時点で終了します。

ステップ 7：最初の画像呼び出し

curl -X POST "$LOCOPAL_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的图片模型 ID",
    "prompt": "白色桌面上的一个红苹果，柔和自然光，产品摄影",
    "size": "1024x1024",
    "n": 1
  }'

レスポンス結果は通常 data[] の中で url または b64_json として返されます。返される URL は短期間有効なアドレスである場合があるため、できるだけ早く保存し直してください。size、quality、response_format は現在の画像モデルに依存します。一部の GPT Image モデルは response_format を拒否し unknown_parameter を返します。その場合はこのフィールドを削除してください。画像を後続の動画参照として使用する場合は、まず素材ライブラリのインターフェースで登録し、ステータスが Active になるのを待ってから asset://<asset_id> で参照してください。

ステップ 8：最初の動画呼び出し

動画は非同期タスクです：作成インターフェースはタスク ID を返し、照会インターフェースは進捗と結果を返します。

POST /v1/video/generations と POST /v1/videos は同じリクエストボディとレスポンス形式を使用するため、どちらを選んでもかまいません。旧呼び出しパスはプラットフォームが自動的に動画タスクプラグインとして処理します。

curl -X POST "$LOCOPAL_BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "从 /v1/models 选择的视频模型 ID",
  "content": [
    { "type": "text", "text": "清晨的湖边，镜头缓慢向前推进" }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}
JSON

{
  "created_at": 1789567067,
  "id": "task-public-id",
  "model": "seedance-2.0-mini",
  "status": "queued",
  "task_id": "task-public-id"
}

作成レスポンスでは id / task_id、status、model、created_at のみに依存するべきです。object、progress などのフィールドは最初の照会後に初めて現れる場合があり、作成成功の必須条件として扱うことはできません。

作成レスポンスの id を保存し、同じタスクを照会します：

export LOCOPAL_TASK_ID="创建响应里的 id"

curl "$LOCOPAL_BASE_URL/v1/video/generations/$LOCOPAL_TASK_ID" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

タスク成功後は metadata.url を読み取って結果をダウンロードまたは再生します。プラットフォームは上流の元動画 URL を優先して返します。上流が読み取り可能なアドレスを返さない場合にのみ、プラットフォームの成果物アドレスをフォールバックとして使用します。上流が返す動画パラメータには以下が含まれる場合があります：

{
  "metadata": {
    "url": "https://上游原始视频地址",
    "upstream_created": true
  },
  "duration_secs": 5,
  "expires_at": 1790578352,
  "framespersecond": 24,
  "generate_audio": true,
  "ratio": "9:16",
  "resolution": "480p",
  "seed": 20260409,
  "output_format": "mp4",
  "execution_expires_after": 172800
}

上記のフィールドのうち、duration_secs は長さ；expires_at は対応する上流が返した場合にのみ現れ；その他の動画パラメータも同様に、モデルと上流が実際に返した場合にのみ現れます。タスク ID を取得した後、ローカルの待機がタイムアウトしても元のタスクを引き続き照会するだけにし、再作成しないでください。そうしないと重複タスクと費用が発生します。

照会結果の status が failed の場合、同じレスポンスの error.code と error.message を読み取ります。動画タスクの終端状態の失敗は通常 video_generation_failed を使用し、error.message はプラットフォームがクリーンアップした読み取り可能な理由です。その中の JSON をさらに解析しないでください：

{
  "id": "task-public-id",
  "status": "failed",
  "error": {
    "code": "video_generation_failed",
    "message": "音频素材缓冲失败: 音频地址必须是 http(s)"
  }
}

ステップ 9：最初のテキスト読み上げ呼び出し

プラットフォームは OpenAI 互換の POST /v1/audio/speech インターフェースを提供します。利用可能かどうかは現在の API Key のグループとモデルカタログに依存します。対応する音声、形式、速度のパラメータは実際のモデルを基準にしてください。

curl -X POST "$LOCOPAL_BASE_URL/v1/audio/speech" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的音频模型 ID",
    "input": "欢迎使用 LocoPal Ai。",
    "voice": "alloy",
    "response_format": "mp3"
  }' \
  --output speech.mp3

成功レスポンスの本文はバイナリ音声であり、JSON ではありません。サンプルでは --output を使用して speech.mp3 として保存します。その他の音声タスクの非同期ステータスと成果物は「タスクログ」で照会できます。

ステップ 10：最初の素材呼び出し

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/groups" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "我的角色素材",
  "description": "视频参考图",
  "type": "virtual"
}
JSON

{
  "code": 0,
  "data": {
    "group": {
      "id": "group-1789069780-5762d1",
      "platform_group_id": "group-1789069780-5762d1",
      "name": "我的角色素材",
      "type": "virtual",
      "description": "视频参考图",
      "created_at": 1789069780,
      "updated_at": 1789069780
    }
  },
  "msg": "素材分组已创建"
}

data.group.id を保存し、画像を送信してステータスをポーリングします：

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/assets" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group_id":"group-id","title":"角色正面图","image_url":"https://你的对象存储域名/person.png"}'

curl "$LOCOPAL_BASE_URL/api/v1/materials/assets/asset-id" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

image_url には公衆網から直接ダウンロード可能な http(s) アドレスを使用します。インターフェースの制限に応じて data_url を送信することもできます。data.asset.status が Active になった後、動画リクエストで asset://<asset_id> を使用して参照できます。完全なパラメータとエラーの説明は素材ライブラリインターフェースを参照してください。

ステップ 11：実写人物素材（任意）

実写人物素材は必ず本人がスマートフォンで QR コードをスキャンして収集と許諾を完了する必要があり、通常の画像アップロードで代用することはできません。コンソールのフローは「素材ライブラリ管理 → 新規グループ → 実写人物素材 → QR コード生成 → 本人がスキャン → スキャン完了、同期開始」です。インターフェースのフローは実写人物スキャンセッションの作成を参照してください。

次のステップ