メインコンテンツへ移動
LocoPal AiLocoPal Ai
素材ライブラリ素材ライブラリ API

ガイド

素材

画像素材の送信、審査ステータスと素材一覧の照会

Markdown を表示

素材

素材は送信後にプラットフォームが非同期で処理し、ステータスが Processing から Active になった後に動画タスクで使用できます。

画像素材の送信

POST/api/v1/materials/assets

認証方式

Authorization: Bearer <API_KEY>。

リクエストボディ · application/json

Prop

Type

image_url と data_url はどちらか一方しか送信できません。image_url には data:image/...;base64,... も指定でき、プラットフォームはこれをインライン画像として処理します。リモート URL を使用する場合、アドレスはプラットフォームが公開ダウンロードできる http(s):// アドレス（http と https の両方に対応）である必要があり、Cookie、Referer、ログインページ、ブラウザセッションに依存せず、プラットフォームの処理期間中は有効であり続ける必要があります。

リモートの image_url は、まずプラットフォームの高速中継キャッシュを経由し、その後素材ライブラリにミラーリングされます。通常の画像であれば数秒で完了します。プラットフォームはインライン画像にも対応しています。image_url の値に data:image/...;base64,... を指定するか、独立した data_url フィールドを使用できます。すでにクライアント側にある画像の場合、インラインで送信すると外部ダウンロードを 1 回減らせます。

data_url は画像全体を base64 でアップロードします（サイズは元画像の約 1.33 倍）。画像にどうしても公開アドレスを用意できない場合にのみ使用してください。たとえば、画像がログインが必要なアドレスの背後にある場合、社内ネットワーク内にある場合、ローカルファイルしかない場合などです。data_url を使用すると、アップロード時間は画像サイズと呼び出し側の帯域に依存し、プラットフォームは画像を永久のプラットフォーム素材ストレージではなく短期の一時中継に書き込みます。素材ライブラリのミラーリングが完了して Active になると、プレビューには素材ライブラリが返す preview_url が優先的に使用され、一時ファイルは中継サービスによって自動的に削除されます。

画像素材は virtual グループにのみ送信できます。real グループの素材は実在人物の QR コード許諾フローで生成されます。

request_id は Idempotency-Key リクエストヘッダーで送信することもできます。同じアカウントが同じ request_id で重複して送信した場合、プラットフォームは最初に作成に成功した同じ素材を返し、上流の素材を再度作成することはありません。request_id を送信しない場合、プラットフォームはアカウント、グループ、タイトル、元の画像ペイロードに基づいて安定した値を自動生成します。同じ画像とタイトルでの再試行も安全に再利用できます。

リクエスト例

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/assets" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "group_id": "group-1789069780-5762d1",
  "request_id": "brand-character-front-001",
  "title": "角色正面定妆图",
  "image_url": "$LOCOPAL_IMAGE_URL",
  "tags": ["人物", "正面"]
}
JSON

ローカル画像を使用する場合は、data_url を送信するように変更します：

{
  "group_id": "group-1789069780-5762d1",
  "request_id": "brand-character-front-001",
  "title": "角色正面定妆图",
  "file_name": "person.png",
  "data_url": "data:image/png;base64,iVBORw0KGgo..."
}

クライアントが引き続き image_url フィールドを使用したい場合は、インライン画像をそのまま送信することもできます：

{
  "group_id": "group-1789069780-5762d1",
  "request_id": "brand-character-front-001",
  "title": "角色正面定妆图",
  "image_url": "data:image/png;base64,iVBORw0KGgo..."
}

レスポンスパラメータ

パラメータ型説明
codeinteger成功時は 0
msgstring成功時は 图片素材已提交
data.asset_idstring素材 ID。data.asset.id と同じ
data.asset.idstring素材 ID。動画タスクでは asset://<id> で参照します
data.asset.kindstring素材タイプ。画像の場合は image
data.asset.titlestring素材名（自動補完後の最終値）
data.asset.request_idstring / null今回のアップロードで使用した冪等リクエスト ID
data.asset.platform_asset_idstring素材サービスのプラットフォーム素材 ID。調査用で、現在のデプロイでは通常 id と同じです
data.asset.group_idstring所属グループ ID
data.asset.statusstring受理後は Processing
data.asset.error_messagestring / null処理失敗の理由。通常は null
data.asset.notestring / nullメモ。未送信の場合は null
data.asset.tagsstring[]タグ一覧。未送信の場合は通常空の配列
data.asset.mime_typestring / null素材サービスが返す MIME タイプ。返されない場合は null
data.asset.bytesinteger / null素材ファイルのサイズ。素材サービスが返さない場合は null
data.asset.created_atinteger作成日時（Unix 秒）
data.asset.updated_atinteger更新日時（Unix 秒）

レスポンスボディ

{
  "code": 0,
  "data": {
    "asset_id": "asset-20260911035115-etexu",
    "asset": {
      "id": "asset-20260911035115-etexu",
      "platform_asset_id": "asset-20260911035115-etexu",
      "kind": "image",
      "title": "角色正面定妆图",
      "group_id": "group-1789069780-5762d1",
      "status": "Processing",
      "error_message": null,
      "note": null,
      "tags": [],
      "mime_type": null,
      "bytes": null,
      "created_at": 1789069876,
      "updated_at": 1789069876
    }
  },
  "msg": "图片素材已提交"
}

