API · Assets
Upload an asset
Upload a local reference image, video or audio file for model inputs.
Authentication and limits
Use a Platform Bearer API key with models:generate permission. Assets belong to the key’s workspace. Maximum file size is 20 MiB; audio and video must be at most 300 seconds. Model-specific input limits still apply. Image inputs accept PNG/JPEG/WebP. Seedance requires 300–6000 px per side and aspect ratio 0.4–2.5; MiniMax H3 requires 256–5760 px per side and aspect ratio 0.4–2.5; Wan 3.0 requires 240–8000 px per side, longest/shortest side at most 8, no PNG alpha channel, and at most 20,000,000 bytes. Model-specific checks run before quoting, even for an existing Asset. See the model parameter table for all limits. Uploads and imports do not reserve generation funds. The workspace upload allowance is 100 assets or 1 GiB in a rolling 24-hour window. Read operations do not consume that allowance.
Input schema
POST /api/v1/media/files — multipart/form-data. Let your HTTP client set the multipart boundary.
| Parameter | Required | Type | Default / options | Description |
|---|---|---|---|---|
| kind | Yes | string | image | video | audio | Media kind matching the file. |
| file | Yes | binary | — | Non-empty local file, up to 20 MiB. |
| modelKey | No | string | — | Optional model metadata; does not override model input limits. |
curl "https://platform-backend.topview.ai/api/v1/media/files" -H "Authorization: Bearer $TOPVIEW_API_PLATFORM_KEY" -F "kind=image" -F "file=@reference.png"Output schema
Upload, import and get return the asset inside data. Additional metadata may be present.
| Field | Type | Description |
|---|---|---|
| data.id | string | Asset ID; save it to retrieve the asset later. |
| data.kind | string | image, video or audio. |
| data.content_type | string | Detected media MIME type. |
| data.size | integer | File size in bytes (also returned as byte_size). |
| data.reference | string | Workspace-owned pfmedia:ID reference. |
| data.download_url | string | Temporary signed HTTPS URL. Retrieve the asset again to refresh it. |
| data.display_name | string | null | Display name; uploaded files use their filename. |
{
"data": {
"id": "ASSET_ID",
"kind": "image",
"content_type": "image/png",
"size": 12345,
"reference": "pfmedia:ASSET_ID",
"download_url": "https://media.example.com/signed-image.png",
"display_name": "reference.png"
}
}Use the asset
Pass data.download_url in the model’s documented image or reference field. Retrieve a fresh URL before use if it has expired. Use Assets in the console to rename or delete files; these mutations are not exposed to public API keys.