> 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: Create an image variable

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

One endpoint of [Image variables](/docs/api/image-variables.md). Authentication, workspaces and errors: [/docs.md](/docs.md).

## 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"
  }
}
```

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