Get an asset

Availability

This page documents the Modelflare asset-management route. Calls require a valid media API key, an available media channel, and the required permission.

Note

The gateway records provider asset IDs, status, and user ownership. The Castaly local library remains separate from the provider asset namespace.

Endpoint

POST https://modelflare.dev/volc/asset/GetAsset

Authentication

Use a Modelflare API key:

bash

-H "Authorization: Bearer YOUR_MODELFLARE_API_KEY"

Send Idempotency-Key with create, update, and delete requests. Retrying the same key for the same user replays the saved response without repeating the mutation.

Request

Read one asset by ID. Use this route to poll an asynchronous upload until Status is Active or Failed.

Field	Type	Required	Description	Example
Id	string	Yes	Asset ID to query.	asset-20260528140922-d9646

JSON example:

JSON

{
  "Id": "asset-20260528140922-d9646"
}

cURL example:

bash

curl --request POST https://modelflare.dev/volc/asset/GetAsset \
  --header "Authorization: Bearer YOUR_MODELFLARE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "Id": "asset-20260528140922-d9646"
}'

Response

The request succeeded.

Field	Type	Required	Description	Example
Id	string	Yes	Asset ID.	asset-20260528140922-d9646
Name	string	No	Asset name.	character-reference
URL	string	No	Temporary file URL. The documented lifetime is 12 hours; do not persist it as the generation reference.	https://example.com/temporary-asset
AssetType	Image	Video	Audio	No
GroupId	string	No	Owning group ID.	group-20260320141746-zsf6b
Status	Processing	Active	Failed	No
ProjectName	string	No	Project name.	default
CreateTime / UpdateTime	string	No	ISO 8601 timestamps.	2026-05-28T06:09:31Z

Response example:

JSON

{
  "Id": "asset-20260528140922-d9646",
  "Name": "character-reference",
  "AssetType": "Image",
  "GroupId": "group-20260320141746-zsf6b",
  "Status": "Active",
  "ProjectName": "default",
  "CreateTime": "2026-05-28T06:09:22Z",
  "UpdateTime": "2026-05-28T06:09:31Z"
}

Errors

Status	Meaning
400	The request is invalid.
401	The API key is missing or unauthorized.

Error body example (when returned):

JSON

{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed."
  }
}

Image, video, and audio creation are asynchronous. After receiving an asset ID, call GetAsset and use the asset://<ID> reference only when the status is Active.