Kenso
Get early access

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.

Campaigns and sequences9 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors

List a campaign's image variables

GET/v1/campaigns/{campaignId}/image-variablesimage-variables.list

Needs the campaign_images feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Ordered by key, at most 5, one page (hasMore is always false). Beside data: linkHostReady (the workspace has a link host to serve images from; without one no image variable can be created or sent), coverage (leads plus, per reference wire name, how many leads have that reference) and models (each image model with its estimated credits per per_prospect image). Requires the Campaigns page.

Parameters

Name
In
Type
Required
Description
campaignId
In: path
integer (int64)
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

data is a list of ImageVariableModel. Each item has these fields. The response also carries pagination, linkHostReady, coverage, models.

Field
Type
Description
key
string
The token key, normalized like custom and AI variables (hero_image for {{hero_image}}).
kind
string
shared or per_prospect.
prompt
string
The image prompt; per_prospect prompts use lead tokens such as {{first_name}}.
references
array of string
Reference pictures: profile_photo, company_logo, sender_logo, website_screenshot, custom_image.
model
string
Image model id from the list's models.
size
string
1024x1024, 1536x1024 or 1024x1536.
quality
string
low, medium or high.
spellingCheck
boolean
Checks the text in each image against the prompt and regenerates once on a mismatch.
requiredForSending
boolean
A lead without a ready image is held from steps that use the token.
enabled
boolean
per_prospect: every eligible lead gets an image, charged per ready image. Off keeps the existing images.
altText
string
sharedImage
SharedImageModel
A shared image variable's image. previewUrl is a presigned link for the app, valid until previewExpiresAt.
counts
ImageVariableCountsModel
Lead images of a per_prospect variable: current ready and failed images, and every pending one.
createdAt
string (date-time)
updatedAt
string (date-time)
Request
curl -X GET "https://api.ken.so/v1/campaigns/812/image-variables" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
  "success": true,
  "data": [
    {
      "key": "string",
      "kind": "string",
      "prompt": "string",
      "references": [
        "string"
      ],
      "model": "string",
      "size": "string",
      "quality": "string",
      "spellingCheck": true,
      "requiredForSending": true,
      "enabled": true,
      "altText": "string",
      "sharedImage": {
        "imageKey": "string",
        "status": "string",
        "errorCode": "string",
        "previewUrl": "https://example.com",
        "previewExpiresAt": "2026-09-23T15:02:11Z"
      },
      "counts": {
        "ready": 1,
        "pending": 1,
        "failed": 1
      },
      "createdAt": "2026-09-23T15:02:11Z",
      "updatedAt": "2026-09-23T15:02:11Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "isTotalCapped": true
  },
  "linkHostReady": true,
  "coverage": {
    "key": 1
  },
  "models": [
    {
      "id": "string",
      "displayName": "string",
      "creditsPerImage": 0.5
    }
  ]
}

Create an image variable

POST/v1/campaigns/{campaignId}/image-variablesimage-variables.create

Needs the campaign_images feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Returns 201 and Location. key shares the namespace of custom and AI variables and is normalized (Hero Image becomes hero_image); custom_image and a key a custom, AI or image variable of the campaign has are 409 variable_key_taken. No link host in the workspace is 409 link_host_required; a sixth variable is 409 image_variable_limit. A new variable starts off: enabled: true is a 400 on enabled, and false or absent is accepted. Turn it on with PATCH after reading its estimate. Requires Campaigns edit.

Parameters

Name
In
Type
Required
Description
campaignId
In: path
integer (int64)
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Request body

application/json, optional.

Field
Type
Required
Description
key
string
optional
The token key; normalized (Hero Image is stored as hero_image). Fixed after create.
kind
string
optional
shared or per_prospect. Fixed after create.
prompt
string
optional
Required for per_prospect, at most 4,000 characters.
references
array of string
optional
Reference wire names; a shared variable may use only sender_logo.
model
string
optional
Default openai/gpt-image-2.5-sunburst.
size
string
optional
Default 1024x1024.
quality
string
optional
Default medium.
spellingCheck
boolean
optional
Default true.
requiredForSending
boolean
optional
Default false.
enabled
boolean
optional
Absent or false only: a new variable starts off, and true is a 400 on enabled. Turn it on with PATCH after reading its estimate.
altText
string
optional
At most 200 characters.