送信の成功は素材が受理されたことだけを示します。動画タスクを送信する前に、必ずステータスを照会してください。

エラーレスポンス

HTTPmsg説明
400缺少 group_idグループが指定されていません
400image_url 必须是可公开下载的 http(s) 地址，当前为 …アドレスのプロトコルが http / https でないか、アドレスが不完全です。公開 http(s) アドレスに変更するか、data_url を使用してください
400image_url 与 data_url 只能提交一个両方のフィールドを同時に送信したか、どちらも送信していません
400data_url 必须是 data:image/...;base64,... 格式data_url の形式が誤っています
400图片数据无效或超过 20MB画像データが空か、20 MB を超えています
400素材名称不能为空 / 素材名称不能超过 64 个字符title の検証に失敗しました
401Invalid tokenAPI キーが欠落、誤り、または失効しています
404素材分组不存在或不属于当前账号group_id が誤っているか、現在のアカウントに属していません
404素材分组不存在或不是虚拟素材分组real グループに画像を送信しました
502 / 503素材服务暂不可用素材サービスに異常があります。リクエスト情報を保持してから再試行してください

単一素材の照会

GET/api/v1/materials/assets/{asset_id}

認証方式

Authorization: Bearer <API_KEY>。

リクエストパラメータ · path

Prop

Type

リクエスト例

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

レスポンスパラメータ

パラメータ型説明
codeinteger成功時は 0
msgstring成功時は OK
data.assetobject素材オブジェクト。フィールドは送信 API と同じです

data.asset.status の値と処理方法：

ステータス意味クライアントの動作
Processing素材がまだ処理中または審査中asset_id を保存し、後で照会する。重複して送信しない
Active素材がこの素材タイプをサポートするタスクで使用可能動画の content で asset://<asset_id> を使用する
Failed素材の処理に失敗error_message を読み取り、元の画像を修正して新しい素材を作成する

レスポンスボディ

{
  "code": 0,
  "data": {
    "asset": {
      "id": "asset-20260911035115-etexu",
      "platform_asset_id": "asset-20260911035115-etexu",
      "kind": "image",
      "title": "角色正面定妆图",
      "group_id": "group-1789069780-5762d1",
      "status": "Active",
      "error_message": null,
      "note": null,
      "tags": [],
      "mime_type": null,
      "bytes": null,
      "created_at": 1789069876,
      "updated_at": 1789069877
    }
  },
  "msg": "OK"
}

審査に失敗した場合も HTTP 200 を返し、失敗理由は error_message に示されます：

{
  "code": 0,
  "data": {
    "asset": {
      "id": "asset-20260911035115-etexu",
      "status": "Failed",
      "error_message": "素材处理失败"
    }
  },
  "msg": "OK"
}

エラーレスポンス

HTTPmsg説明
401Invalid tokenAPI キーが欠落、誤り、または失効しています
404素材不存在或无权访问素材 ID が誤っている、削除済み、または現在のアカウントに属していません
502 / 503素材服务暂不可用素材サービスに異常があります。リクエスト情報を保持してから再試行してください

素材一覧の照会

GET/api/v1/materials/assets

認証方式

Authorization: Bearer <API_KEY>。

リクエストパラメータ · query

パラメータ型必須デフォルト説明
pageintegerいいえ1ページ番号
page_sizeintegerいいえ201 ページあたりの件数。最大 100
group_idstringいいえ—そのグループ内の素材のみを返します

リクエスト例

curl "$LOCOPAL_BASE_URL/api/v1/materials/assets?page=1&page_size=20&group_id=group-1789069780-5762d1" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

レスポンスパラメータ

パラメータ型説明
codeinteger成功時は 0
msgstring成功時は OK
data.totalinteger条件に一致する素材の総数
data.page / data.page_sizeinteger今回のページネーションパラメータ
data.assetsarray素材一覧。フィールドは送信 API と同じです

レスポンスボディ

{
  "code": 0,
  "data": {
    "assets": [
      {
        "id": "asset-20260911035115-etexu",
        "platform_asset_id": "asset-20260911035115-etexu",
        "kind": "image",
        "title": "角色正面定妆图",
        "group_id": "group-1789069780-5762d1",
        "status": "Active",
        "error_message": null,
        "note": null,
        "tags": [],
        "mime_type": null,
        "bytes": null,
        "created_at": 1789069876,
        "updated_at": 1789069877
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  },
  "msg": "OK"
}

エラーレスポンス

HTTPmsg説明
401Invalid tokenAPI キーが欠落、誤り、または失効しています
404素材分组不存在或无权访问指定した group_id が存在しない、または現在のアカウントに属していません
500 / 502 / 503素材服务暂不可用素材サービスに異常があります。リクエスト情報を保持してから再試行してください
このページは役に立ちましたか？

素材グループ

素材グループの作成と照会の API 仕様

素材ステータスの同期

現在のアカウントに基づいてグループと素材の名前、ステータス、エラー情報、アクセスアドレスを更新します

このページの目次

素材画像素材の送信認証方式リクエストボディ · application/jsonリクエスト例レスポンスパラメータレスポンスボディエラーレスポンス単一素材の照会認証方式リクエストパラメータ · pathリクエスト例レスポンスパラメータレスポンスボディエラーレスポンス素材一覧の照会認証方式リクエストパラメータ · queryリクエスト例レスポンスパラメータレスポンスボディエラーレスポンス