Skip to content
PLUNKDOCS
Create API key

Images

Before you start

Section titled “Before you start”
  • Check the cost first with GET /cx/v1/images/{id}/estimate. It returns the credits a set of operations would cost and your balance.
  • Long operations return a jobId. Poll GET /cx/v1/images/jobs/{jobId}.
  • Failed jobs refund their credits. See how credits work.

Endpoints

Section titled “Endpoints”

All paths are under https://api.plunk.io.

Method Endpoint What it does
GET /cx/v1/images List images. ?productId= &category= &approval= &q= &$top=
GET /cx/v1/images/{id} One image with its versions, placements, product and approval state
GET /cx/v1/images/{id}/versions Every version, newest last, with how each was made
GET /cx/v1/images/{id}/estimate Credits a set of operations would cost, and your balance. ?ops= &hires= &placements=
GET /cx/v1/images/{id}/exports Exports made for an image. ?versionId=
GET /cx/v1/images/jobs/{jobId} Job status (queued, running, done, failed), the new versionId, and the credits spent
GET /cx/v1/images/placements Placement sizes you can export to
GET /cx/v1/images/categories Image recipes by product category
POST /cx/v1/images Make new images. { prompt, productId?, references?, scene?, shotType?, aspect, count, language, placements? }. productId takes your product id or SKU. Spends credits
POST /cx/v1/images/{id}/ops Edit a version: { versionId, action: background | extend | retouch | recolor | straighten, params }. Spends credits
POST /cx/v1/images/{id}/hires High-resolution version: { versionId }. Spends credits
POST /cx/v1/images/{id}/approve { versionId, state: draft | in_review | approved, note? }
POST /cx/v1/images/{id}/export { versionId, placements, language?, hires: true }. May spend credits for high resolution
PUT /cx/v1/images/{id}/text Text layers on a version (free)
PUT /cx/v1/images/{id}/placements Placements to export to (free)
POST /cx/v1/images/upload Upload your own image: { fileName, contentType, bytes, rights: own | licensed | brand_supplied, rightsNote?, language?, productId? }. Returns a presigned uploadUrl (valid 15 minutes) and a token
POST /cx/v1/images/upload/{token}/complete After you PUT the file: registers it. Returns the new image, or the existing one if it’s a duplicate

Example: replace a background

Section titled “Example: replace a background”
Start the edit
curl -X POST "https://api.plunk.io/cx/v1/images/1843201/ops" \
  -H "Authorization: Bearer sk_live_••••" -H "Content-Type: application/json" \
  -d '{"versionId":"1843215","action":"background","params":{"mode":"scene:studio"}}'


# 202 Accepted
{ "jobId": "88123", "versionId": null }
Poll the job
curl "https://api.plunk.io/cx/v1/images/jobs/88123" -H "Authorization: Bearer sk_live_••••"


{ "id": "88123", "status": "done", "versionId": "1843220", "credits": 6, "error": null, … }

Errors

Section titled “Errors”
Status When
402 out_of_credits Your balance can’t cover the call
409 A version needs approval first, or is locked by a high-resolution run
422 Input it can’t use
429 daily_cap Your account’s daily image limit is reached
Section titled “Related”
Was this helpful?

Still stuck? Contact support and include the job or page you were on.