Saltar a la navegación
API de archivos

create asset

Register a media URL as a reusable asset and get back its id. Use the id in generation inputs (input[].assetId) or as a voice clone sample. To upload a local file, first request a presigned URL via POST /v2/assets/upload, PUT the file there, then register the returned url here. Registration verifies the upload happened and enforces plan limits on the actual file size.

projectId is optional. When provided it must reference a project in your organization — a stale or foreign id is rejected with a 422 and errorCode project_not_found; omit the field if you don’t need the asset attached to a project.

A link to a single TikTok, Instagram, Facebook, or YouTube video is imported instead of registered. The response is 409 import_in_progress until the video is downloaded; send the same request again after Retry-After to get the imported VIDEO asset, named after the video. A failed import returns 422 import_failed; check the message or upload the file instead. A 429 means the concurrent or daily import limit was reached; follow Retry-After. Link imports return 403 import_not_enabled when unavailable for your account and 503 import_unavailable when temporarily unavailable. See Asset Uploads.

Autenticación

x-api-keystring
Autenticación con clave API vía encabezado

Solicitud

This endpoint expects an object.
urlstringRequerido

The public URL of the media to register — e.g. the url returned by POST /v2/assets/upload. Registration verifies the upload happened and enforces plan limits on the actual file size. A link to a single TikTok, Instagram, Facebook, or YouTube video is imported as a VIDEO asset instead.

typeenumRequerido
The type of asset.
Valores permitidos:
namestringOpcional
An optional display name for the asset.
visibilityenumOpcionalValor predeterminado: USER
Who can see the asset. Defaults to USER.
Valores permitidos:
projectIdstringOpcional

Optionally attach the asset to a project (created via POST /v2/projects) so it appears in Studio under that project’s media. Must reference a project in your organization — otherwise the request is rejected with 422.

inputTypeenumOpcional
The source of the asset.
thumbnailUrlstring or nullOpcional
Optional thumbnail URL for the asset.
sizelongOpcional
File size in bytes.
formatstringOpcional
File format or extension.
durationSecondsdoubleOpcional
Media duration in seconds.
widthintegerOpcional
Width in pixels for video or image assets.
heightintegerOpcional
Height in pixels for video or image assets.
contentSha256stringOpcionalformat: "^[a-f0-9]{64}$"

SHA-256 digest of the file’s bytes, as 64 lowercase hex characters.

Respuesta

Asset registered successfully
idstring
A unique identifier for an asset.
createdAtdatetime
The date and time the asset was created.
updatedAtdatetime
The date and time the asset was last updated.
typeenum
The type of asset file.
Valores permitidos:
visibilityenum
Visibility scope for the asset.
Valores permitidos:
namestringOpcional
The filename of the asset.
urlstringOpcional
The URL to access the asset media.
sizelongOpcional
File size in bytes.
formatstringOpcional

File format/extension (e.g., “mp4”, “wav”).

inputTypeenumOpcional
The source type of the asset.
durationSecondsdoubleOpcional

Duration of the media in seconds (for audio/video).

thumbnailUrlstringOpcional
URL to the asset's thumbnail image.
widthintegerOpcional

Width in pixels (for video/image).

heightintegerOpcional

Height in pixels (for video/image).

projectIdstringOpcional
The id of the project this asset is attached to, or null when it belongs to no project.
proxyPathstring or nullOpcional
Stable API proxy path for authenticated media playback.

Errores

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
409
Link Import IN Progress Error
422
Unprocessable Entity Error
429
Link Import Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error