---
title: "Edit an existing cover image with a text prompt (async)"
method: POST
path: "/api/v1/covers/{coverId}/edit-image"
tags: ["Covers"]
---

# Edit an existing cover image with a text prompt (async)

`POST /api/v1/covers/{coverId}/edit-image`

## Request

- Base URL: `https://beyourcover.com`
- URL: `https://beyourcover.com/api/v1/covers/{coverId}/edit-image`
- Auth: HTTP bearer

Applies an AI image edit to the cover's preview image, producing one new child cover. Costs 1 credit. The source cover must have a preview image. NOTE: the `prompt` limit on this endpoint is 1000 characters (route-local), not the 1500-character limit used by /covers/generate.

## Path parameters

- `coverId` string, uuid, required

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `prompt` string, required: Required non-empty edit instruction. Max 1000 characters. Subject to content moderation.
  - `external_ref` string: Optional caller-supplied reference. (Length/type limits are not enforced on this endpoint in code.)
  - `webhookUrl` string: Optional per-job webhook URL. (Length/type limits are not enforced on this endpoint in code.)

## Response `200`

Idempotent replay of an existing job with the same `Idempotency-Key`.

- JobReplay: 200 envelope returned when an Idempotency-Key matches an existing job. Unlike the fresh 202, `status` reflects the job's current state and `operation` is always present.
  - `jobId` string, uuid, required
  - `status` 'queued' | 'processing' | 'completed' | 'failed', required: Current status of the previously created job.
  - `operation` 'generate' | 'variation' | 'edit_image' | 'upscale' | 'audiobook_cover' | 'remove_text' | 'generate_reference' | 'wrap' | 'wrap_extend_front', required
  - `credits_reserved` integer: What the ORIGINAL job reserved. Returned by the variations, edit-image, upscale, audiobook-cover, remove-text, wraps and extend-front endpoints when the job recorded it.
  - `included_format` boolean: true when the book's marketing kit paid for the ORIGINAL job instead of credits. Returned by the edit-image, upscale, audiobook-cover, remove-text, wraps and extend-front endpoints.
  - `external_ref` string, nullable, required: The external_ref stored on the ORIGINAL job.
  - `created_at` string, date-time, required
  - `poll_url` string, required

## Other responses

- `202`: Job accepted and queued. `operation` is `edit_image`.
- `400`: `code` is one of: `missing_prompt`, `field_too_long` (prompt > 1000 chars), `missing_cover_image`, `content_policy_violation`.
- `401`: Missing/malformed API key, unknown or inactive key, or inactive subscription detected during credit checks. `code`: `unauthorized`.
- `402`: Not enough credits (monthly + overage) for the requested operation. `code`: `insufficient_credits`.
- `403`: The API key is valid but its owner has no active enterprise subscription. `code`: `forbidden`.
- `404`: Cover not found or not owned by this API key's user. `code`: `cover_not_found`.
- `429`: The subscription's concurrent-job limit is reached (jobs with status `queued` or `processing` count). `code`: `concurrency_limit`.
- `500`: Server error. `code` is `job_creation_failed` or `internal_error`. The reserved credit is refunded.

---

[API](https://skmtc.dev/beyourcover/apis/beyourcover-partner-api.md) · [All operations](https://skmtc.dev/beyourcover/apis/beyourcover-partner-api/llms.txt) · [OpenAPI document](https://skmtc.dev/beyourcover/apis/beyourcover-partner-api/revisions/82ad2c7c8ede?raw)