Object Extractor API

About Object Extractor

Cut out only the object you describe, as a transparent PNG.

Call it with the model name popnow/object-extractor-v1/edit on POST /jobs/createTask, from $0.024.

Introduction

Object Extractor isolates one thing in a photo from a text description and returns it on a transparent background. Where a background remover keeps every foreground subject, this endpoint keeps only the object you name.

Request

{
 "image_url": "https://example.com/bar.jpg",
 "prompt": "the woman in the cream sweater",
 "refine_edges": true,
 "autocrop": false
}

image_url and prompt are required. refine_edges adds a background-removal pass that cleans up leftover pixels around the edges. autocrop trims the canvas to the object instead of keeping the full photo size.

What we saw in testing

In a 1536×864 bar scene, "the woman in the cream sweater" came back alone at 1536×864 after about 17 seconds, with clean hair and sweater edges. With autocrop on, "the wine glass in front of the man" came back as a 130×307 PNG; the background seen through the glass stayed inside it. A coffee mug held in two hands came back with gaps where the fingers covered it. A request without a description returned the photo unchanged.

Task flow

Extraction is asynchronous.

Tips

• Be specific when there are look-alikes: "the taller bottle on the left" beats "the bottle".
• Keep autocrop off when you want to put the cutout back in the same position later.
• For every subject at once, Background Remover (/api/background-remover-v1) is the simpler tool.

Request parameters

Pricing

Prices are in USD. The API uses a separate USD balance. Website credits cannot be used or transferred to it, and API funds cannot be transferred to website credits. When a task is accepted, we reserve the maximum quoted amount from your API balance. On completion, we charge for actual usage, never more than the hold, and release the remainder. If the task fails, the hold is released.

Send the same request body to POST /jobs/quote to see the estimated and maximum USD charge before running. A quote does not run the task or charge your balance.

API quick start

Call the Object Extractor API in three steps

1. Create an API key. Sign in to PopNow and create a key in the API console. Keys start with sk-popnow-. API calls use your separate USD balance.
2. Send the request. POST /jobs/createTask with model popnow/object-extractor-v1/edit and an input object that follows the parameter table. The response returns a task ID straight away.
3. Get the result. Poll GET /jobs/recordInfo with the task ID, or pass a callBackUrl and we post the result to it. Download the output links when the task succeeds.

# 1. Create the task. Keep the Idempotency-Key if you retry after a network error.
export IDEMPOTENCY_KEY="$(uuidgen)"
curl -X POST https://api.popnow.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
  "model": "popnow/object-extractor-v1/edit",
  "input": {
    "prompt": "A ceramic teapot on a linen cloth, soft window light, muted palette",
    "image_url": "https://media.popnow.ai/influencer/examples/marco.webp"
  }
}'

# 2. Copy data.taskId from the response, then poll until state is succeeded, failed, canceled or expired.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.popnow.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
  -H "Authorization: Bearer $POPNOW_API_KEY"

Replace the prompt and any links with your own. The API tab has the response, polling and callback reference.

Object Extractor API questions

More about Object Extractor

Try it

Object Extractor AI Image Generator onlineCreate images with Object Extractor in PopNow

Docs

Object Extractor model ID and input schema in the API docsPopNow API quickstart: send your first requestImage generation guide for the PopNow APIWebhooks: get Object Extractor results without polling