Response 201

data is a ImageVariableModel.

Field
Type
Description
key
string
The token key, normalized like custom and AI variables (hero_image for {{hero_image}}).
kind
string
shared or per_prospect.
prompt
string
The image prompt; per_prospect prompts use lead tokens such as {{first_name}}.
references
array of string
Reference pictures: profile_photo, company_logo, sender_logo, website_screenshot, custom_image.
model
string
Image model id from the list's models.
size
string
1024x1024, 1536x1024 or 1024x1536.
quality
string
low, medium or high.
spellingCheck
boolean
Checks the text in each image against the prompt and regenerates once on a mismatch.
requiredForSending
boolean
A lead without a ready image is held from steps that use the token.
enabled
boolean
per_prospect: every eligible lead gets an image, charged per ready image. Off keeps the existing images.
altText
string
sharedImage
SharedImageModel
A shared image variable's image. previewUrl is a presigned link for the app, valid until previewExpiresAt.
counts
ImageVariableCountsModel
Lead images of a per_prospect variable: current ready and failed images, and every pending one.
createdAt
string (date-time)
updatedAt
string (date-time)
Request
curl -X POST "https://api.ken.so/v1/campaigns/812/image-variables" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "string",
  "kind": "string",
  "prompt": "string",
  "references": [
    "string"
  ],
  "model": "string",
  "size": "string",
  "quality": "string",
  "spellingCheck": true,
  "requiredForSending": true,
  "enabled": true,
  "altText": "string"
}'
Response 201
{
  "success": true,
  "data": {
    "key": "string",
    "kind": "string",
    "prompt": "string",
    "references": [
      "string"
    ],
    "model": "string",
    "size": "string",
    "quality": "string",
    "spellingCheck": true,
    "requiredForSending": true,
    "enabled": true,
    "altText": "string",
    "sharedImage": {
      "imageKey": "string",
      "status": "string",
      "errorCode": "string",
      "previewUrl": "https://example.com",
      "previewExpiresAt": "2026-09-23T15:02:11Z"
    },
    "counts": {
      "ready": 1,
      "pending": 1,
      "failed": 1
    },
    "createdAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-09-23T15:02:11Z"
  }
}

Get one image variable

GET/v1/campaigns/{campaignId}/image-variables/{variableKey}image-variables.get

Needs the campaign_images feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

A shared variable carries its current image with a presigned previewUrl (1 hour). Requires the Campaigns page.

Parameters

Name
In
Type
Required
Description
campaignId
In: path
integer (int64)
required
variableKey
In: path
string
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

data is a ImageVariableModel.

Field
Type
Description
key
string
The token key, normalized like custom and AI variables (hero_image for {{hero_image}}).
kind
string
shared or per_prospect.
prompt
string
The image prompt; per_prospect prompts use lead tokens such as {{first_name}}.
references
array of string
Reference pictures: profile_photo, company_logo, sender_logo, website_screenshot, custom_image.
model
string
Image model id from the list's models.
size
string
1024x1024, 1536x1024 or 1024x1536.
quality
string
low, medium or high.
spellingCheck
boolean
Checks the text in each image against the prompt and regenerates once on a mismatch.
requiredForSending
boolean
A lead without a ready image is held from steps that use the token.
enabled
boolean
per_prospect: every eligible lead gets an image, charged per ready image. Off keeps the existing images.
altText
string
sharedImage
SharedImageModel
A shared image variable's image. previewUrl is a presigned link for the app, valid until previewExpiresAt.
counts
ImageVariableCountsModel
Lead images of a per_prospect variable: current ready and failed images, and every pending one.
createdAt
string (date-time)
updatedAt
string (date-time)
Request
curl -X GET "https://api.ken.so/v1/campaigns/812/image-variables/string" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
  "success": true,
  "data": {
    "key": "string",
    "kind": "string",
    "prompt": "string",
    "references": [
      "string"
    ],
    "model": "string",
    "size": "string",
    "quality": "string",
    "spellingCheck": true,
    "requiredForSending": true,
    "enabled": true,
    "altText": "string",
    "sharedImage": {
      "imageKey": "string",
      "status": "string",
      "errorCode": "string",
      "previewUrl": "https://example.com",
      "previewExpiresAt": "2026-09-23T15:02:11Z"
    },
    "counts": {
      "ready": 1,
      "pending": 1,
      "failed": 1
    },
    "createdAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-09-23T15:02:11Z"
  }
}

