Private Asset Library — API Guide

For face / character / scene reference asset management and video generation with the Seedance 2.0 model family.

0. Overview

PiAPI's Private Asset Library lets you upload face photos, character reference images, video clips, or audio references once, obtain a stable asset_id, and then reference it as asset://<asset_id> in your Seedance video-generation tasks. Once an asset reaches the Active state, every subsequent generation that references it benefits from stable character consistency across shots and skips re-processing of that asset on every request.

Typical use cases:

Multi-shot short films where the same character appears across cuts

Multiple characters in the same scene that need separate references in the prompt

Workflows where you want assets vetted up-front instead of re-checked on every generation

Asset lifecycle:

Upload → the service asynchronously fetches the URL and ingests the file (usually seconds to a few minutes)

Status transitions: Processing → Active (usable) or Failed (fetch failed / asset rejected / multi-face violation)

Idle assets are garbage-collected after the per-plan TTL; calls to list / get / Seedance references refresh last_used_at

Explicit deletion is also supported; when the last asset of a group is deleted, the group itself is cleaned up automatically

1. Authentication

All endpoints use the X-API-Key HTTP header. Asset endpoints additionally require an account plan ≥ hobbyist.

2. Quota and TTL (per plan)

Plan	Max Assets	TTL (auto-purged when idle)
hobbyist	50	3 days
developer	200	7 days
premium	500	15 days
enterprise	1000	15 days

Assets in the Failed state do not count toward your quota.

3. Upload Assets

3.1 Single upload

Request fields:

Field	Required	Description
`url`	✅	Publicly reachable URL. Must remain reachable for at least 24 hours so the service can fetch it asynchronously.
`asset_type`	optional	`Image` / `Video` / `Audio`. Inferred from the URL suffix when omitted.
`name`	optional	Display name for the asset. Defaults to the last path segment (e.g. `example1.png`).

Supported types and constraints:

Type	Extensions	Size limit	Other
Image	jpeg / jpg / png / webp / bmp / tiff / gif / heic / heif	< 30 MB	Aspect ratio (0.4, 2.5); width/height (300, 6000) px
Video	mp4 / mov	≤ 50 MB	480p / 720p / 1080p; 2–15 s; 24–60 FPS
Audio	mp3 / wav	≤ 15 MB	2–15 s

Response (HTTP 202):

{
  "asset_id": "asset-20260607154123-6nxk8",
  "status": "Processing",
  "upload_at": "2026-06-07T15:41:23Z",
  "expires_at": "2026-06-22T15:41:23Z"
}

3.2 Batch upload (up to 5 items)

Response (HTTP 202):

{
  "total": 4,
  "success": 4,
  "failed": 0,
  "results": [
    {"asset_id": "asset-20260607154123-aaaa1", "status": "Processing"},
    {"asset_id": "asset-20260607154124-bbbb2", "status": "Processing"},
    {"asset_id": "asset-20260607154124-cccc3", "status": "Processing"},
    {"asset_id": "asset-20260607154125-dddd4", "status": "Processing"}
  ]
}

Individual failures do not block the batch; failed items carry an error field describing the cause.

4. Query Asset Status

Newly uploaded assets start in Processing. Poll until they reach Active before referencing them in a generation request.

4.1 List (with quota info)

Query parameters:

Param	Default	Description
`page`	1	Page number
`size`	20	Page size (≤ 100)
`status`	all	Comma-separated subset, e.g. `active,processing,failed`
`order`	`-last_used_at`	Sort key; `-` prefix for descending order

Response:

{
  "items": [
    {
      "asset_id": "asset-20260607154123-aaaa1",
      "name": "char-female",
      "asset_type": "Image",
      "status": "Active",
      "url": "https://your-cdn.com/example1.png",
      "last_used_at": "2026-06-07T15:41:23Z",
      "expires_at": "2026-06-22T15:41:23Z",
      "created_at": "2026-06-07T15:41:23Z"
    }
  ],
  "total": 4,
  "page": 1,
  "size": 20,
  "quota": {
    "used": 4,
    "limit": 500,
    "ttl_days": 15
  }
}

The url field echoes back the original URL you uploaded with — keep it persistent if you want it as a thumbnail preview source.

4.2 Single asset details

Calling this also refreshes last_used_at (preventing LRU purge).

Response:

{
  "asset_id": "asset-20260607154123-aaaa1",
  "name": "char-female",
  "asset_type": "Image",
  "status": "Active",
  "url": "https://your-cdn.com/example1.png",
  "last_used_at": "2026-06-07T15:50:00Z",
  "expires_at": "2026-06-22T15:50:00Z",
  "created_at": "2026-06-07T15:41:23Z"
}

When status=Failed, the response carries an error object with details:

{
  "asset_id": "asset-...",
  "status": "Failed",
  "error": {
    "code": "ImageFormatNotSupported",
    "message": "Image format heif is not supported by current version"
  }
}

5. Delete Assets

5.1 Single delete

Response: HTTP 204 (empty body).

5.2 Batch delete

Response:

{
  "deleted": 4,
  "failed": 0,
  "results": [
    {"asset_id": "asset-...aaaa1", "status": "deleted"},
    {"asset_id": "asset-...bbbb2", "status": "deleted"},
    {"asset_id": "asset-...cccc3", "status": "deleted"},
    {"asset_id": "asset-...dddd4", "status": "deleted"}
  ]
}

