Assets

Upload a file with POST /v1/uploads. A successful request returns an asset that you can retrieve, bind to a project, and use in editor state.

Upload a file

Send the file bytes as the raw request body, with these headers:

Do not send JSON or multipart form data. Use cURL or an SDK to upload files; uploads cannot be sent from the interactive API reference.

curl --fail-with-body https://api.indream.ai/v1/uploads \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: image/png' \
  -H 'x-file-name: hero.png' \
  --data-binary @hero.png

For a local file, cURL supplies Content-Length from the body size. The SDK upload helpers also set the length for the bytes you provide.

Supported files

Upload images, videos, audio, or .srt, .ass, and .lrc caption files. The content and filename must agree with the declared file type.

Documents, 3D files, JSON files (including Lottie JSON), and unknown formats are not accepted. Unsupported or invalid files return an error; fix the file before retrying. See the upload reference for the complete request and response.

Reference an uploaded asset

An API asset and an editor-state asset are different objects. Map the API's fileUrl to remoteUrl, and fileKey to remoteKey. Include the required metadata for the asset type.

For example, this JavaScript snippet builds an image asset from an upload response. It assumes client is initialized and imageBytes contains the file bytes:

const asset = await client.uploads.upload(imageBytes, {
  filename: 'hero.png',
  contentType: 'image/png',
})
if (asset.width == null || asset.height == null || asset.size == null) {
  throw new Error('The uploaded image is missing its dimensions or size.')
}
const imageAsset = {
  id: 'hero',
  type: 'image',
  filename: asset.filename,
  size: asset.size,
  mimeType: asset.mimetype,
  width: asset.width,
  height: asset.height,
  remoteUrl: asset.fileUrl,
  remoteKey: asset.fileKey,
}

Store this object under editorState.assets.hero. An image item references it with assetId: "hero"; the item must also appear in a track. This local key is separate from the API's assetId. Validate the complete state before saving or exporting it.

Bind assets to a project

Provide x-project-id during upload, or pass projectId to the JavaScript upload helper (project_id in Python). To manage bindings later:

• GET /v1/projects/{projectId}/assets lists the project's assets.
• POST /v1/projects/{projectId}/assets binds an existing assetId.
• DELETE /v1/projects/{projectId}/assets/{assetId} removes the binding.

Retrieve or delete an asset

GET /v1/assets/{assetId} returns the stored asset's metadata and file location. DELETE /v1/assets/{assetId} deletes the asset when reference checks pass.

If deletion returns ASSET_REFERENCED, remove the relevant references before trying again. Unbinding an asset from one project does not guarantee that no other references remain.