Images

Edit post image

Edits an existing Postiv image with a natural-language instruction, stacking a new version on the same image id. If attached to a post, the post publishes the newest version automatically. On an X post the edited version replaces the image inside the post in place.

POST/api/public/images/:id/edit

cURLPOST /api/public/images/:id/edit

curl -X POST https://postiv.ai/api/public/images/ID_ID/edit \
  -H "Authorization: Bearer pk_postiv_..." \
  -H "Content-Type: application/json" \
  -d '{
    "editPrompt": "Make the background darker and increase headline contrast."
  }'

200Response

{
  "success": true,
  "image": {
    "id": "img1...",
    "versionId": "v2...",
    "versionNumber": 2,
    "postId": "post1...",
    "style": "notebook_infographic",
    "width": 1080,
    "height": 1350,
    "imageUrl": "https://postiv-user-media.s3...",
    "generationTimeMs": 18342
  }
}

Authorization

Requires an organization API key with the images:write scope, sent as Authorization: Bearer or x-api-key.

Path parameters

idstringrequired

Resource id from the corresponding list or create endpoint.

Body parameters

editPromptstringrequired

1-4000 chars, trimmed.

Response

The edited image's new version.

image.iduuid

image.versionIduuid

image.versionNumberint

image.postIduuid|null

image.stylestring

image.width / heightint

image.imageUrlstring

Signed S3 URL (default TTL, NOT the 7-day widget TTL used by the MCP tool).

image.generationTimeMsint

image.channelstring

Channel of the post the image is attached to; null when it is attached to none.

image.assetId / tweetIndex / tweetId / articlePlacement / afterParagraph / replacedAssetIds / postVersionNumber / placedIn

mixed

X posts only: where the edited image now sits (the post's own asset, the tweet or the article placement), the assets it replaced and the post's new version number.

Errors

400	missing_edit_prompt / image_missing_content
403	image_permission_denied
404	image_not_found
422	content_blocked: blocked by the model's content filter
500	image_edit_failed
409	post_media_locked: the X post is scheduled or published (unschedule a scheduled post first)
409	x_image_not_in_post: the image was removed from the X post, so there is nothing to edit in place; generate a new image with the MCP tool generate_post_image
409	x_image_not_placed: the edit is saved but could not be placed in the X post; POST /api/public/posts/:id/media with the imageId finishes it (details.postId, imageId, versionId)

Good to know

There is NO REST endpoint to generate a brand-new image: that only exists as the MCP tool generate_post_image. This route is edit-only; requireOwnership is false (any workspace member's image is editable via the API key, not just the creator's).
On an X post the call is refused before any credits are spent if the post is scheduled or published, or if the image is no longer in the post.