Images
Stock-photo search, AI cover generation and server-side image copying for the campaign builder, plus an allowlisted image proxy.
Proxy an allowlisted image
Streams an image from the platform's CDN or images.unsplash.com, for local development. Public. The upstream body and Content-Type are passed through with a 24-hour cache header; the upstream status code is not, so an upstream error page also arrives as 200.
Parameters
Query Parameters
"uri"Responses
The upstream image
Which image features are available
Search stock photos
Searches Unsplash for landscape photos. Requires a bearer session. When a photo is chosen, call POST /images/track-download with its downloadLocation, as Unsplash's terms require.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Query Parameters
1113020Responses
Search results
Generate a cover image with AI
Generates a landscape campaign cover from a prompt (the first 500 characters are used, wrapped in a fixed style prompt). Requires a bearer session.
With the default gpt-image-* model the image is stored on the platform CDN immediately and persisted is true; that path is also gated by features.image_uploads and answers 403 when the flag is off. With a dall-e-* model the URL is OpenAI's temporary one (persisted: false) and should be copied with POST /images/save-from-url.
Limited to 10 generations an hour and 30 a day per user; past either limit the answer is 429 with Retry-After. Errors from the image provider are not passed through: a prompt the provider refuses answers 400, a temporarily unavailable provider 503, and any other provider failure 502, each with a generic message.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Request Body
Responses
Generated image
Make a photo square with AI
Re-renders a photo as a square without cutting anyone out of it: the people and the setting are kept and the rest of the frame is composed to fill the square. A photo that is already square is rendered again, so calling twice gives a second rendering. Requires a bearer session.
The square comes back as base64 and nothing is stored. Upload it through the normal image upload to use it as a cover.
Shares the limits of POST /images/generate: 10 an hour and 30 a day per user; past either limit the answer is 429 with Retry-After. Errors from the image provider are not passed through: a photo the provider refuses answers 400, a temporarily unavailable provider 503, and any other provider failure 502, each with a generic message.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Request Body
Responses
The square photo
Record a stock-photo selection
Tells Unsplash a photo was chosen, as its API guidelines require. Pass the downloadLocation from GET /images/search. Never fails the caller's action: a failed ping answers 200 with tracked: false. Requires a bearer session.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Request Body
Responses
Tracking outcome
Copy a generated image to the CDN
Downloads an AI-generated image from OpenAI's image storage and stores it on the platform CDN, returning the permanent URL. A URL already on the platform CDN is returned unchanged. Requires a bearer session and the features.image_uploads flag.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Request Body
Responses
Stored image