6. Generate Video with Assets (Seedance)

The bridge between the asset library and Seedance: reference your assets as asset://<asset_id> instead of a regular URL.

6.1 Important constraints

✅ Supported task types: seedance-2-less-restriction (std) and seedance-2-fast-less-restriction (fast)

❌ Not supported: strict variants (seedance-2 / seedance-2-fast); requests carrying asset:// references will fast-fail. Use the corresponding -less-restriction variant instead.

✅ In the prompt, reference assets using the literal Image 1 / Image 2 / Video 1 / Audio 1 notation. The index matches the position inside image_urls / video_urls / audio_urls.

✅ The alternative @image1 / @video2 / @audio1 reference syntax is also accepted; the service rewrites it to the canonical form automatically.

6.2 Submit a task

Response:

{
  "code": 200,
  "data": {
    "task_id": "3f5ab17a-0b2e-44a3-b31d-3e6075e2b974",
    "status": "pending"
  },
  "message": "success"
}

On submission the service validates:

Every asset:// reference belongs to the calling account

Each referenced asset has status=Active

task_type is one of the -less-restriction variants

If any check fails the request is rejected before being billed.

6.3 Poll task status

In-progress response:

{
  "code": 200,
  "data": {
    "task_id": "3f5ab17a-...",
    "status": "processing"
  }
}

Completed response:

{
  "code": 200,
  "data": {
    "task_id": "3f5ab17a-...",
    "status": "completed",
    "input": {
      "prompt": "Cinematic. Photo realistic. A cyber female Image 1 stands in courtyard Image 3. Cyber warrior Image 2 next to her. Cyber boss Image 4 emerges. 5s scene.",
      "image_urls": ["asset://asset-...aaaa1", "asset://asset-...bbbb2", "asset://asset-...cccc3", "asset://asset-...dddd4"],
      "aspect_ratio": "16:9",
      "duration": 5,
      "resolution": "720p"
    },
    "output": {
      "video": "https://img.theapi.app/ephemeral/026610ac-5b23-4105-ac06-30f2044f304d.mp4"
    },
    "meta": {
      "usage": {
        "type": "point",
        "consume": 10000000
      }
    }
  }
}

The video URL is valid for 24 hours — download or consume it within that window.

6.4 Status state machine

status	Meaning
`pending`	Accepted, queued for scheduling
`processing`	Generation in progress
`completed`	Success; `output.video` is ready
`failed`	Failure; inspect `error.message`

7. End-to-end example (Python)

8. Common errors

HTTP	Message	Meaning / Resolution
400	`invalid request: 'url' is required`	Missing `url` field on upload
400	`unsupported asset_type: xxx`	The file extension is not in the whitelist
400	`quota exceeded: plan hobbyist allows 50 assets, currently 50`	Quota full — delete old assets or upgrade plan
403	`asset not owned by this account`	The referenced `asset_id` belongs to another account
404	`asset not found`	Wrong `asset_id` or already deleted
409	`asset still processing`	Wait a few seconds and retry
422	`asset:// references are only allowed on -less-restriction task types`	Switch `task_type` to `seedance-2-(fast-)less-restriction`
422	`asset xxx status=Failed`	The referenced asset failed processing; GET its details to see why

9. Best practices

URL persistence — the URL you upload must remain reachable until ingestion completes. Once an asset has reached status=Active the original URL is no longer required, but keeping it alive for at least 24 hours is the safe default.

Asset reuse — upload once and reference unlimited times. Every reference refreshes last_used_at, so frequently-used assets never hit the LRU TTL.

Prompt reference order — Image 1 maps to image_urls[0], Image 2 to image_urls[1], etc. Indexes beyond the array length are ignored by the model.

Mixing media types — image_urls, video_urls, and audio_urls can all appear in the same request, with the prompt referencing each via Image N / Video N / Audio N.

Quota visualization — every list response contains quota.{used, limit, ttl_days}. Surface this on your dashboard so users know when they are close to the limit.

Failed-asset hygiene — Failed assets do not count toward quota, but they still clutter the list. Delete them explicitly to keep the view clean.

Change log

2026-06-07: Initial release

Private Asset Library

Private Asset Library — API Guide#

0. Overview#

1. Authentication#

2. Quota and TTL (per plan)#

3. Upload Assets#

3.1 Single upload#

3.2 Batch upload (up to 5 items)#

4. Query Asset Status#

4.1 List (with quota info)#

4.2 Single asset details#

5. Delete Assets#

5.1 Single delete#

5.2 Batch delete#

6. Generate Video with Assets (Seedance)#

6.1 Important constraints#

6.2 Submit a task#

6.3 Poll task status#

6.4 Status state machine#

7. End-to-end example (Python)#

8. Common errors#

9. Best practices#

Private Asset Library — API Guide

0. Overview

1. Authentication

2. Quota and TTL (per plan)

3. Upload Assets

3.1 Single upload

3.2 Batch upload (up to 5 items)

4. Query Asset Status

4.1 List (with quota info)

4.2 Single asset details

5. Delete Assets

5.1 Single delete

5.2 Batch delete

6. Generate Video with Assets (Seedance)

6.1 Important constraints

6.2 Submit a task

6.3 Poll task status

6.4 Status state machine

7. End-to-end example (Python)

8. Common errors

9. Best practices