Update an image variable

PATCH/v1/campaigns/{campaignId}/image-variables/{variableKey}image-variables.update

Needs the campaign_images feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Absent fields stay unchanged; prompt and altText are cleared by null or blank. key and kind never change (400 on that field). A changed prompt, reference set, model, size or quality replaces the images of leads with no sent or queued step that uses the variable; read the estimate first. enabled: false is always allowed and keeps the existing images. Requires Campaigns edit.

Parameters

Name
In
Type
Required
Description
campaignId
In: path
integer (int64)
required
variableKey
In: path
string
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Request body

application/json, optional.

Field
Type
Required
Description
key
string
optional
Not changeable: sending it is 400.
kind
string
optional
Not changeable: sending it is 400.
prompt
string
optional
references
array of string
optional
model
string
optional
size
string
optional
quality
string
optional
spellingCheck
boolean
optional
requiredForSending
boolean
optional
enabled
boolean
optional
per_prospect standing order. False is always allowed and keeps the existing images.
altText
string
optional

Response 200

data is a ImageVariableModel.

Field
Type
Description
key
string
The token key, normalized like custom and AI variables (hero_image for {{hero_image}}).
kind
string
shared or per_prospect.
prompt
string
The image prompt; per_prospect prompts use lead tokens such as {{first_name}}.
references
array of string
Reference pictures: profile_photo, company_logo, sender_logo, website_screenshot, custom_image.
model
string
Image model id from the list's models.
size
string
1024x1024, 1536x1024 or 1024x1536.
quality
string
low, medium or high.
spellingCheck
boolean
Checks the text in each image against the prompt and regenerates once on a mismatch.
requiredForSending
boolean
A lead without a ready image is held from steps that use the token.
enabled
boolean
per_prospect: every eligible lead gets an image, charged per ready image. Off keeps the existing images.
altText
string
sharedImage
SharedImageModel
A shared image variable's image. previewUrl is a presigned link for the app, valid until previewExpiresAt.
counts
ImageVariableCountsModel
Lead images of a per_prospect variable: current ready and failed images, and every pending one.
createdAt
string (date-time)
updatedAt
string (date-time)
Request
curl -X PATCH "https://api.ken.so/v1/campaigns/812/image-variables/string" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "string",
  "kind": "string",
  "prompt": "string",
  "references": [
    "string"
  ],
  "model": "string",
  "size": "string",
  "quality": "string",
  "spellingCheck": true,
  "requiredForSending": true,
  "enabled": true,
  "altText": "string"
}'
Response 200
{
  "success": true,
  "data": {
    "key": "string",
    "kind": "string",
    "prompt": "string",
    "references": [
      "string"
    ],
    "model": "string",
    "size": "string",
    "quality": "string",
    "spellingCheck": true,
    "requiredForSending": true,
    "enabled": true,
    "altText": "string",
    "sharedImage": {
      "imageKey": "string",
      "status": "string",
      "errorCode": "string",
      "previewUrl": "https://example.com",
      "previewExpiresAt": "2026-09-23T15:02:11Z"
    },
    "counts": {
      "ready": 1,
      "pending": 1,
      "failed": 1
    },
    "createdAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-09-23T15:02:11Z"
  }
}

Delete an image variable

DELETE/v1/campaigns/{campaignId}/image-variables/{variableKey}image-variables.delete

Needs the campaign_images feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Returns 204. 409 image_variable_in_use while any step of the campaign holds {{key}} in its body or subject: remove it there first, or disable the variable instead. Its images stay. Requires Campaigns edit.

