Create a video 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/CreateAsset

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

Add a video to an existing group. The returned ID can be used by supported Seedance workflows after processing.

Field	Type	Required	Description	Example
GroupId	string	Yes	Target asset group ID.	group-20260320141746-zsf6b
AssetType	Video	Yes	Must be Video.	Video
URL	string	Yes	Public video URL. Video Base64 is not accepted. Use MP4 or MOV, 2–30 seconds, 24–60 FPS, 300–6000 px on each side, 0.4–2.5 aspect ratio, 480p/720p/1080p/4K, 407696–2086876 total pixels, and no more than 200 MB.	https://example.com/video.mp4
file	binary	No	Multipart alternative to URL with the same video constraints.	video.mp4
Name	string	No	Display/search name, up to 64 characters.	scene-clip
model	string	Yes	Use volc-asset-video for the standard route or volc-asset-video-nsfw for the separately authorized sensitive-content route.	volc-asset-video
ProjectName	string	No	Project name. It must match the target group; defaults to default.	default

JSON example:

JSON

{
  "model": "volc-asset-video",
  "GroupId": "group-20260320141746-zsf6b",
  "Name": "scene-clip",
  "AssetType": "Video",
  "URL": "https://example.com/video.mp4",
  "ProjectName": "default"
}

multipart/form-data example:

bash

curl --request POST https://modelflare.dev/volc/asset/CreateAsset \
  --header "Authorization: Bearer YOUR_MODELFLARE_API_KEY" \
  --form "model=volc-asset-video" \
  --form "GroupId=group-20260320141746-zsf6b" \
  --form "file=@video.mp4"

Response

The video has entered asynchronous processing. Poll GetAsset until Status is Active or Failed. There is no upload-time SLA; a typical video takes about 9–12 seconds, while a busy review queue can take roughly 10 seconds to 2 minutes.

Field	Type	Required	Description	Example
Id	string	Yes	Asset ID. Use asset://<ID> only after the status is Active.	asset-20260528140922-d9646

Response example:

JSON

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

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.