Asset tools

Tools for browsing, retrieving, and generating assets (images, videos, audio) in the organization's asset library.

get-assets

Search and retrieve assets from the library with optional filters.

Use search for natural-language queries

This tool supports server-side natural-language search — pass what the user asked for (e.g. "images of old people", "beach sunset", "hotel lobby at night") directly into the search parameter. It runs a semantic search over each asset's AI-generated visual description, name, and tags. Don't call get-assets without search and then manually scan the returned visualDescription fields yourself — the server-side search is more accurate and avoids paging through the entire library.

Parameters

Parameter	Type	Required	Description
search	string	No	Natural-language search query, e.g. "images of old people". Matches semantically against name, visual description, and tags — pass user phrasing straight through instead of filtering results yourself
collectionId	string	No	Filter by collection ID
tags	string	No	Comma-separated tag IDs (use get-tags to get IDs)
uncategorized	boolean	No	Only return assets without a collection
assetType	string	No	Filter by type: image, audio, or video
insertProductId	string	No	Filter by associated product ID
limit	number	No	Page size, 1–200 (default 50, newest first)
offset	number	No	Number of assets to skip for pagination (default 0)

Ordering with search

When search is provided, results are ranked by relevance (best match first) instead of newest first.

Response

Field	Type	Description
assets	array	List of assets (this page)
assets[].id	string	Unique asset identifier
assets[].name	string	Asset name
assets[].assetUrl	string | null	Full-resolution URL
assets[].previewUrl	string | null	Preview/thumbnail URL
assets[].status	string	Processing status
assets[].visualDescription	string | null	AI-generated description
assets[].assetType	string	image, audio, or video
assets[].collection	object | null	{ name } if assigned
assets[].insertProducts	array	[{ name }], linked products
assets[].tags	array	[{ name }], assigned tags
assets[].createdAt	string	ISO date
assets[].updatedAt	string	ISO date
returned	number	Number of assets in this page
limit	number	Page size used
offset	number	Offset used
hasMore	boolean	true if the page was full; call again with offset += limit

Pagination

Large libraries are paged to keep responses fast. When hasMore is true, request the next page by increasing offset by limit (e.g. offset: 50, then 100, …).

Example

{
  "tool": "get-assets",
  "arguments": {
    "search": "images of old people",
    "assetType": "image"
  }
}

---

get-asset

Retrieve a single asset by ID with full metadata and relationships.

Parameters

Parameter	Type	Required	Description
id	string	Yes	Asset identifier

Response

Field	Type	Description
asset.id	string	Unique identifier
asset.name	string	Asset name
asset.assetUrl	string | null	Full-resolution URL
asset.previewUrl	string | null	Preview URL
asset.status	string	Processing status
asset.visualDescription	string | null	AI-generated description
asset.assetType	string	image, audio, or video
asset.collection	object | null	{ id, name }
asset.tags	array	[{ id, name, colorScheme }]
asset.createdAt	string	ISO date
asset.updatedAt	string	ISO date

Example

{
  "tool": "get-asset",
  "arguments": {
    "id": "ast_xyz789"
  }
}

---

get-tags

List all tags for the organization, including how many assets each tag has.

Parameters

None.

Response

Field	Type	Description
tags	array	List of tags
tags[].id	string	Tag identifier
tags[].name	string	Tag name
tags[].colorScheme	string	Display color
tags[].assetCount	number	Number of assets with this tag
tags[].createdAt	string	ISO date
tags[].updatedAt	string	ISO date
total	number	Total number of tags

---

generate-asset

Generate a new image using AI. The generated asset is added to the organization's asset library.

Parameters

Parameter	Type	Required	Description
prompt	string	Yes	Description of the image to generate
mode	string	No	Generation mode: stock (generic), product (product-focused), or productContent
productImageType	string	No	For product modes: packaging or content
insertProductIds	string[]	No	Up to 3 product IDs to use as reference (for product modes)

Response

Field	Type	Description
asset.id	string	ID of the generated asset
asset.name	string	Auto-generated name
asset.prompt	string	The prompt used
asset.status	string	Processing status (may be processing initially)
asset.assetType	string	Always image
asset.createdAt	string	ISO date
asset.updatedAt	string	ISO date
message	string	Status message

Example

{
  "tool": "generate-asset",
  "arguments": {
    "prompt": "A modern office workspace with a laptop and coffee, warm lighting, professional photography style",
    "mode": "stock"
  }
}

---

upload-asset

Upload a new image into the organization's asset library so it can be inserted into a design. Provide either a publicly fetchable imageUrl (the server downloads it) or inline base64 data with a mimeType. By default the asset is not filed into any collection (it stays in the library root); pass an optional collectionId to place it in a specific collection. The upload returns a persistent assetUrl.

Supported formats: jpeg, png, gif, webp, svg. Inline base64 uploads are capped at 12 MB; use imageUrl for larger files.

Parameters

Parameter	Type	Required	Description
imageUrl	string	One of imageUrl/base64	Direct URL the server downloads and stores
base64	string	One of imageUrl/base64	Base64-encoded image bytes (a data: prefix is accepted)
mimeType	string	No	MIME type for base64 data, e.g. image/png (default image/png)
name	string	No	Descriptive asset name, e.g. hero-mountains
collectionId	string	No	Existing collection id to file the asset into. Omit to leave it in the library root. Use get-collections to discover ids or create-collection to make a new one

Response

Field	Type	Description
ok	boolean	true on success
asset.id	string	New asset ID
asset.name	string	Stored asset name
asset.assetUrl	string | null	Persistent URL; use this to insert the image
asset.previewUrl	string | null	Preview URL
asset.assetType	string	Always image
asset.status	string	Processing status
note	string	Hint on how to place it in the editor

On failure the tool returns an error string (e.g. unfetchable URL, unsupported type, too large).

Example

{
  "tool": "upload-asset",
  "arguments": {
    "imageUrl": "https://example.com/photo.jpg",
    "name": "campaign-hero"
  }
}

Insert it into a design

After uploading, place the image in a Studio document with studio_call (target it with templateId or designId):

{
  "tool": "studio_call",
  "arguments": {
    "templateId": "<template id>",
    "tool": "studio_create_image",
    "args": { "source": "custom", "customUrl": "<assetUrl from upload-asset>", "name": "campaign-hero" }
  }
}