Image variables
The image tokens of a campaign's sequence, each one shared image or one image per lead: create, edit, estimate, test and regenerate them.
Path parameters
The endpoints whose path names one of these take it as described here. An endpoint's own table lists a path parameter only when it describes it differently.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
campaignId | path | integer (int64) | required | Id of the campaign. |
variableKey | path | string | required | Key of the image variable, such as hero_image. |
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | The API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy. |
X-Ken-Workspace-Id | header | integer (int64) | optional | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found. |
List a campaign's image variables
/v1/campaigns/{campaignId}/image-variablesimage-variables.list- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
campaign_images feature on your workspace. Until it is on, calls answer 404.Returns the campaign's image variables, ordered by key, in one page: hasMore is always false. Next to data, the response has what you need to set up a variable:
linkHostReady: whether the workspace has a tracking link host. Without one, you cannot create or send an image variable.coverage: how many contacts Kenso counted (leads), and how many of them have each reference picture.models: the image models you can pick, each with its estimated credits per still image andsupportsGif, whether a variable on it can be an animated GIF.
Errors:
404 not_found: the campaign does not exist in this workspace.
Requires Campaigns view.
curl -X GET "https://api.ken.so/v1/campaigns/812/image-variables" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of ImageVariable. Each item has these fields. The response also carries pagination, linkHostReady, coverage, models.
Show the 18 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Create an image variable
/v1/campaigns/{campaignId}/image-variablesimage-variables.create- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
campaign_images feature on your workspace. Until it is on, calls answer 404.Adds an image variable to the campaign. Returns 201 with the variable and its Location. A new variable is off and generates nothing: read its cost with the estimate call, then turn it on with PATCH and enabled: true. Sending enabled: true here is a 400.
key and kind are required and never change later. Kenso normalizes key to lowercase snake_case, so Hero Image becomes hero_image and steps use it as {{hero_image}}. The key shares one set of names with the campaign's custom variables and AI variables. A per_prospect variable needs a prompt. A shared variable can use only the sender_logo reference, because it has no contact. For the same reason its prompt cannot hold a token such as {first_name} or {{company}}.
format: gif makes each image an animated GIF of frameCount frames (2 to 16, default 9) that each show for frameDurationMs (20 to 2000, default 200). It needs a model whose supportsGif is true in the list response, and no references. A GIF costs more than a still: read the estimate before you turn it on.
Errors:
400 validation_failed: a field is missing or not valid, the key is a reserved field, orenabledis true. Agifwhile animated GIFs are not available, on a model without GIF support, or with references is also a400.error.detailsnames the field.404 not_found: the campaign does not exist in this workspace.409 link_host_required: the workspace has no tracking link host.409 image_variable_limit: the campaign already has 5 image variables.409 variable_key_taken: a custom, AI or image variable of the campaign already uses the key, or the key iscustom_image.
Requires Campaigns edit.
Request body
application/json, optional.
The variable to create.
| Field | Type | Required | Description |
|---|---|---|---|
key | string | required | The token key. Required. Kenso normalizes it to lowercase snake_case, so Hero Image becomes hero_image. It cannot change later. |
kind | string | required | Either shared or per_prospect. Required. It cannot change later. |
prompt | string | optional | What to draw, at most 4,000 characters. Required for per_prospect. |
references | array of string | optional | Reference pictures: profile_photo, company_logo, sender_logo, website_screenshot or custom_image. A shared variable can use only sender_logo. Omitted is none. |
model | string | optional | Id of the image model, from models in the list response. Defaults to openai/gpt-image-2.6-sunburst. |
size | string | optional | Image size in pixels: 1024x1024, 1536x1024 or 1024x1536. Defaults to 1024x1024. |
quality | string | optional | Image quality: low, medium or high. Defaults to medium. |
format | string | optional | Either still (the default) or gif for an animated GIF. A gif needs a model whose supportsGif is true in the list response, and no references. |
frameCount | integer (int32) | optional | Frames of the animated GIF, 2 to 16. Defaults to 9. Ignored when format is still. |
frameDurationMs | integer (int32) | optional | Milliseconds each GIF frame shows, 20 to 2000, rounded to 10. Defaults to 200. Ignored when format is still. |
spellingCheck | boolean | optional | Whether Kenso checks the text in each image against the prompt. Defaults to true. |
requiredForSending | boolean | optional | Whether a contact waits for a ready image before steps that use the token. Defaults to false. |
enabled | boolean | optional | Leave it out or send false: a new variable is always off, and true is a 400. Turn it on with PATCH after you read its estimate. |
altText | string | optional | Alt text of the image in the email, at most 200 characters. |
curl -X POST "https://api.ken.so/v1/campaigns/812/image-variables" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"key": "string",
"kind": "string",
"prompt": "string",
"references": [
"profile_photo"
],
"model": "openai/gpt-image-2.6-sunburst",
"size": "1024x1024",
"quality": "medium",
"format": "still",
"frameCount": 1,
"frameDurationMs": 1,
"spellingCheck": true,
"requiredForSending": true,
"enabled": true,
"altText": "string"
}'Response 201
data is a ImageVariable.
Show the 18 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get an image variable
/v1/campaigns/{campaignId}/image-variables/{variableKey}image-variables.get- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
campaign_images feature on your workspace. Until it is on, calls answer 404.Returns one image variable with the counts of its contact images. A shared variable also has its current image in sharedImage, with a previewUrl that works for 1 hour.
Errors:
404 not_found: the campaign or the variable does not exist in this workspace.
Requires Campaigns view.
curl -X GET "https://api.ken.so/v1/campaigns/812/image-variables/hero_image" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a ImageVariable.
Show the 18 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update an image variable
/v1/campaigns/{campaignId}/image-variables/{variableKey}image-variables.update- Permission
- Campaigns edit
- Credits
- Varies with the request (
campaign_image) - Rate limit
- 4,800 requests a minute per API key
campaign_images feature on your workspace. Until it is on, calls answer 404.Changes an image variable. Fields you leave out keep their value. Send prompt or altText as null or blank to clear it. key and kind never change, so sending either one is a 400.
enabled: true turns on a per_prospect variable: Kenso then generates an image for each eligible contact and charges credits for each ready image. enabled: false is always allowed. It stops new images and keeps the ones that exist.
A change to prompt, references, model, size, quality, format or the GIF frames replaces the images of contacts that have no sent or queued step using the variable. Send the same fields to the estimate call first to see how many images that replaces and what it costs.
format: still clears frameCount and frameDurationMs. format: gif without frames takes 9 frames at 200 ms. A GIF variable cannot move to a model without GIF support: set format: still first.
Errors:
400 validation_failed: a field is not valid, or the body haskeyorkind.error.detailsnames the field.404 not_found: the campaign or the variable does not exist in this workspace.
Requires Campaigns edit.
Request body
application/json, optional.
The fields to change.
| Field | Type | Required | Description |
|---|---|---|---|
key | string | optional | Cannot change. Sending it is a 400. |
kind | string | optional | Cannot change. Sending it is a 400. |
prompt | string | optional | What to draw, at most 4,000 characters. Null or blank clears it, which a per_prospect variable does not allow. |
references | array of string | optional | The full new list of reference pictures. An empty list removes them all. |
model | string | optional | Id of the image model, from models in the list response. |
size | string | optional | Image size in pixels: 1024x1024, 1536x1024 or 1024x1536. |
quality | string | optional | Image quality: low, medium or high. |
format | string | optional | Either still or gif. still clears the frame settings. gif needs a model whose supportsGif is true in the list response and no references, and takes 9 frames at 200 ms unless you send them. |
frameCount | integer (int32) | optional | Frames of the animated GIF, 2 to 16. Ignored on a still variable. |
frameDurationMs | integer (int32) | optional | Milliseconds each GIF frame shows, 20 to 2000, rounded to 10. Ignored on a still variable. |
spellingCheck | boolean | optional | Whether Kenso checks the text in each image against the prompt. |
requiredForSending | boolean | optional | Whether a contact waits for a ready image before steps that use the token. |
enabled | boolean | optional | True turns a per_prospect variable on, so Kenso generates and charges for each eligible contact's image. False is always allowed and keeps the images that exist. |
altText | string | optional | Alt text of the image in the email, at most 200 characters. Null or blank clears it. |
curl -X PATCH "https://api.ken.so/v1/campaigns/812/image-variables/hero_image" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"key": "string",
"kind": "string",
"prompt": "string",
"references": [
"string"
],
"model": "string",
"size": "1024x1024",
"quality": "low",
"format": "string",
"frameCount": 1,
"frameDurationMs": 1,
"spellingCheck": true,
"requiredForSending": true,
"enabled": true,
"altText": "string"
}'Response 200
data is a ImageVariable.
Show the 18 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Delete an image variable
/v1/campaigns/{campaignId}/image-variables/{variableKey}image-variables.delete- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
campaign_images feature on your workspace. Until it is on, calls answer 404.Deletes an image variable. Returns 204. Images Kenso already made stay. You cannot delete a variable while a step of the campaign has its {{key}} token in the body or subject: remove the token first, or turn the variable off with enabled: false instead.
Errors:
404 not_found: the campaign or the variable does not exist in this workspace.409 image_variable_in_use: a step of the campaign still uses the token.
Requires Campaigns edit.
curl -X DELETE "https://api.ken.so/v1/campaigns/812/image-variables/hero_image" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 204
HTTP/1.1 204 No ContentEstimate an image variable's cost
/v1/campaigns/{campaignId}/image-variables/{variableKey}/estimateimage-variables.estimate- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
campaign_images feature on your workspace. Until it is on, calls answer 404.Returns how many images the variable would generate now and what they would cost. Nothing is saved. To price a change before you make it, send the fields you plan to change, with the same names as on PATCH. Fields you leave out use the saved values, and an empty body prices the variable as it is saved.
For a per_prospect variable, leadsNow counts the contacts that would get an image now. It already includes the replaceCount contacts whose current image the change would replace. creditsNow is leadsNow times creditsPerImage. A shared variable is one image: creditsNow is the price of that image and creditsPerNewLead is 0. All prices are in credits.
Errors:
400 validation_failed: a field is not valid.error.detailsnames the field.404 not_found: the campaign or the variable does not exist in this workspace.
Requires Campaigns edit.
Request body
application/json, optional.
The fields to price. Optional.
| Field | Type | Required | Description |
|---|---|---|---|
prompt | string | optional | The prompt to price. Null or blank prices the variable with no prompt. |
references | array of string | optional | The reference pictures to price. |
model | string | optional | The image model to price. |
size | string | optional | The image size to price. |
quality | string | optional | The image quality to price. |
format | string | optional | The format to price: still or gif. An animated GIF costs more than a still. |
frameCount | integer (int32) | optional | The GIF frame count to price, 2 to 16. More frames cost more. |
frameDurationMs | integer (int32) | optional | The GIF frame duration to price, 20 to 2000 milliseconds. |
spellingCheck | boolean | optional | The spelling check setting to price. |
curl -X POST "https://api.ken.so/v1/campaigns/812/image-variables/hero_image/estimate" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"prompt": "string",
"references": [
"string"
],
"model": "string",
"size": "string",
"quality": "string",
"format": "still",
"frameCount": 1,
"frameDurationMs": 1,
"spellingCheck": true
}'Response 200
data is a ImageVariableEstimate.
Show the 5 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Test an image variable on contacts
/v1/campaigns/{campaignId}/image-variables/{variableKey}/testimage-variables.test- Permission
- Campaigns edit
- Credits
- Varies with the request (
campaign_image) - Rate limit
- 240 requests a minute per API key
campaign_images feature on your workspace. Until it is on, calls answer 404.Generates images for up to 5 contacts of a per_prospect variable, so you can check the result before you turn the variable on. The call waits for the images and returns them. Each image becomes that contact's image. The test does not turn the variable on.
Kenso picks contacts with no image first, then contacts whose image failed. It never picks a contact whose image Kenso blocked. A contact whose generation failed outright is left out of the response. Kenso charges credits for each ready image. Each contact it picks counts toward the workspace's daily limit of image generations (100 a day, lower on the Free plan). When no contact is eligible, the call generates nothing and counts nothing.
Errors:
404 not_found: the campaign or the variable does not exist in this workspace.409 wrong_kind: the variable isshared. Set its image with the shared image call instead.429 quota_exceeded: the workspace reached its daily limit of image generations.Retry-Aftersays when to try again.
Requires Campaigns edit.
curl -X POST "https://api.ken.so/v1/campaigns/812/image-variables/hero_image/test" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a ImageVariableTest.
Show the 1 response field and an example
The fields and an example are also on this endpoint's Markdown page.
Regenerate a contact's image
/v1/campaigns/{campaignId}/image-variables/{variableKey}/contacts/{contactId}/regenerateimage-variables.regenerate-contact- Permission
- Campaigns edit
- Credits
- Varies with the request (
campaign_image) - Rate limit
- 100 requests a day per workspace (Free plan: 10 a day)
campaign_images feature on your workspace. Until it is on, calls answer 404.Generates a new image for one contact of a per_prospect variable. The call waits for the image and returns it, ready or failed. The contact keeps its previous image until a new one is ready. Kenso charges credits for a ready image, and the call counts toward the workspace's daily limit of image generations.
Errors:
404 not_found: the campaign, the variable or the contact does not exist in this workspace, or the contact is not one Kenso makes images for in this campaign.409 wrong_kind: the variable isshared.409 image_in_use: the contact already has a sent or queued step that uses the variable, so it keeps that image.409 blocked: Kenso blocked the contact's current image. After a prompt change, Kenso can still generate a new image for the contact, but this call does not replace it.409with a failure reason such asprovider_refused: the generation saved no image.429 quota_exceeded: the workspace reached its daily limit of image generations.
Requires Campaigns edit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
contactId | path | integer (int64) | required | Id of the contact. |
curl -X POST "https://api.ken.so/v1/campaigns/812/image-variables/hero_image/contacts/812/regenerate" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a CampaignImage.
Show the 11 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in Copy and personalization:Custom variablesAI promptsPrompt versionsCopy gradesCopy checksVoicesVoice notesVoice note previewsMessage templatesAll resources