API · Assets
Import an asset URL
Copy a public HTTPS media file into your workspace.
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/imports — application/json. The URL must be publicly reachable over HTTPS. Redirects and private-network addresses are rejected.
| Parameter | Required | Type | Default / options | Description |
|---|---|---|---|---|
| kind | Yes | string | image | video | audio | Expected media kind. |
| url | Yes | string (URI) | — | Public HTTPS media URL, up to 20 MiB. |
| modelKey | No | string | — | Optional model metadata. |
curl "https://platform-backend.topview.ai/api/v1/media/imports" -H "Authorization: Bearer $TOPVIEW_API_PLATFORM_KEY" -H "Content-Type: application/json" -d '{"kind":"image","url":"https://YOUR_PUBLIC_HOST/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"
}
}