素材ライブラリ API 概要

素材ライブラリ API は、素材グループの作成、画像の送信、素材ステータスの照会、素材の同期、実在人物の QR コード許諾の開始に使用します。すべての API は同じプラットフォーム API キーを使用し、追加の署名や他のサービスの呼び出しは不要です。

共通の取り決め（ベースアドレス、認証方式、レート制限、冪等性）は認証と基本仕様を参照してください。

具体的な API：

エンドポイント一覧

統一レスポンス構造

成功時：

{ "code": 0, "data": {}, "msg": "OK" }

失敗時は HTTP ステータスコードと code が一致し、data は null になります：

{ "code": 404, "data": null, "msg": "素材不存在或无权访问" }

data の実際の構造

data は配列ではなくオブジェクトで、具体的なフィールドは API によって異なります。一覧系 API のコレクションは名前付きキーの下に置かれます：

{
  "code": 0,
  "data": {
    "groups": [
      { "id": "group-1789069780-5762d1", "name": "我的角色素材", "type": "virtual" }
    ],
    "page": 1,
    "page_size": 20,
    "total": 4
  },
  "msg": "OK"
}

data がそのまま配列であると想定しないでください。 グループ一覧は data.groups、素材一覧は data.assets にあります。 コレクションを読み取るときは名前付きキーを使用し、data.total で次のページがあるかどうかを判断してください。

注意：自動登録されたリソースには id がない場合があります

プラットフォームが自動登録した素材グループでは、id と platform_group_id が空文字列になる場合があります：

{ "id": "", "platform_group_id": "", "name": "自动登记素材", "type": "virtual" }

一覧の結果を保存したりマージしたりする際に id を一意キーとして使用しないでください。そうしないと、複数の自動登録エントリが互いに上書きされます。 代わりに platform_group_id || id || name の組み合わせを使用するか、後続の API 呼び出しに使用できないエントリはスキップすることをおすすめします。 唯一の例外は認証失敗です。API キーが欠落、誤り、または失効している場合は HTTP 401 を返し、レスポンスボディは {"error":{"code":"","message":"Invalid token (request id: ...)","type":"new_api_error"}} です。

変数の準備

export LOCOPAL_API_KEY="sk-你的APIKey"
export LOCOPAL_BASE_URL="https://locopalai.com"
export LOCOPAL_IMAGE_URL="https://你的对象存储域名/person.png"

素材 ID について

API が返す data.asset_id（data.asset.id と同じ）が素材の一意な ID です。コンソールの「素材管理」一覧に表示される素材 ID も同じ値で、両者は相互に使用でき、プログラム内でマッピングを行う必要はありません。

素材は API キーではなくアカウントに属します。同じアカウントでキーを変更したり、キーを再作成したり、呼び出しグループを切り替えたりしても、元の素材を引き続き照会して使用できます。他のアカウントからは表示も参照もできません。

モデルと素材ライブラリ

素材はプラットフォームの統一素材ライブラリで管理されます。一度登録すれば、以下のモデルはすべて同じ素材を直接使用でき、特定のモデル用にコピーを用意したり、審査を再送信したりする必要はありません。

したがって：

• 素材は一度登録するだけで、モデルを変更するときはリクエストの model フィールドを変えるだけで、素材 ID を変更する必要はありません。
• モデルごとにグループを個別に作成する必要はなく、「素材をどの素材ライブラリに入れるか」を指定する必要もありません。
• 実在人物素材は生体認証による許諾をサポートする素材ライブラリで管理され、参照をサポートするモデルは doubao-seedance-2.0-D、doubao-seedance-2.0-D-fast、doubao-seedance-2.0-D-mini、doubao-seedance-2.5-D、seedance-2.0、seedance-2.0-fast、seedance-2.0-mini、seedance-2.5 です。実在人物素材を他のモデルに送信すると読み取り可能なエラーが返されます。制限を回避するために通常の画像 URL に変更しないでください。

素材ステータスが Active になれば、素材参照をサポートする任意のモデルで使用でき、モデル側での再準備を待つ必要はありません。

これより前に登録された既存の素材は、初めてあるモデルから参照されたときにプラットフォームが一度だけ準備します。準備が完了すれば、直接参照した素材と同じように動作します。新しく登録された素材ではこの手順は不要です。