Skip to content

Asset Management API

The Asset Management API lets your application manage assets (images, videos, audio) and asset groups programmatically. It uses the same API key issued for your account — there is no separate key to provision. If your account has the asset feature enabled, your existing sk-... key works here too.

It is zero-config: you don't pass any project or storage identifiers. Your account already determines where assets live, so most calls need no parameters at all.

Access — this feature is opt-in

The Asset Management API provides the reference assets used by SIRAYA Seedance 2.0 and SIRAYA Seedance 2.0 fast (reference-guided video generation). It is not enabled by default for all customers — if you need it, contact us to have it turned on for your account. Until it's enabled, calls return 403 FEATURE_INACTIVE.

If you're integrating faces into Seedance 2.0 (face swap, character consistency), see the Using Assets with Seedance 2.0 guide — it covers the required upload-first workflow, use cases, and the Platform UI walkthrough.

Asset Groups are a restricted, advanced feature

The Group API (/assets/groups*) is a more advanced capability that is not available to every account — even on request. It is granted selectively (VIP accounts); other accounts receive 403 TIER_FORBIDDEN. The standard single-group asset workflow needs no groups, so most integrations never use these endpoints.

Why Use the Asset Management API?

  • Reuse your existing key: The same sk-... key you use for the LLM gateway works here.
  • Zero-config storage: Where assets live is resolved from your account automatically — you never pass a project or bucket.
  • Async, durable uploads: Upload a file or a public URL and poll until the asset is active.

Base URL

https://console-api.siraya.ai/extapi/v1

API Methods

Assets

Method Endpoint Description
List Assets GET /assets List your assets with filtering, sorting, and pagination.
Upload an Asset POST /assets Upload a file or a public URL (async → 202).
Get an Asset GET /assets/{assetId} Fetch an asset and a short-lived download URL.
Delete an Asset DELETE /assets/{assetId} Permanently delete an asset.

Asset Groups — restricted (VIP only)

Granted selectively and not available to every account, even on request. Accounts without it receive 403 TIER_FORBIDDEN.

Method Endpoint Description
List Groups GET /assets/groups List your asset groups.
Create a Group POST /assets/groups Create a new asset group.
Update a Group PUT /assets/groups/{groupId} Rename or re-describe a group.
Delete a Group DELETE /assets/groups/{groupId} Delete an asset group.

Authentication

Send your API key as a Bearer token on every request:

Authorization: Bearer sk-abc12345...xyz789

The key is never stored or decrypted — the server hashes the key you send, checks it is active (not expired / not revoked), and resolves the owning account. A revoked or expired key stops working on this surface immediately.

Situation HTTP error.code
Missing / malformed Authorization header 401 UNAUTHORIZED
Invalid / expired / revoked key 401 UNAUTHORIZED
Account has no active asset entitlement 403 FEATURE_INACTIVE
Asset / group not owned by your account 404 NOT_FOUND
Plan not sufficient (normal account hitting a group endpoint) 403 TIER_FORBIDDEN
Request validation failed 400 INVALID_INPUT

Response Envelope

All responses use a common envelope.

{ "isSuccess": true, "data": { /* ... */ } }

{
  "isSuccess": true,
  "data": { "items": [ /* ... */ ] },
  "pagination": { "page": 1, "pageSize": 20, "total": 137, "totalPages": 7 }
}

{ "isSuccess": false, "error": { "code": "FEATURE_INACTIVE", "message": "..." } }

Plans

Your plan determines whether you work with a single account group or many.

Capability Normal VIP
Asset list / upload / get / delete ✅ no groupId needed — your account's group is used automatically ✅ groupId optional; defaults to your account's group, or pass one to target a specific group
Group endpoints (/assets/groups*) ❌ 403 TIER_FORBIDDEN ✅ list / create / update / delete your groups

A Normal account simply calls the asset endpoints with no group parameter at all. A VIP account can additionally organise assets across multiple groups.

Note: assetId is returned when you list or upload an asset; use it to fetch or delete that asset. groupId is plan-dependent — Normal accounts never send it (a sent value is ignored), and your account is provisioned with a group when it is set up.