Assets

After submission, assets are processed asynchronously by the platform; they can only be used in video tasks after the status changes from Processing to Active.

Submit Image Assets

Authentication

Authorization: Bearer <API_KEY>.

Request Body · application/json

Only one of image_url and data_url can be submitted. image_url can also be data:image/...;base64,..., which the platform treats as an inline image. When using a remote URL, the address must be an http(s):// address that the platform can download publicly (both http and https are supported), and it must not depend on cookies, Referer, a login page, or a browser session, and must remain valid while the platform processes it.

A remote image_url first goes through the platform's fast relay cache and is then mirrored by the asset library; ordinary images can usually be completed within seconds. The platform also supports inline images: you can write the value of image_url as data:image/...;base64,..., or use the separate data_url field. For images already available locally on the client, inline submission can save one additional external download.

data_url uploads the entire image as base64 (about 1.33 times the original size); use it only when the image truly cannot be provided at a public address: for example, when the image is behind an address that requires login, on an internal network, or available only as a local file. When using data_url, upload time depends on image size and caller bandwidth; the platform writes the image to short-term temporary relay storage rather than permanent platform asset storage. After the asset library finishes mirroring and the asset enters Active, previews preferentially use the preview_url returned by the asset library, and temporary files are cleaned up automatically by the relay service.

Image assets can only be submitted to virtual groups; assets in real groups are produced by the portrait QR code authorization flow.

request_id can also be submitted through the Idempotency-Key request header. When the same account submits repeatedly with the same request_id, the platform returns the same asset created on the first success and does not create the upstream asset again. When request_id is not submitted, the platform automatically generates a stable value from the account, group, title, and original image payload; retries with the same image and title can still be reused safely.

Request Example

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

When using a local image, submit data_url instead:

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

If the client prefers to keep using the image_url field, it can also submit an inline image directly:

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

Response Parameters

Response Body

{
  "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": "图片素材已提交"
}

A successful submission only means the asset has been accepted; you still need to query the status before submitting a video task.

Error Responses

Query a Single Asset

Authentication

Authorization: Bearer <API_KEY>.

Request Parameters · path

Request Example

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

Response Parameters

Values and handling of data.asset.status:

Response Body

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

A review failure also returns HTTP 200, with the reason in error_message:

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

Error Responses

Query the Asset List

Authentication

Authorization: Bearer <API_KEY>.

Request Parameters · query

Request Example

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

Response Parameters

Response Body

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

Error Responses