Search inspiration

Search Pinterest or Cosmos for images to use as visual references: a style, a composition, a mood, a kind of product shot.

Tool name: search-inspiration.

Search Pinterest or Cosmos for images to use as visual references: a style, a composition, a mood, a kind of product shot. Read-only. Returns image urls to pass as references in generate-creatives, for composition, mood and style only: never reproduce someone else's photo, product, logo or person.

When to use

Find visual references before making ad images when the user wants a look or a style rather than another advertiser's ad (for ads, use search-ad-library). Offer it when the user has no references of their own.

Access

Property	Value
Required scope	`read`
Publishes	No
Read-only	Yes
Destructive	No
Idempotent	Yes
Open world	Yes

Input

Field	Type	Required	Description
`source`	`string`	Yes	pinterest for a wide pool of everyday and product imagery; cosmos for curated, design-led images (editorial, branding, type, art direction). One of `pinterest`, `cosmos`.
`query`	`string`	Yes	What to look for, in a few words: a style, a subject, a mood or a kind of ad ("minimal skincare flat lay", "bold typographic poster"). At most 200 characters.
`limit`	`integer`	No	Images to return, 1-30. Defaults to 12. Minimum 1, maximum 30.
`cursor`	`string`	No	`nextCursor` from the previous page of the same search. At most 500 characters.

Output

Field	Type	Required	Description
`images`	`object[]`	Yes
`nextCursor`	`string \| null`	Yes

REST equivalent

GET /v1/brands/{brandId}/inspiration, Search inspiration. CLI: koast search-inspiration.