{"openapi":"3.1.0","info":{"title":"Clearcut API","version":"0.2.0","description":"Image background removal and editing with temporary private image storage. Verified accounts receive 30 free credits per calendar month, shared across the website, bulk editor and API. Fast costs 1 credit per image; Fine costs 2. Free credits renew on the first of each month at 00:00 UTC, do not roll over, and are used before purchased credits. One-time packs start at $3 USD for 30 credits before tax, with no expiry. See https://clearcut.sh/pricing for current plans and limits."},"servers":[{"url":"https://clearcut.sh","description":"Clearcut API"}],"paths":{"/v1.0/removebg":{"post":{"operationId":"remove_background","summary":"Remove a background","description":"Remove a background and return an image in one request. Requires an API key. If processing takes more than 55 seconds, returns 202 with a job ID; poll that job instead of creating another.","security":[{"apiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":128},"description":"Reuse for retries of identical source and options."}],"responses":{"200":{"description":"Success","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"202":{"description":"Still processing. Poll the returned job ID."},"default":{"description":"Structured error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image_file":{"type":"string","format":"binary","description":"JPG, PNG or WebP file, up to 22 MB. Choose exactly one input source."},"image_url":{"type":"string","description":"Public HTTP or HTTPS image URL. Private hosts, credentials, non-standard ports and unsafe redirects are rejected."},"image_file_b64":{"type":"string","description":"Base64-encoded image bytes. Choose this instead of a file or URL."},"quality":{"type":"string","description":"Fast uses 1 credit. Fine detail (quality) uses 2. Output resolution is independent of quality.","enum":["fast","quality"],"default":"fast"},"size":{"type":"string","description":"auto, preview and small fit within 625 × 400 pixels. full and 50MP preserve original dimensions, up to 50 MP. No upscaling.","enum":["auto","preview","small","full","50MP"],"default":"auto"},"format":{"type":"string","description":"auto chooses JPG for a background or PNG for transparency. ZIP contains color.jpg and alpha.png.","enum":["auto","png","jpg","webp","zip"],"default":"auto"},"bg_color":{"type":"string","description":"Three- or six-digit hex color, with or without #."},"bg_image_url":{"type":"string","description":"Public image URL for a replacement background. Mutually exclusive with bg_image_file."},"bg_image_file":{"type":"string","format":"binary","description":"Replacement background file, up to 22 MB."},"crop":{"type":"boolean","description":"Crop to the detected subject bounds.","default":false},"crop_margin":{"type":"integer","description":"Padding around cropped subject, in pixels. Integer from 0 to 1,000.","default":0},"add_shadow":{"type":"boolean","description":"Add a drop shadow when no shadow_type is selected.","default":false},"shadow_type":{"type":"string","description":"Choose a generated contact or drop shadow.","enum":["none","drop","ground","car"],"default":"none"},"shadow_opacity":{"type":"integer","description":"Shadow opacity from 0 to 100.","default":35},"semitransparency":{"type":"boolean","description":"Preserve soft edges. false thresholds alpha at 128.","default":true},"channels":{"type":"string","description":"Return color with transparency or a grayscale alpha mask.","enum":["rgba","alpha"],"default":"rgba"}},"required":[]}}}}}},"/api/jobs":{"post":{"operationId":"create_job","summary":"Create an image job","description":"Queue an image and return immediately. API keys always use credits. The browser editor uses credits first; at zero balance, Fast processing can use the five-per-day free allowance. Files expire after one hour.","security":[{"apiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":128},"description":"Reuse for retries of identical source and options."}],"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{},"example":{"id":"image_id","name":"photo.jpg","status":"queued","quality":"fast","credits":1,"created":1789052400,"expires":1789056000,"original_url":"/api/files/image_id/original.png"}}}},"default":{"description":"Structured error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image_file":{"type":"string","format":"binary","description":"JPG, PNG or WebP file, up to 22 MB. Choose exactly one input source."},"image_url":{"type":"string","description":"Public HTTP or HTTPS image URL. Private hosts, credentials, non-standard ports and unsafe redirects are rejected."},"quality":{"type":"string","description":"Fast uses 1 credit. Fine detail (quality) uses 2. Output resolution is independent of quality.","enum":["fast","quality"],"default":"fast"}},"required":[]}}}}},"get":{"operationId":"list_jobs","summary":"List images","description":"Return your latest 100 unexpired images. This endpoint does not expose another account’s images.","security":[{"apiKey":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{},"example":[{"id":"image_id","name":"photo.jpg","status":"queued","quality":"fast","credits":1,"created":1789052400,"expires":1789056000,"original_url":"/api/files/image_id/original.png"}]}}},"default":{"description":"Structured error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/jobs/{id}":{"get":{"operationId":"get_job","summary":"Get a job","description":"Poll until status is done or error. Poll about once every 2 seconds. Files are private and use the same session or API key as the job.","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{},"example":{"id":"image_id","name":"photo.jpg","status":"done","quality":"fast","credits":1,"created":1789052400,"expires":1789056000,"original_url":"/api/files/image_id/original.png","width":1200,"height":800,"result_url":"/api/files/image_id/cutout.png","mask_url":"/api/files/image_id/mask.png"}}}},"default":{"description":"Structured error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"delete_job","summary":"Delete an image","description":"Delete the image files immediately. Processing must finish first. Successful processing is not refunded by deletion.","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{},"example":{"deleted":true}}}},"default":{"description":"Structured error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/files/{id}/{filename}":{"get":{"operationId":"download","summary":"Download a result","description":"Download original.png, cutout.png, mask.png or a generated file belonging to your image. Include your API key. Links expire with the job.","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"filename","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"Structured error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/jobs/{id}/export":{"post":{"operationId":"export","summary":"Export an edited image","description":"Render a finished image using the same settings as the editor. Export uses no extra credits. Add ?prepare=true to receive a private download URL.","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"Structured error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"format":{"type":"string","description":"Output format.","enum":["png","jpg","webp"],"default":"png"},"size":{"type":"string","description":"Output dimensions.","enum":["full","preview"],"default":"full"},"settings":{"type":"object","description":"Editor settings. See the edit example."},"background":{"type":"string","description":"An included background path or a background URL returned for this job."},"mask":{"type":"string","description":"Optional Base64 PNG alpha mask from the manual brush."}},"required":[]}}}}}},"/api/jobs/{id}/background":{"post":{"operationId":"background","summary":"Upload a background","description":"Add a replacement photo to an existing image. Use the returned URL in an export.","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{},"example":{"url":"/api/files/image_id/bg_background-id.png"}}}},"default":{"description":"Structured error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image_file":{"type":"string","format":"binary","description":"JPG, PNG or WebP file, up to 22 MB. Choose exactly one input source."},"image_url":{"type":"string","description":"Public HTTP or HTTPS image URL. Private hosts, credentials, non-standard ports and unsafe redirects are rejected."}},"required":[]}}}}}},"/api/batch/export":{"post":{"operationId":"batch_export","summary":"Export a ZIP batch","description":"Render 1–100 finished images into a ZIP, up to 300 MB. Every image must belong to you. Processing is billed per image when submitted; ZIP export uses no additional credits.","security":[{"apiKey":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"Structured error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{},"description":"Job IDs, used with one shared spec."},"spec":{"type":"object","description":"Shared export settings."},"items":{"type":"array","items":{},"description":"Alternative to ids: objects with id and spec, allowing different edits per image."}},"required":[]}}}}}},"/api/batch/background":{"post":{"operationId":"batch_background","summary":"Copy a batch background","description":"Copy an uploaded background to 1–100 images in your account. Use the returned per-image URLs when exporting.","security":[{"apiKey":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{},"example":{"image_id":"/api/files/image_id/bg_background-id.png"}}}},"default":{"description":"Structured error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source_id":{"type":"string","description":"Image owning the source background."},"background":{"type":"string","description":"Source background URL."},"ids":{"type":"array","items":{},"description":"Target image IDs."}},"required":["source_id","background","ids"]}}}}}},"/api/jobs/{id}/segment":{"post":{"operationId":"smart_brush","summary":"Smart Brush","description":"Select a region or object with 1–32 stroke points in original image coordinates. Selection balances model confidence with the painted stroke; it can extend to detected boundaries beyond the brush. Returns a PNG selection mask; the caller applies it to the editor. Uses 1 credit per request.","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":128},"description":"Reuse for retries of identical source and options."}],"responses":{"200":{"description":"Success","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"Structured error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"points":{"type":"array","items":{},"description":"Ordered [x, y] stroke coordinates inside the image. Include both ends and sample evenly along the path."},"radius":{"type":"number","description":"Brush radius in original-image pixels, greater than zero and at most the longest image edge. Defaults to 2% of the longest edge. Used to rank selection candidates against the painted area."},"mode":{"type":"string","description":"Intended editor action. Both modes return the same detected boundary, without an extra erase margin; the caller subtracts or restores the mask.","enum":["erase","restore"],"default":"erase"}},"required":["points"]}}}}}},"/api/jobs/{id}/generate":{"post":{"operationId":"generate_scene","summary":"Generate a scene","description":"Generate an empty background matched to the current subject by default. The original cutout remains a separate, movable layer. Apply suggested_settings together with your placement settings when exporting to add the suggested contact shadow. Large placement changes may need a new scene. Optional AI operation, 3 credits per successful request. Failed operations refund credits. Reuse an Idempotency-Key for the same request; do not automatically retry with a new key.","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":128},"description":"Reuse for retries of identical source and options."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{},"example":{"url":"/api/files/image_id/bg_background-id.png","matched":true,"suggested_settings":{"shadow":35,"shadowType":"ground"}}}}},"default":{"description":"Structured error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"match_subject":{"type":"boolean","description":"Match the scene to the cutout, placement and lighting. Set false for an independent backdrop.","default":true},"settings":{"type":"object","description":"Current export settings, including ratio, scale, position, rotation and color adjustments. Background, text and shadow are excluded from the reference. Used when matching."},"mask":{"type":"string","description":"Optional PNG or WebP mask as a base64 data URL, white to keep and black to erase. Used when matching; include the same mask when exporting."},"prompt":{"type":"string","description":"Describe the setting in 1–1,000 characters. Recommended. Omitting it uses the legacy style preset."},"background":{"type":"string","description":"Optional visual reference: a background belonging to this image or an included background. Omit for prompt-only generation."},"style":{"type":"string","description":"Legacy preset, used only when prompt is omitted.","enum":["studio","nature","city","interior","beach"],"default":"studio"},"seed":{"type":"integer","description":"Deprecated. Accepted for older clients but ignored by the scene generator; output is not seed-reproducible."}},"required":[]}}}}}},"/api/account":{"get":{"operationId":"account","summary":"Credit balance","description":"Read your shared website/API balance and free website allowance. Verified accounts receive 30 free credits per calendar month. API requests use monthly free or purchased credits, never the five-per-day website allowance. monthlyFree reports the remaining monthly credits and next renewal as a Unix timestamp.","security":[{"apiKey":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{},"example":{"credits":30,"monthlyFree":{"limit":30,"remaining":30,"renewsAt":1790812800},"freeRemaining":0,"freeLimit":5}}}},"default":{"description":"Structured error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/jobs/{id}/retry":{"post":{"operationId":"retry_job","summary":"Retry a failed image","description":"Create a new attempt from the stored source of a failed job. Returns a new job ID. The old failed reservation was returned; this attempt reserves credits again.","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{},"example":{"id":"image_id","name":"photo.jpg","status":"queued","quality":"fast","credits":1,"created":1789052400,"expires":1789056000,"original_url":"/api/files/image_id/original.png"}}}},"default":{"description":"Structured error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/usage":{"get":{"operationId":"usage","summary":"Recent usage","description":"Read the latest 100 processing and AI-edit ledger records for your account. Error records show the original reservation; the reservation has been returned.","security":[{"apiKey":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{},"example":[{"id":"image_id","name":"photo.jpg","quality":"fast","status":"done","credits":1,"created":1789052400}]}}},"default":{"description":"Structured error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}