> 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: Set a shared image variable's image

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

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

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