> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [/docs/api/image-variables/openapi.json](/docs/api/image-variables/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Image variables

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

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 personalization. 9 endpoints under `https://api.ken.so`. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`: see [Authentication](/docs/authentication.md), [Workspaces](/docs/workspaces.md) and [Errors](/docs/errors.md). OpenAPI for this resource only: [/docs/api/image-variables/openapi.json](/docs/api/image-variables/openapi.json).

- `GET /v1/campaigns/{campaignId}/image-variables` - List a campaign's image variables (`image-variables.list`): [/docs/api/image-variables/list.md](/docs/api/image-variables/list.md)
- `POST /v1/campaigns/{campaignId}/image-variables` - Create an image variable (`image-variables.create`): [/docs/api/image-variables/create.md](/docs/api/image-variables/create.md)
- `GET /v1/campaigns/{campaignId}/image-variables/{variableKey}` - Get an image variable (`image-variables.get`): [/docs/api/image-variables/get.md](/docs/api/image-variables/get.md)
- `PATCH /v1/campaigns/{campaignId}/image-variables/{variableKey}` - Update an image variable (`image-variables.update`): [/docs/api/image-variables/update.md](/docs/api/image-variables/update.md)
- `DELETE /v1/campaigns/{campaignId}/image-variables/{variableKey}` - Delete an image variable (`image-variables.delete`): [/docs/api/image-variables/delete.md](/docs/api/image-variables/delete.md)
- `POST /v1/campaigns/{campaignId}/image-variables/{variableKey}/estimate` - Estimate an image variable's cost (`image-variables.estimate`): [/docs/api/image-variables/estimate.md](/docs/api/image-variables/estimate.md)
- `POST /v1/campaigns/{campaignId}/image-variables/{variableKey}/test` - Test an image variable on contacts (`image-variables.test`): [/docs/api/image-variables/test.md](/docs/api/image-variables/test.md)
- `POST /v1/campaigns/{campaignId}/image-variables/{variableKey}/shared-image` - Set a shared image variable's image (`image-variables.set-shared-image`): [/docs/api/image-variables/set-shared-image.md](/docs/api/image-variables/set-shared-image.md)
- `POST /v1/campaigns/{campaignId}/image-variables/{variableKey}/contacts/{contactId}/regenerate` - Regenerate a contact's image (`image-variables.regenerate-contact`): [/docs/api/image-variables/regenerate-contact.md](/docs/api/image-variables/regenerate-contact.md)

## List a campaign's image variables

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

| Permission | Rate limit |
| --- | --- |
| Campaigns view | 12,000 requests a minute per API key |

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.

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

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/image-variables/GET/v1/campaigns/%7BcampaignId%7D/image-variables)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `campaignId` | path | integer (int64) | yes | Id of the campaign. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Response 200

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

| Field | Type | Description |
| --- | --- | --- |
| `key` | string | The token key in lowercase snake_case, such as `hero_image` for the `{{hero_image}}` token. |
| `kind` | string | Either `shared` (one image for every contact) or `per_prospect` (one image per contact). |
| `prompt` | string | What to draw. A `per_prospect` prompt can use contact tokens such as `{{first_name}}`. Null when the variable has no prompt. |
| `references` | array of string | Pictures Kenso gives the image model with the prompt: `profile_photo`, `company_logo`, `sender_logo`, `website_screenshot` or `custom_image` (the contact's own image). A contact that lacks a picture is generated without it. |
| `model` | string | Id of the image model, one of the `models` in the list response. |
| `size` | string | Image size in pixels: `1024x1024`, `1536x1024` or `1024x1536`. |
| `quality` | string | Image quality: `low`, `medium` or `high`. |
| `format` | string | Either `still` (one image) or `gif` (an animated GIF). |
| `frameCount` | integer (int32) | How many frames the animated GIF has, 2 to 16. Null when `format` is `still`. |
| `frameDurationMs` | integer (int32) | How long each GIF frame shows, in milliseconds, 20 to 2000. Null when `format` is `still`. |
| `spellingCheck` | boolean | When true, Kenso checks the text in each image against the prompt and generates it once more if they differ. |
| `requiredForSending` | boolean | When true, Kenso holds a contact from steps that use the token until the contact's image is ready. |
| `enabled` | boolean | Whether a `per_prospect` variable is on. While it is on, Kenso generates an image for each eligible contact and charges credits for each ready image. Turning it off keeps the images that exist. |
| `altText` | string | Alt text of the image in the email, or null for none. |
| `sharedImage` | SharedImage | The current image of a `shared` variable, or the attempt that just failed. Null for a `per_prospect` variable and for a `shared` one with no image yet. |
| `counts` | ImageVariableCounts | How many contact images the variable has, by status. |
| `createdAt` | string (date-time) | When the variable was created, in UTC. |
| `updatedAt` | string (date-time) | When the variable last changed, in UTC. |

### Request

```bash
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"
```

### Example response

```json
{
  "success": true,
  "data": [
    {
      "key": "hero_image",
      "kind": "string",
      "prompt": "string",
      "references": [
        "profile_photo"
      ],
      "model": "string",
      "size": "1024x1024",
      "quality": "low",
      "format": "string",
      "frameCount": 1,
      "frameDurationMs": 1,
      "spellingCheck": true,
      "requiredForSending": true,
      "enabled": true,
      "altText": "string",
      "sharedImage": {
        "imageKey": "string",
        "status": "pending",
        "errorCode": "provider_refused",
        "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,
    "totalCount": 1,
    "isTotalCapped": true
  },
  "linkHostReady": true,
  "coverage": {
    "key": 1
  },
  "models": [
    {
      "id": "openai/gpt-image-2.6-sunburst",
      "displayName": "string",
      "creditsPerImage": 0.5,
      "supportsGif": true
    }
  ]
}
```

## Create an image variable

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

| Permission | Rate limit |
| --- | --- |
| Campaigns edit | 4,800 requests a minute per API key |

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.

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

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/image-variables/POST/v1/campaigns/%7BcampaignId%7D/image-variables)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `campaignId` | path | integer (int64) | yes | Id of the campaign. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Request body

`application/json`, optional.

The variable to create.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | string | yes | The token key. Required. Kenso normalizes it to lowercase snake_case, so `Hero Image` becomes `hero_image`. It cannot change later. |
| `kind` | string | yes | Either `shared` or `per_prospect`. Required. It cannot change later. |
| `prompt` | string | no | What to draw, at most 4,000 characters. Required for `per_prospect`. |
| `references` | array of string | no | 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 | no | Id of the image model, from `models` in the list response. Defaults to `openai/gpt-image-2.6-sunburst`. |
| `size` | string | no | Image size in pixels: `1024x1024`, `1536x1024` or `1024x1536`. Defaults to `1024x1024`. |
| `quality` | string | no | Image quality: `low`, `medium` or `high`. Defaults to `medium`. |
| `format` | string | no | 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) | no | Frames of the animated GIF, 2 to 16. Defaults to 9. Ignored when `format` is `still`. |
| `frameDurationMs` | integer (int32) | no | Milliseconds each GIF frame shows, 20 to 2000, rounded to 10. Defaults to 200. Ignored when `format` is `still`. |
| `spellingCheck` | boolean | no | Whether Kenso checks the text in each image against the prompt. Defaults to true. |
| `requiredForSending` | boolean | no | Whether a contact waits for a ready image before steps that use the token. Defaults to false. |
| `enabled` | boolean | no | 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 | no | Alt text of the image in the email, at most 200 characters. |

### Response 201

`data` is a `ImageVariable`.

| Field | Type | Description |
| --- | --- | --- |
| `key` | string | The token key in lowercase snake_case, such as `hero_image` for the `{{hero_image}}` token. |
| `kind` | string | Either `shared` (one image for every contact) or `per_prospect` (one image per contact). |
| `prompt` | string | What to draw. A `per_prospect` prompt can use contact tokens such as `{{first_name}}`. Null when the variable has no prompt. |
| `references` | array of string | Pictures Kenso gives the image model with the prompt: `profile_photo`, `company_logo`, `sender_logo`, `website_screenshot` or `custom_image` (the contact's own image). A contact that lacks a picture is generated without it. |
| `model` | string | Id of the image model, one of the `models` in the list response. |
| `size` | string | Image size in pixels: `1024x1024`, `1536x1024` or `1024x1536`. |
| `quality` | string | Image quality: `low`, `medium` or `high`. |
| `format` | string | Either `still` (one image) or `gif` (an animated GIF). |
| `frameCount` | integer (int32) | How many frames the animated GIF has, 2 to 16. Null when `format` is `still`. |
| `frameDurationMs` | integer (int32) | How long each GIF frame shows, in milliseconds, 20 to 2000. Null when `format` is `still`. |
| `spellingCheck` | boolean | When true, Kenso checks the text in each image against the prompt and generates it once more if they differ. |
| `requiredForSending` | boolean | When true, Kenso holds a contact from steps that use the token until the contact's image is ready. |
| `enabled` | boolean | Whether a `per_prospect` variable is on. While it is on, Kenso generates an image for each eligible contact and charges credits for each ready image. Turning it off keeps the images that exist. |
| `altText` | string | Alt text of the image in the email, or null for none. |
| `sharedImage` | SharedImage | The current image of a `shared` variable, or the attempt that just failed. Null for a `per_prospect` variable and for a `shared` one with no image yet. |
| `counts` | ImageVariableCounts | How many contact images the variable has, by status. |
| `createdAt` | string (date-time) | When the variable was created, in UTC. |
| `updatedAt` | string (date-time) | When the variable last changed, in UTC. |

### Request

```bash
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"
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "key": "hero_image",
    "kind": "string",
    "prompt": "string",
    "references": [
      "profile_photo"
    ],
    "model": "string",
    "size": "1024x1024",
    "quality": "low",
    "format": "string",
    "frameCount": 1,
    "frameDurationMs": 1,
    "spellingCheck": true,
    "requiredForSending": true,
    "enabled": true,
    "altText": "string",
    "sharedImage": {
      "imageKey": "string",
      "status": "pending",
      "errorCode": "provider_refused",
      "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 an image variable

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

| Permission | Rate limit |
| --- | --- |
| Campaigns view | 12,000 requests a minute per API key |

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.

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

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/image-variables/GET/v1/campaigns/%7BcampaignId%7D/image-variables/%7BvariableKey%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `campaignId` | path | integer (int64) | yes | Id of the campaign. |
| `variableKey` | path | string | yes | Key of the image variable, such as `hero_image`. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Response 200

`data` is a `ImageVariable`.

| Field | Type | Description |
| --- | --- | --- |
| `key` | string | The token key in lowercase snake_case, such as `hero_image` for the `{{hero_image}}` token. |
| `kind` | string | Either `shared` (one image for every contact) or `per_prospect` (one image per contact). |
| `prompt` | string | What to draw. A `per_prospect` prompt can use contact tokens such as `{{first_name}}`. Null when the variable has no prompt. |
| `references` | array of string | Pictures Kenso gives the image model with the prompt: `profile_photo`, `company_logo`, `sender_logo`, `website_screenshot` or `custom_image` (the contact's own image). A contact that lacks a picture is generated without it. |
| `model` | string | Id of the image model, one of the `models` in the list response. |
| `size` | string | Image size in pixels: `1024x1024`, `1536x1024` or `1024x1536`. |
| `quality` | string | Image quality: `low`, `medium` or `high`. |
| `format` | string | Either `still` (one image) or `gif` (an animated GIF). |
| `frameCount` | integer (int32) | How many frames the animated GIF has, 2 to 16. Null when `format` is `still`. |
| `frameDurationMs` | integer (int32) | How long each GIF frame shows, in milliseconds, 20 to 2000. Null when `format` is `still`. |
| `spellingCheck` | boolean | When true, Kenso checks the text in each image against the prompt and generates it once more if they differ. |
| `requiredForSending` | boolean | When true, Kenso holds a contact from steps that use the token until the contact's image is ready. |
| `enabled` | boolean | Whether a `per_prospect` variable is on. While it is on, Kenso generates an image for each eligible contact and charges credits for each ready image. Turning it off keeps the images that exist. |
| `altText` | string | Alt text of the image in the email, or null for none. |
| `sharedImage` | SharedImage | The current image of a `shared` variable, or the attempt that just failed. Null for a `per_prospect` variable and for a `shared` one with no image yet. |
| `counts` | ImageVariableCounts | How many contact images the variable has, by status. |
| `createdAt` | string (date-time) | When the variable was created, in UTC. |
| `updatedAt` | string (date-time) | When the variable last changed, in UTC. |

### Request

```bash
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"
```

### Example response

```json
{
  "success": true,
  "data": {
    "key": "hero_image",
    "kind": "string",
    "prompt": "string",
    "references": [
      "profile_photo"
    ],
    "model": "string",
    "size": "1024x1024",
    "quality": "low",
    "format": "string",
    "frameCount": 1,
    "frameDurationMs": 1,
    "spellingCheck": true,
    "requiredForSending": true,
    "enabled": true,
    "altText": "string",
    "sharedImage": {
      "imageKey": "string",
      "status": "pending",
      "errorCode": "provider_refused",
      "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}` - operationId `image-variables.update`

| Permission | Credits | Rate limit |
| --- | --- | --- |
| Campaigns edit | Varies with the request (`campaign_image`) | 4,800 requests a minute per API key |

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.

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

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/image-variables/PATCH/v1/campaigns/%7BcampaignId%7D/image-variables/%7BvariableKey%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `campaignId` | path | integer (int64) | yes | Id of the campaign. |
| `variableKey` | path | string | yes | Key of the image variable, such as `hero_image`. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Request body

`application/json`, optional.

The fields to change.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | string | no | Cannot change. Sending it is a `400`. |
| `kind` | string | no | Cannot change. Sending it is a `400`. |
| `prompt` | string | no | 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 | no | The full new list of reference pictures. An empty list removes them all. |
| `model` | string | no | Id of the image model, from `models` in the list response. |
| `size` | string | no | Image size in pixels: `1024x1024`, `1536x1024` or `1024x1536`. |
| `quality` | string | no | Image quality: `low`, `medium` or `high`. |
| `format` | string | no | 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) | no | Frames of the animated GIF, 2 to 16. Ignored on a `still` variable. |
| `frameDurationMs` | integer (int32) | no | Milliseconds each GIF frame shows, 20 to 2000, rounded to 10. Ignored on a `still` variable. |
| `spellingCheck` | boolean | no | Whether Kenso checks the text in each image against the prompt. |
| `requiredForSending` | boolean | no | Whether a contact waits for a ready image before steps that use the token. |
| `enabled` | boolean | no | 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 | no | Alt text of the image in the email, at most 200 characters. Null or blank clears it. |

### Response 200

`data` is a `ImageVariable`.

| Field | Type | Description |
| --- | --- | --- |
| `key` | string | The token key in lowercase snake_case, such as `hero_image` for the `{{hero_image}}` token. |
| `kind` | string | Either `shared` (one image for every contact) or `per_prospect` (one image per contact). |
| `prompt` | string | What to draw. A `per_prospect` prompt can use contact tokens such as `{{first_name}}`. Null when the variable has no prompt. |
| `references` | array of string | Pictures Kenso gives the image model with the prompt: `profile_photo`, `company_logo`, `sender_logo`, `website_screenshot` or `custom_image` (the contact's own image). A contact that lacks a picture is generated without it. |
| `model` | string | Id of the image model, one of the `models` in the list response. |
| `size` | string | Image size in pixels: `1024x1024`, `1536x1024` or `1024x1536`. |
| `quality` | string | Image quality: `low`, `medium` or `high`. |
| `format` | string | Either `still` (one image) or `gif` (an animated GIF). |
| `frameCount` | integer (int32) | How many frames the animated GIF has, 2 to 16. Null when `format` is `still`. |
| `frameDurationMs` | integer (int32) | How long each GIF frame shows, in milliseconds, 20 to 2000. Null when `format` is `still`. |
| `spellingCheck` | boolean | When true, Kenso checks the text in each image against the prompt and generates it once more if they differ. |
| `requiredForSending` | boolean | When true, Kenso holds a contact from steps that use the token until the contact's image is ready. |
| `enabled` | boolean | Whether a `per_prospect` variable is on. While it is on, Kenso generates an image for each eligible contact and charges credits for each ready image. Turning it off keeps the images that exist. |
| `altText` | string | Alt text of the image in the email, or null for none. |
| `sharedImage` | SharedImage | The current image of a `shared` variable, or the attempt that just failed. Null for a `per_prospect` variable and for a `shared` one with no image yet. |
| `counts` | ImageVariableCounts | How many contact images the variable has, by status. |
| `createdAt` | string (date-time) | When the variable was created, in UTC. |
| `updatedAt` | string (date-time) | When the variable last changed, in UTC. |

### Request

```bash
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"
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "key": "hero_image",
    "kind": "string",
    "prompt": "string",
    "references": [
      "profile_photo"
    ],
    "model": "string",
    "size": "1024x1024",
    "quality": "low",
    "format": "string",
    "frameCount": 1,
    "frameDurationMs": 1,
    "spellingCheck": true,
    "requiredForSending": true,
    "enabled": true,
    "altText": "string",
    "sharedImage": {
      "imageKey": "string",
      "status": "pending",
      "errorCode": "provider_refused",
      "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}` - operationId `image-variables.delete`

| Permission | Rate limit |
| --- | --- |
| Campaigns edit | 4,800 requests a minute per API key |

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.

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

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/image-variables/DELETE/v1/campaigns/%7BcampaignId%7D/image-variables/%7BvariableKey%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `campaignId` | path | integer (int64) | yes | Id of the campaign. |
| `variableKey` | path | string | yes | Key of the image variable, such as `hero_image`. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Response 204

### Request

```bash
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"
```

### Example response

```http
HTTP/1.1 204 No Content
```

## Estimate an image variable's cost

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

| Permission | Rate limit |
| --- | --- |
| Campaigns edit | 4,800 requests a minute per API key |

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.

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

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/image-variables/POST/v1/campaigns/%7BcampaignId%7D/image-variables/%7BvariableKey%7D/estimate)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `campaignId` | path | integer (int64) | yes | Id of the campaign. |
| `variableKey` | path | string | yes | Key of the image variable, such as `hero_image`. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Request body

`application/json`, optional.

The fields to price. Optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `prompt` | string | no | The prompt to price. Null or blank prices the variable with no prompt. |
| `references` | array of string | no | The reference pictures to price. |
| `model` | string | no | The image model to price. |
| `size` | string | no | The image size to price. |
| `quality` | string | no | The image quality to price. |
| `format` | string | no | The format to price: `still` or `gif`. An animated GIF costs more than a still. |
| `frameCount` | integer (int32) | no | The GIF frame count to price, 2 to 16. More frames cost more. |
| `frameDurationMs` | integer (int32) | no | The GIF frame duration to price, 20 to 2000 milliseconds. |
| `spellingCheck` | boolean | no | The spelling check setting to price. |

### Response 200

`data` is a `ImageVariableEstimate`.

| Field | Type | Description |
| --- | --- | --- |
| `leadsNow` | integer (int32) | Contacts that would get an image now, including the contacts whose image the change would replace. 0 for a `shared` variable. |
| `replaceCount` | integer (int32) | Of those contacts, how many have a ready image that the change would replace. |
| `creditsPerImage` | number (double) | Estimated credits for one image. |
| `creditsNow` | number (double) | Estimated credits for the images Kenso would generate now. For a `shared` variable, the price of its one image. |
| `creditsPerNewLead` | number (double) | Estimated credits for each contact that becomes eligible later. 0 for a `shared` variable. |

### Request

```bash
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
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "leadsNow": 1,
    "replaceCount": 1,
    "creditsPerImage": 0.5,
    "creditsNow": 0.5,
    "creditsPerNewLead": 0.5
  }
}
```

## Test an image variable on contacts

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

| Permission | Credits | Rate limit |
| --- | --- | --- |
| Campaigns edit | Varies with the request (`campaign_image`) | 240 requests a minute per API key |

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.

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

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/image-variables/POST/v1/campaigns/%7BcampaignId%7D/image-variables/%7BvariableKey%7D/test)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `campaignId` | path | integer (int64) | yes | Id of the campaign. |
| `variableKey` | path | string | yes | Key of the image variable, such as `hero_image`. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Response 200

`data` is a `ImageVariableTest`.

| Field | Type | Description |
| --- | --- | --- |
| `images` | array of CampaignImage | One image per tested contact, ready or failed. A contact whose generation failed outright is left out. |

### Request

```bash
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"
```

### Example response

```json
{
  "success": true,
  "data": {
    "images": [
      {
        "imageKey": "string",
        "contactId": 812,
        "variableKey": "string",
        "status": "string",
        "errorCode": "timeout",
        "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-image` - operationId `image-variables.set-shared-image`

| Permission | Credits | Rate limit |
| --- | --- | --- |
| Campaigns edit | Varies with the request (`campaign_image`) | 240 requests a minute per API key |

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.

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

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/image-variables/POST/v1/campaigns/%7BcampaignId%7D/image-variables/%7BvariableKey%7D/shared-image)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `campaignId` | path | integer (int64) | yes | Id of the campaign. |
| `variableKey` | path | string | yes | Key of the image variable, such as `hero_image`. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Request body

`application/json`, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | no | A public https link to a PNG, JPEG or WebP image of at most 10 MB. Kenso downloads it once. |
| `generate` | boolean | no | True generates the image from the variable's prompt. The call waits for the image and charges credits for it. |

### Response 200

`data` is a `ImageVariable`.

| Field | Type | Description |
| --- | --- | --- |
| `key` | string | The token key in lowercase snake_case, such as `hero_image` for the `{{hero_image}}` token. |
| `kind` | string | Either `shared` (one image for every contact) or `per_prospect` (one image per contact). |
| `prompt` | string | What to draw. A `per_prospect` prompt can use contact tokens such as `{{first_name}}`. Null when the variable has no prompt. |
| `references` | array of string | Pictures Kenso gives the image model with the prompt: `profile_photo`, `company_logo`, `sender_logo`, `website_screenshot` or `custom_image` (the contact's own image). A contact that lacks a picture is generated without it. |
| `model` | string | Id of the image model, one of the `models` in the list response. |
| `size` | string | Image size in pixels: `1024x1024`, `1536x1024` or `1024x1536`. |
| `quality` | string | Image quality: `low`, `medium` or `high`. |
| `format` | string | Either `still` (one image) or `gif` (an animated GIF). |
| `frameCount` | integer (int32) | How many frames the animated GIF has, 2 to 16. Null when `format` is `still`. |
| `frameDurationMs` | integer (int32) | How long each GIF frame shows, in milliseconds, 20 to 2000. Null when `format` is `still`. |
| `spellingCheck` | boolean | When true, Kenso checks the text in each image against the prompt and generates it once more if they differ. |
| `requiredForSending` | boolean | When true, Kenso holds a contact from steps that use the token until the contact's image is ready. |
| `enabled` | boolean | Whether a `per_prospect` variable is on. While it is on, Kenso generates an image for each eligible contact and charges credits for each ready image. Turning it off keeps the images that exist. |
| `altText` | string | Alt text of the image in the email, or null for none. |
| `sharedImage` | SharedImage | The current image of a `shared` variable, or the attempt that just failed. Null for a `per_prospect` variable and for a `shared` one with no image yet. |
| `counts` | ImageVariableCounts | How many contact images the variable has, by status. |
| `createdAt` | string (date-time) | When the variable was created, in UTC. |
| `updatedAt` | string (date-time) | When the variable last changed, in UTC. |

### Request

```bash
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"
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "key": "hero_image",
    "kind": "string",
    "prompt": "string",
    "references": [
      "profile_photo"
    ],
    "model": "string",
    "size": "1024x1024",
    "quality": "low",
    "format": "string",
    "frameCount": 1,
    "frameDurationMs": 1,
    "spellingCheck": true,
    "requiredForSending": true,
    "enabled": true,
    "altText": "string",
    "sharedImage": {
      "imageKey": "string",
      "status": "pending",
      "errorCode": "provider_refused",
      "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 a contact's image

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

| Permission | Credits | Rate limit |
| --- | --- | --- |
| Campaigns edit | Varies with the request (`campaign_image`) | 100 requests a day per workspace (Free plan: 10 a day) |

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.

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

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/image-variables/POST/v1/campaigns/%7BcampaignId%7D/image-variables/%7BvariableKey%7D/contacts/%7BcontactId%7D/regenerate)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `campaignId` | path | integer (int64) | yes | Id of the campaign. |
| `variableKey` | path | string | yes | Key of the image variable, such as `hero_image`. |
| `contactId` | path | integer (int64) | yes | Id of the contact. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Response 200

`data` is a `CampaignImage`.

| Field | Type | Description |
| --- | --- | --- |
| `imageKey` | string | The image's unique 26-character key. Read the image again with `GET /v1/campaign-images/{imageKey}`. |
| `contactId` | integer (int64) | Id of the contact the image belongs to. Omitted for an image that every contact shares. |
| `variableKey` | string | Key of the image variable the image fills, or `custom_image` for the contact's own image. Omitted when the image belongs to no current image variable. |
| `status` | string | State of the image: `pending` while Kenso makes or fetches it, `ready` once it is stored, or `failed`. |
| `errorCode` | string | Why the image failed, such as `timeout`, `not_an_image`, `too_large` or `provider_error`. Set when `status` is `failed`. |
| `errorDetail` | string | A readable explanation of the failure. Set when `status` is `failed`. |
| `width` | integer (int32) | Width of the image in pixels. Omitted while unknown. |
| `height` | integer (int32) | Height of the image in pixels. Omitted while unknown. |
| `previewUrl` | string | A link to view the ready image, valid until `previewExpiresAt`. Use it for viewing only, not inside an email. Omitted unless `status` is `ready`. |
| `previewExpiresAt` | string (date-time) | When `previewUrl` stops working, in UTC: 1 hour after the call. Omitted with `previewUrl`. |
| `updatedAt` | string (date-time) | When the image last changed, in UTC. |

### Request

```bash
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"
```

### Example response

```json
{
  "success": true,
  "data": {
    "imageKey": "string",
    "contactId": 812,
    "variableKey": "string",
    "status": "string",
    "errorCode": "timeout",
    "errorDetail": "string",
    "width": 1,
    "height": 1,
    "previewUrl": "https://example.com",
    "previewExpiresAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-09-23T15:02:11Z"
  }
}
```

## Types

Each named type the tables above use, nested ones included.

### SharedImage

The one image of a `shared` image variable.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `imageKey` | string | no | Key of the image, the same as on the campaign's image routes. |
| `status` | string | no | State of the image: `pending`, `ready` or `failed`. |
| `errorCode` | string | no | Why the image failed, such as `provider_refused` or `spelling_mismatch`. Null unless `status` is `failed`. |
| `previewUrl` | string | no | A link to view the image, valid until `previewExpiresAt`. Do not put it in emails or keep it. |
| `previewExpiresAt` | string (date-time) | no | When `previewUrl` stops working, in UTC, 1 hour after the call. |

### ImageVariableCounts

Counts of a `per_prospect` variable's contact images: the current ready and failed images, and every pending one.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ready` | integer (int32) | no | Contacts whose current image is ready. |
| `pending` | integer (int32) | no | Images that Kenso is still generating. |
| `failed` | integer (int32) | no | Contacts whose current image failed. |

### CampaignImage

An image Kenso made or stored for a campaign's emails.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `imageKey` | string | no | The image's unique 26-character key. Read the image again with `GET /v1/campaign-images/{imageKey}`. |
| `contactId` | integer (int64) | no | Id of the contact the image belongs to. Omitted for an image that every contact shares. |
| `variableKey` | string | no | Key of the image variable the image fills, or `custom_image` for the contact's own image. Omitted when the image belongs to no current image variable. |
| `status` | string | no | State of the image: `pending` while Kenso makes or fetches it, `ready` once it is stored, or `failed`. |
| `errorCode` | string | no | Why the image failed, such as `timeout`, `not_an_image`, `too_large` or `provider_error`. Set when `status` is `failed`. |
| `errorDetail` | string | no | A readable explanation of the failure. Set when `status` is `failed`. |
| `width` | integer (int32) | no | Width of the image in pixels. Omitted while unknown. |
| `height` | integer (int32) | no | Height of the image in pixels. Omitted while unknown. |
| `previewUrl` | string | no | A link to view the ready image, valid until `previewExpiresAt`. Use it for viewing only, not inside an email. Omitted unless `status` is `ready`. |
| `previewExpiresAt` | string (date-time) | no | When `previewUrl` stops working, in UTC: 1 hour after the call. Omitted with `previewUrl`. |
| `updatedAt` | string (date-time) | no | When the image last changed, in UTC. |

All resources: [/docs.md](/docs.md).
