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.

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

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

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