Skip to navigation

API · Assets · Create a persistent asset from a remote URL or a local file

View as Markdown

Create a persistent workspace asset from a remote url the server downloads.

To add a file from your own machine, do not call this tool — use signAssetUpload, PUT the bytes to the signed URL it returns, then registerAsset. (path exists for the smp command-line tool only; it cannot work over MCP, where the file is on a different machine.)

Processing is async (download + thumbnail via Celery), usually a few seconds. The returned UUID is usable immediately in data.assets[], but the 201 response is not the file: its thumbnail is empty and not usable, and import_state is pending. Poll getAsset and read its import_state:

  • "stored": file_url is the stored CDN file and ready to use.
  • "failed": the import failed; import_error says why (http_<status>, timeout, unreachable, not_an_image, import_failed).
  • "pending" / "importing": still importing, file_url is empty until stored. Check again on a later step; if it is still not stored after about a minute, treat it as failed.

Common use: persist a transient AI-generated image (from generateImage) so it can be saved to a project, published, or opened in the editor.

Authentication

AuthorizationApi-Key

Header authentication of the form Api-Key <token>

OR
AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects any.
anyRequired
OR
anyRequired

Response

Asset created — processing asynchronously

Errors

400
Bad Request Error
401
Unauthorized Error