Migrate a Remove.bg integration to Picsart Creative APIs

This guide covers the Creative APIs v1 endpoint https://api.picsart.io/tools/1.0/removebg. It is not the newer model-based API Platform contract. Changing the endpoint alone is insufficient: update authentication, request fields, output handling and tests.

Start with a minimal request

curl --fail --request POST \
  https://api.picsart.io/tools/1.0/removebg \
  --header "X-Picsart-API-Key: $PICSART_API_KEY" \
  --header "Accept: application/json" \
  --form "image=@/path/to/input.jpg" \
  --form "output_type=cutout" \
  --form "format=PNG"

Set your key securely in the environment before running the example. Keep it in server-side configuration. With --form, let curl create the multipart Content-Type boundary. The example is documentation-based; inspect and test it with your account before production use.

Map the request intentionally

• Authentication: replace the Remove.bg key/header with X-Picsart-API-Key and a Picsart key authorized for this API.
• Image: replace image_file with image for a file upload, or use image_url for a retrievable URL. Supply one source. Base64 input is not a direct replacement for these fields. The older image_id source is marked deprecated in the current reference.
• Format: request an explicit Picsart value such as PNG, JPG or WEBP. Do not carry over Remove.bg values such as auto or zip without a supported mapping. JPEG cannot preserve transparency.
• Cutout or mask: output_type=cutout requests the extracted foreground; mask requests a mask. These address a different concern from cropping.
• Crop and margins: Remove.bg crop and crop_margin have no assumed one-to-one mapping. In particular, output_type=cutout is not equivalent to crop=true.
• Canvas size: evaluate bg_width and bg_height for the required canvas. They do not directly reproduce Remove.bg resolution presets such as size.
• Scale and position: Picsart scale uses fit/fill choices; auto_center centers the cutout. Do not copy percentage scale or arbitrary position values unchanged.
• Background: review bg_color, bg_image_url and bg_blur against the target endpoint’s accepted values.
• Outline: Picsart exposes stroke_size, stroke_color and stroke_opacity; set them only if the desired design needs an outline.
• Other fields: do not forward type, type_level, roi or foreground-position metadata without an explicit supported replacement. If your app relies on that behavior, implement and test the missing step separately.

Change response handling

A client that expects image bytes or decodes Remove.bg data.result_b64 must handle the Picsart JSON response instead. A successful response includes status and an output URL under data.url, with a result identifier under data.id.

{"status":"success","data":{"id":"result-id.png","url":"https://cdn.picsart.io/example.png"}}

The URL above is illustrative. Check HTTP status and the JSON body, then download the returned URL to your own storage. Do not assume the output URL is permanent. Verify download status and use a filename extension matching the requested format.

Foreground coordinates/dimensions from a previous response contract are not automatically supplied by this response. Update any layout or cropping logic that depends on them.

Validate before switching traffic

1. Test representative subjects, fine edges, transparency, busy backgrounds and intended output dimensions.
2. Handle authentication, credit, validation, size/type, rate-limit and server errors separately. Do not treat every HTTP response as an image.
3. Use bounded retries for transient failures and retain enough non-secret diagnostics to investigate errors.
4. Check downstream storage and rendering, update your internal documentation and train maintainers on the new request/response contract.
5. Switch production traffic only after the new behavior meets your requirements, with a rollback path.

Consult the current Remove.bg API reference for your source integration. Legacy examples from May 2024 should not be treated as a current competitor contract.