API Reference

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, SIRAYA Seedance 2.0 fast, SIRAYA Seedance 2.0 mini, and SIRAYA Seedance 2.5 (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 or 2.5 (face swap, character consistency), see the Using Assets with Seedance 2.0 & 2.5 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`
The upstream service is rate limiting requests	429	`UPSTREAM_RATE_LIMIT`
The upstream service timed out	504	`UPSTREAM_TIMEOUT`
The upstream service rejected SIRAYA's own credentials	502	`UPSTREAM_UNAUTHORIZED`
The upstream service is unavailable, returned an unusable response, or rejected the request for a reason SIRAYA cannot classify	502	`UPSTREAM_UNAVAILABLE`

See Upstream errors and retries for how to handle the four UPSTREAM_* codes.

Response Envelope

All responses use a common envelope.

SuccessSuccess (paginated list)Error

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

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

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

Upstream errors and retries

Assets are stored and checked by an upstream service. When a call to it fails, the API returns one of four UPSTREAM_* codes. All four carry the same message, upstream service error, so branch on error.code, not on the message.

`error.code`	HTTP	What to do
`UPSTREAM_RATE_LIMIT`	429	Safe to retry. Back off exponentially (for example 1 s, 2 s, 4 s, up to a few attempts) and slow your request rate.
`UPSTREAM_TIMEOUT`	504	Retry with the same backoff. For an upload, list your assets before retrying: the first attempt may already have created the asset, and a blind retry would duplicate it.
`UPSTREAM_UNAVAILABLE`	502	Retry up to 2–3 times with backoff. If the same file keeps failing while other files upload normally, treat it as a problem with the file — an upstream rejection of the file's format, frame rate, resolution or size is reported with this code too — and try a re-encoded copy before contacting support.
`UPSTREAM_UNAUTHORIZED`	502	Not caused by your API key, and retrying will not help. Contact us and include the time of the request and the endpoint.

Note

UPSTREAM_UNAVAILABLE does not tell you whether the upstream service was down or rejected the file, because the API does not currently separate the two. If a retry does not clear it, send us the time of the request, the endpoint and, for an upload, the file's format, resolution, frame rate and duration.

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.