API · Assets · Create a persistent asset from a remote URL or a local file
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_urlis the stored CDN file and ready to use."failed": the import failed;import_errorsays why (http_<status>,timeout,unreachable,not_an_image,import_failed)."pending"/"importing": still importing,file_urlis 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
Header authentication of the form Api-Key <token>
Bearer authentication of the form Bearer <token>, where token is your auth token.
Request
Response
Asset created — processing asynchronously
