---
title: "Create an image replacement on an AutoGenerator slide"
method: POST
path: "/api/v1/autogenerator/replace-image"
tags: ["AutoGenerator"]
---

# Create an image replacement on an AutoGenerator slide

`POST /api/v1/autogenerator/replace-image`

Swaps an image on a slide with a new image sourced from the
caller's workspace, Adobe Stock, Freepik, a previously uploaded
file, an extracted image, or S3.

The target slide's S3 location is resolved from
`slide_callback_id` — it is not supplied by the caller.

## Query parameters

- `callback_id` string, required

## Request body

- AutoGeneratorReplaceImageRequest — Request body for `POST /api/v1/autogenerator/replace-image`.
  - `oldImage` object, required — Description of the existing image being replaced.
    - `meta` object, required — Image metadata (size, position, etc.).
    - `shapeType` string, required — PowerPoint shape type.
  - `newImage` object, required — Description of the replacement image. `imageIndex` and `source` are always required; the remaining fields depend on `source`: | `source` | Additionally required | |---|---| | `myWorkspace` | `s3_path`, `s3_bucket` | | `s3` | `s3_path`, `s3_bucket` | | `brand-images` | `s3_path` | | `extracted` | `s3_path` (bucket is resolved server-side) | | `adobe` | `id` | | `freepik` | `id` | | `upload` | `image`, `extension` |
    - `imageIndex` integer, required — Index of the image to replace on the slide.
    - `source` 'myWorkspace' | 'adobe' | 'freepik' | 'upload' | 'extracted' | 's3' | 'brand-images', required — Source of the replacement image.
    - `s3_path` string — S3 key when `source` is `myWorkspace`, `s3`, `brand-images`, or `extracted`.
    - `s3_bucket` string — S3 bucket when `source` is `myWorkspace` or `s3`.
    - `id` string — Image id when `source` is `adobe` or `freepik`.
    - `image` string — Base64-encoded image content when `source` is `upload`.
    - `extension` string — File extension (e.g. `png`, `jpg`) when `source` is `upload`.
  - `slide_callback_id` string, required — Slide callback id where the image lives. The slide's S3 bucket and path are resolved from this id.
  - `duplicate_slide_callback_id` string — Optional duplicate slide id to mirror the replacement onto.

## Response `200`

Image replacement completed.

- AutoGeneratorMessageDataResponse — Standard success envelope. Endpoint-specific schemas extend this and constrain the `data` property to their concrete shape. Additional legacy keys (`status`, `log`, …) may appear alongside `success`/`data` for backwards compatibility, and some legacy handlers omit `success`, so it is not marked required.
  - `success` boolean — `true` on success (omitted by some legacy handlers).
  - `data` object, required — Service-specific payload.

## Other responses

- `400` — Generic client error. `error.code` is one of `BAD_REQUEST`, `INVALID_JSON`, `MISSING_REQUIRED_FIELD`, `MISSING_QUERY_PARAM`, `MISSING_CALLBACK_ID`, `MISSING_SLIDES_ARRAY`, `MISSING_PROMPT`, `MISSING_TEMPLATE_ID`, `MISSING_FILE_CONTENT`, `MISSING_SHARE_DETAILS`, `INVALID_TYPE`, `INVALID_DATA`, `INVALID_DATA_TYPE`, `INVALID_PAYLOAD`, `INVALID_REQUEST`, `API_REQUEST_FAILED`, or `FILE_UPLOAD_FAILED`.
- `401` — Caller did not present a valid Bearer token, or the token has expired. `error.code` is one of `UNAUTHORIZED`, `INVALID_API_KEY`, `EXPIRED_API_KEY`.
- `403` — Caller is authenticated but not allowed to perform this operation. `error.code` is `FORBIDDEN`.
- `404` — Requested endpoint or resource does not exist. `error.code` is one of `ENDPOINT_NOT_FOUND`, `RESOURCE_NOT_FOUND`, `NOT_FOUND`.
- `422` — Request was well-formed but failed semantic validation. `error.code` is one of `INVALID_INPUT`, `UNPROCESSABLE_ENTITY`.
- `429` — Rate limit, usage limit, or gateway-level throttle exceeded. `error.code` is `TOO_MANY_REQUESTS` (gateway throttle), `RATE_LIMIT_EXCEEDED` (per-category), or `USAGE_LIMIT_EXCEEDED` (annual quota). Default limits (all configurable per company/key): - Gateway throttle (per API key) → `TOO_MANY_REQUESTS`: 10 requests/second sustained, 5 burst, 1,000 requests/day. - Per-company, per-category sliding 60-second window → `RATE_LIMIT_EXCEEDED`. The applicable category is given by each operation's `x-rate-limit-category`. - Annual usage quota → `USAGE_LIMIT_EXCEEDED`: 50,000 slide generations/year and 1,000,000 presentation downloads/year. `X-RateLimit-Limit`/`X-RateLimit-Remaining`/`X-RateLimit-Reset` are returned on successful (2xx) responses from rate-limited endpoints and, with `Retry-After`, on the per-category `RATE_LIMIT_EXCEEDED` 429 (the headers declared below). The gateway `TOO_MANY_REQUESTS` and annual `USAGE_LIMIT_EXCEEDED` responses do not carry them. Read `X-RateLimit-Remaining` to self-throttle and honour `Retry-After` on a 429.
- `500` — Unexpected server error. `error.code` is `INTERNAL_SERVER_ERROR`.
- `503` — Service is temporarily unavailable (downstream dependency unhealthy). `error.code` is `SERVICE_UNAVAILABLE` or `EXTERNAL_SERVICE_ERROR`.
- `504` — A downstream call timed out. `error.code` is `GATEWAY_TIMEOUT`.

---

[API](https://skmtc.net/prezent/apis/prezent-platform-api.md) · [All operations](https://skmtc.net/prezent/apis/prezent-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/prezent/prezent-platform-api/revisions/a01cb764a085/schema)