Parameters

Name
In
Type
Required
Description
campaignId
In: path
integer (int64)
required
variableKey
In: path
string
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 204

Request
curl -X DELETE "https://api.ken.so/v1/campaigns/812/image-variables/string" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 204
HTTP/1.1 204 No Content

Estimate what running an image variable would generate and cost

POST/v1/campaigns/{campaignId}/image-variables/{variableKey}/estimateimage-variables.estimate

Needs the campaign_images feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

A read: nothing is written. The body holds optional draft fields (absent = the saved value). leadsNow is how many leads would get an image now, already counting the replaceCount leads whose current image the change would replace; creditsNow = leadsNow x creditsPerImage. A shared variable is one image and 0 per new lead. Every credit field is credits. Requires Campaigns edit.

Parameters

Name
In
Type
Required
Description
campaignId
In: path
integer (int64)
required
variableKey
In: path
string
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Request body

application/json, optional.

Field
Type
Required
Description
prompt
string
optional
references
array of string
optional
model
string
optional
size
string
optional
quality
string
optional
spellingCheck
boolean
optional

Response 200

data is a ImageVariableEstimateModel.

Field
Type
Description
leadsNow
integer (int32)
Leads that would get an image now, including the leads whose image would be replaced.
replaceCount
integer (int32)
Of those, leads whose current ready image would be replaced by the change.
creditsPerImage
number (double)
creditsNow
number (double)
creditsPerNewLead
number (double)
Credits per lead that becomes eligible later; 0 for a shared variable.
Request
curl -X POST "https://api.ken.so/v1/campaigns/812/image-variables/string/estimate" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "string",
  "references": [
    "string"
  ],
  "model": "string",
  "size": "string",
  "quality": "string",
  "spellingCheck": true
}'
Response 200
{
  "success": true,
  "data": {
    "leadsNow": 1,
    "replaceCount": 1,
    "creditsPerImage": 0.5,
    "creditsNow": 0.5,
    "creditsPerNewLead": 0.5
  }
}

Test a per_prospect image variable on up to 5 leads

POST/v1/campaigns/{campaignId}/image-variables/{variableKey}/testimage-variables.test

Needs the campaign_images feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Sync: generates for up to 5 eligible leads (leads with no image first, then leads whose image failed), charged per ready image, and returns the images (a lead whose generation failed outright is left out). They become those leads' images. A lead whose image Kenso staff blocked is never picked. Does not turn the variable on. A shared variable is 409 wrong_kind. Reserves one editor generation per lead it picks (at most 5, none when no lead is eligible), after those checks. Requires Campaigns edit.

Parameters

Name
In
Type
Required
Description
campaignId
In: path
integer (int64)
required
variableKey
In: path
string
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

data is a ImageVariableTestModel.

Field
Type
Description
images
array of CampaignImageModel
Request
curl -X POST "https://api.ken.so/v1/campaigns/812/image-variables/string/test" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
  "success": true,
  "data": {
    "images": [
      {
        "imageKey": "string",
        "contactId": 812,
        "variableKey": "string",
        "status": "string",
        "errorCode": "string",
        "errorDetail": "string",
        "width": 1,
        "height": 1,
        "previewUrl": "https://example.com",
        "previewExpiresAt": "2026-09-23T15:02:11Z",
        "updatedAt": "2026-09-23T15:02:11Z"
      }
    ]
  }
}

Set a shared image variable's image

POST/v1/campaigns/{campaignId}/image-variables/{variableKey}/shared-imageimage-variables.set-shared-image

Needs the campaign_images feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Exactly one source: multipart field file (PNG, JPEG or WebP, at most 10 MB), JSON { "url": "..." } (a public https image, fetched once) or JSON { "generate": true } (from the prompt, sync and charged; reserves 1 editor generation once the checks below pass). Returns the variable; a generation that failed comes back as sharedImage.statusfailed with its errorCode, and the image already in use stays. A URL that cannot be fetched is 400 on url. A per_prospect variable is 409 wrong_kind; no link host is 409 link_host_required. A shared image Kenso staff blocked is not replaced from any source: 409 blocked. Requires Campaigns edit.

