Assets
Store media files once and reference them across generation requests.
The Assets API lets you store images, videos, and audio files in APIFRAME's storage. Once created, reference them in generation requests using asset://{assetId} URIs instead of direct URLs.
Asset URIs work in every media URL field across all generation endpoints — image, video, and music generation, plus the edit, upscale, and background-removal endpoints. The API resolves each asset:// reference to its stored URL before dispatching the job, so they work with every model regardless of which provider serves it.
This is especially useful for multimodal references (e.g. Seedance's reference_image_urls, reference_video_urls, reference_audio_urls, start_image, end_image) and whenever the same reference media is reused across many jobs. Unlike /v2/uploads files, assets do not expire.
Create an asset
POST /v2/assets/create
Provide a public URL; APIFRAME downloads the file, verifies its content type, and stores it. Creation is synchronous — the asset is ready to use as soon as the request returns.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | Public https URL of the media file (max 25 MB for images/audio, 50 MB for video) |
type | string | Yes | Media type: "image", "video", or "audio" — must match the actual file contents |
Response
Status: 201 Created
{
"assetId": "3f9d2a71-58f0-4f4e-9c6b-2f1f7d0a8b34",
"status": "Active",
"url": "https://cdn2.apiframe.ai/assets/..."
}Get an asset
GET /v2/assets/:assetId
Returns the stored asset. Only assets created by your team are accessible.
Response
Status: 200 OK
{
"status": "Active",
"url": "https://cdn2.apiframe.ai/assets/...",
"errorMsg": null,
"type": "image",
"contentType": "image/png",
"byteSize": 245123,
"createdAt": "2026-08-12T00:00:00.000Z"
}Usage in generation requests
Use asset://{assetId} in any field that accepts media URLs:
{
"prompt": "A person dancing to upbeat music",
"model": "seedance-2",
"seedanceParams": {
"reference_audio_urls": ["asset://3f9d2a71-58f0-4f4e-9c6b-2f1f7d0a8b34"],
"reference_image_urls": ["asset://a1b2c3d4-0000-4000-8000-000000000000", "https://example.com/photo.jpg"]
}
}You can mix asset:// URIs with direct URLs in the same request. Referencing an asset that does not exist (or belongs to another team) fails the request with a 400 before any credits are deducted.
Code examples
# 1. Create an asset (synchronous — ready when the response returns)
curl -X POST https://api.apiframe.ai/v2/assets/create \
-H "X-API-Key: afk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/reference.mp4", "type": "video"}'
# 2. Use it in a generation request
curl -X POST https://api.apiframe.ai/v2/videos/generate \
-H "X-API-Key: afk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"prompt": "A cinematic scene inspired by the reference", "model": "seedance-2", "seedanceParams": {"reference_video_urls": ["asset://YOUR_ASSET_ID"]}}'import requests
headers = {
"X-API-Key": "afk_your_api_key_here",
"Content-Type": "application/json",
}
# 1. Create an asset (synchronous)
resp = requests.post(
"https://api.apiframe.ai/v2/assets/create",
headers=headers,
json={"url": "https://example.com/reference.mp4", "type": "video"},
)
asset_id = resp.json()["assetId"]
# 2. Use in generation
requests.post(
"https://api.apiframe.ai/v2/videos/generate",
headers=headers,
json={
"prompt": "A cinematic scene inspired by the reference",
"model": "seedance-2",
"seedanceParams": {
"reference_video_urls": [f"asset://{asset_id}"],
},
},
)const headers = {
"X-API-Key": "afk_your_api_key_here",
"Content-Type": "application/json",
};
// 1. Create an asset (synchronous)
const createResp = await fetch("https://api.apiframe.ai/v2/assets/create", {
method: "POST",
headers,
body: JSON.stringify({ url: "https://example.com/reference.mp4", type: "video" }),
});
const { assetId } = await createResp.json();
// 2. Use in generation
await fetch("https://api.apiframe.ai/v2/videos/generate", {
method: "POST",
headers,
body: JSON.stringify({
prompt: "A cinematic scene inspired by the reference",
model: "seedance-2",
seedanceParams: {
reference_video_urls: [`asset://${assetId}`],
},
}),
});