Skip to Content
Copy and personalization

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.

Copy and personalization9 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

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.

NameInTypeRequiredDescription
campaignIdpathinteger (int64)requiredId of the campaign.
variableKeypathstringrequiredKey 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.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe 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-Idheaderinteger (int64)optionalThe 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

GET/v1/campaigns/{campaignId}/image-variablesimage-variables.list
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key
Needs the campaign_images feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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 and supportsGif, 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.

Request
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

POST/v1/campaigns/{campaignId}/image-variablesimage-variables.create
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key
Needs the campaign_images feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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, or enabled is true. A gif while animated GIFs are not available, on a model without GIF support, or with references is also a 400. error.details names 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 is custom_image.

Requires Campaigns edit.

Request body

application/json, optional.

The variable to create.

FieldTypeRequiredDescription
keystringrequiredThe token key. Required. Kenso normalizes it to lowercase snake_case, so Hero Image becomes hero_image. It cannot change later.
kindstringrequiredEither shared or per_prospect. Required. It cannot change later.
promptstringoptionalWhat to draw, at most 4,000 characters. Required for per_prospect.
referencesarray of stringoptionalReference pictures: profile_photo, company_logo, sender_logo, website_screenshot or custom_image. A shared variable can use only sender_logo. Omitted is none.
modelstringoptionalId of the image model, from models in the list response. Defaults to openai/gpt-image-2.6-sunburst.
sizestringoptionalImage size in pixels: 1024x1024, 1536x1024 or 1024x1536. Defaults to 1024x1024.
qualitystringoptionalImage quality: low, medium or high. Defaults to medium.
formatstringoptionalEither 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.
frameCountinteger (int32)optionalFrames of the animated GIF, 2 to 16. Defaults to 9. Ignored when format is still.
frameDurationMsinteger (int32)optionalMilliseconds each GIF frame shows, 20 to 2000, rounded to 10. Defaults to 200. Ignored when format is still.
spellingCheckbooleanoptionalWhether Kenso checks the text in each image against the prompt. Defaults to true.
requiredForSendingbooleanoptionalWhether a contact waits for a ready image before steps that use the token. Defaults to false.
enabledbooleanoptionalLeave 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.
altTextstringoptionalAlt text of the image in the email, at most 200 characters.
Request
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

GET/v1/campaigns/{campaignId}/image-variables/{variableKey}image-variables.get
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key
Needs the campaign_images feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

Request
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

PATCH/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
Needs the campaign_images feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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 has key or kind. error.details names 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.

FieldTypeRequiredDescription
keystringoptionalCannot change. Sending it is a 400.
kindstringoptionalCannot change. Sending it is a 400.
promptstringoptionalWhat to draw, at most 4,000 characters. Null or blank clears it, which a per_prospect variable does not allow.
referencesarray of stringoptionalThe full new list of reference pictures. An empty list removes them all.
modelstringoptionalId of the image model, from models in the list response.
sizestringoptionalImage size in pixels: 1024x1024, 1536x1024 or 1024x1536.
qualitystringoptionalImage quality: low, medium or high.
formatstringoptionalEither 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.
frameCountinteger (int32)optionalFrames of the animated GIF, 2 to 16. Ignored on a still variable.
frameDurationMsinteger (int32)optionalMilliseconds each GIF frame shows, 20 to 2000, rounded to 10. Ignored on a still variable.
spellingCheckbooleanoptionalWhether Kenso checks the text in each image against the prompt.
requiredForSendingbooleanoptionalWhether a contact waits for a ready image before steps that use the token.
enabledbooleanoptionalTrue 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.
altTextstringoptionalAlt text of the image in the email, at most 200 characters. Null or blank clears it.
Request
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

DELETE/v1/campaigns/{campaignId}/image-variables/{variableKey}image-variables.delete
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key
Needs the campaign_images feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

Request
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

Response 204
HTTP/1.1 204 No Content

Estimate an image variable's cost

POST/v1/campaigns/{campaignId}/image-variables/{variableKey}/estimateimage-variables.estimate
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key
Needs the campaign_images feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.details names 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.

FieldTypeRequiredDescription
promptstringoptionalThe prompt to price. Null or blank prices the variable with no prompt.
referencesarray of stringoptionalThe reference pictures to price.
modelstringoptionalThe image model to price.
sizestringoptionalThe image size to price.
qualitystringoptionalThe image quality to price.
formatstringoptionalThe format to price: still or gif. An animated GIF costs more than a still.
frameCountinteger (int32)optionalThe GIF frame count to price, 2 to 16. More frames cost more.
frameDurationMsinteger (int32)optionalThe GIF frame duration to price, 20 to 2000 milliseconds.
spellingCheckbooleanoptionalThe spelling check setting to price.
Request
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

POST/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
Needs the campaign_images feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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 is shared. Set its image with the shared image call instead.
  • 429 quota_exceeded: the workspace reached its daily limit of image generations. Retry-After says when to try again.

Requires Campaigns edit.

Request
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.

Set a shared image variable's image

POST/v1/campaigns/{campaignId}/image-variables/{variableKey}/shared-imageimage-variables.set-shared-image
Permission
Campaigns edit
Credits
Varies with the request (campaign_image)
Rate limit
240 requests a minute per API key
Needs the campaign_images feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Sets the one image of a shared variable. Send exactly one source:

  • A multipart form with a file field: a PNG, JPEG or WebP image of at most 10 MB.
  • A JSON body { "url": "https://..." }: a public https image that Kenso downloads once.
  • A JSON body { "generate": true }: Kenso generates the image from the variable's prompt. The call waits for the image, charges credits for it and counts toward the workspace's daily limit of image generations.

Returns the variable. An upload or a URL costs nothing. If a generation fails, sharedImage.status is failed with its errorCode, and the image in use stays.

Errors:

  • 400 validation_failed: the body has no source or more than one, the file is not an allowed image, Kenso could not use the image at url, or the variable has no prompt to generate from.
  • 404 not_found: the campaign or the variable does not exist in this workspace.
  • 409 wrong_kind: the variable is per_prospect.
  • 409 link_host_required: the workspace has no tracking link host.
  • 409 blocked: Kenso blocked the current image, so no source can replace it. Create a new image variable instead.
  • 409 with a failure reason such as provider_refused: the generation saved no image.
  • 429 quota_exceeded: a generation would pass the workspace's daily limit of image generations.

Requires Campaigns edit.

Request body

application/json, required.

FieldTypeRequiredDescription
urlstringoptionalA public https link to a PNG, JPEG or WebP image of at most 10 MB. Kenso downloads it once.
generatebooleanoptionalTrue generates the image from the variable's prompt. The call waits for the image and charges credits for it.
Request
curl -X POST "https://api.ken.so/v1/campaigns/812/image-variables/hero_image/shared-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 '{
  "url": "https://cdn.example.com/brand/team-photo.png"
}'

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.

Regenerate a contact's image

POST/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)
Needs the campaign_images feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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 is shared.
  • 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.
  • 409 with a failure reason such as provider_refused: the generation saved no image.
  • 429 quota_exceeded: the workspace reached its daily limit of image generations.

Requires Campaigns edit.

Parameters

NameInTypeRequiredDescription
contactIdpathinteger (int64)requiredId of the contact.
Request
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.


On this page