Parameters

Name
In
Type
Required
Description
campaignId
In: path
integer (int64)
required
variableKey
In: path
string
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

data is a ImageVariableModel.

Field
Type
Description
key
string
The token key, normalized like custom and AI variables (hero_image for {{hero_image}}).
kind
string
shared or per_prospect.
prompt
string
The image prompt; per_prospect prompts use lead tokens such as {{first_name}}.
references
array of string
Reference pictures: profile_photo, company_logo, sender_logo, website_screenshot, custom_image.
model
string
Image model id from the list's models.
size
string
1024x1024, 1536x1024 or 1024x1536.
quality
string
low, medium or high.
spellingCheck
boolean
Checks the text in each image against the prompt and regenerates once on a mismatch.
requiredForSending
boolean
A lead without a ready image is held from steps that use the token.
enabled
boolean
per_prospect: every eligible lead gets an image, charged per ready image. Off keeps the existing images.
altText
string
sharedImage
SharedImageModel
A shared image variable's image. previewUrl is a presigned link for the app, valid until previewExpiresAt.
counts
ImageVariableCountsModel
Lead images of a per_prospect variable: current ready and failed images, and every pending one.
createdAt
string (date-time)
updatedAt
string (date-time)
Request
curl -X POST "https://api.ken.so/v1/campaigns/812/image-variables/string/shared-image" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
  "success": true,
  "data": {
    "key": "string",
    "kind": "string",
    "prompt": "string",
    "references": [
      "string"
    ],
    "model": "string",
    "size": "string",
    "quality": "string",
    "spellingCheck": true,
    "requiredForSending": true,
    "enabled": true,
    "altText": "string",
    "sharedImage": {
      "imageKey": "string",
      "status": "string",
      "errorCode": "string",
      "previewUrl": "https://example.com",
      "previewExpiresAt": "2026-09-23T15:02:11Z"
    },
    "counts": {
      "ready": 1,
      "pending": 1,
      "failed": 1
    },
    "createdAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-09-23T15:02:11Z"
  }
}

Regenerate one lead's image

POST/v1/campaigns/{campaignId}/image-variables/{variableKey}/contacts/{contactId}/regenerateimage-variables.regenerate-contact

Needs the campaign_images feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Sync and charged per ready image; reserves 1 editor generation once the checks pass. Returns the new image, ready or failed; the previous image stays in use until a new one is ready. 409 image_in_use when the lead already has a sent or queued step that uses the variable, so it keeps that image. 409 blocked when Kenso staff blocked the lead's current image: a block covers that one image, not its slot, so a changed prompt still lets the generation job make the lead a new one, but this route does not replace it. A lead outside the campaign's image audience is 404; a shared variable is 409 wrong_kind. Requires Campaigns edit.

Parameters

Name
In
Type
Required
Description
campaignId
In: path
integer (int64)
required
variableKey
In: path
string
required
contactId
In: path
integer (int64)
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

data is a CampaignImageModel.

Field
Type
Description
imageKey
string
contactId
integer (int64)
variableKey
string
status
string
errorCode
string
errorDetail
string
width
integer (int32)
height
integer (int32)
previewUrl
string
previewExpiresAt
string (date-time)
updatedAt
string (date-time)
Request
curl -X POST "https://api.ken.so/v1/campaigns/812/image-variables/string/contacts/812/regenerate" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
  "success": true,
  "data": {
    "imageKey": "string",
    "contactId": 812,
    "variableKey": "string",
    "status": "string",
    "errorCode": "string",
    "errorDetail": "string",
    "width": 1,
    "height": 1,
    "previewUrl": "https://example.com",
    "previewExpiresAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-09-23T15:02:11Z"
  }
}
More in Campaigns and sequences:CampaignsSegmentsEmail sequencesSegment email sequencesLinkedIn sequencesSegment LinkedIn sequencesSequence variablesCustom variablesCampaign imagesListsTracking linksAuto pausesCampaign complianceCampaign languagesCampaign localizationsMarketsAnalyticsAll resources