Developer Update: more consistency, fewer edge cases

If you integrate Picsart Creative APIs, this update is for you.

Over the last few months we have been collecting feedback from engineering teams and looking closely at where integrations get harder than they should be. The themes were consistent: standard patterns, predictable behavior, and fewer “special cases” per endpoint.

So we are making a set of platform changes that move us toward one clear goal.

One standard solution across all Creative APIs.

Below are the four updates that matter most for developers, plus what to do next.

If you are not the person coding the integration, please forward this to your engineering team.

1) Sync and async execution is moving to a standard HTTP approach

We are introducing a consistent way to control synchronous vs asynchronous execution using the standard HTTP Prefer header (RFC 7240).

This replaces the older pattern where some endpoints exposed a mode parameter.

What changes:

• You can explicitly request async behavior with Prefer: respond-async.
• You can request bounded waiting with Prefer: wait=<seconds> and get a clean async fallback if the result is not ready.

We recommend that teams start planning the transition now. Not every service supports this yet, but the direction is firm. We are rolling this out across services over time.

Docs: https://docs.picsart.io/docs/sync-async-execution

Quick mapping:

• Old: mode=async → New: Prefer: respond-async
• Old: mode=sync → New: Prefer: wait=60 (60 seconds is a practical default for sync-style behavior)

2) Deprecation deadline: _id input parameters will be removed on June 1, 2026

Historically, some endpoints accepted input resources using:

• image (binary upload)
• image_url
• image_id

We are deprecating support for input parameters that end in _id. This applies broadly across Programmable Image APIs and GenAI APIs. Examples include:

• image_id
• reference_image_id
• mask_id
• and other similar *_id parameters

Deadline:

• Support for _id input parameters will be removed on June 1, 2026.

What you should do now:

• Audit your usage for any *_id input params.
• Migrate to *_url inputs or binary upload inputs.

3) GenAI status values are being standardized

GenAI jobs have historically exposed a few different “in progress” states. That made status handling inconsistent across services.

We are standardizing GenAI job status values moving forward to:

• success
• error
• processing

Important note:

• processing simply means the job is accepted and still running.
• It does not indicate whether it has started, or whether it is 10% or 60% complete.
• This is intentional. It keeps integrations stable even when queue behavior changes.

Best practice for your code:

• Write your switch logic around success and error.
• Treat everything else as “keep waiting.” In the new model, that state is processing.

This avoids fragile logic that tries to infer internal progress.

4) JSON request bodies are now supported across services (plus base64 data URIs)

Historically, Programmable Image APIs used multipart/form-data so you could upload binary images directly.

That remains the right choice when you want true binary uploads.

But many integrations do not upload files at all. They pass image_url. In those cases, multipart/form-data adds complexity without value.

Update:

• We now support application/json request bodies across services.
• JSON requests do not support binary uploads.

Workaround option:

• You can now embed an image directly in image_url using a base64 data URI:
  image_url: "data:image/jpeg;base64,/9j/4QAiRXhpZgAASUkqAAgAAAABABIBA..."

This is production-ready, but not yet published as a global default across every public doc page. If you use it and hit any edge cases, reach out and we will help quickly.

What you should do next

Here is the practical checklist most teams will follow:

1) Start migrating sync/async control from mode to Prefer.
2) Remove _id input parameters before June 1, 2026.
3) Update GenAI polling logic to handle only success, error, processing.
4) If your integration is URL-driven, consider switching from multipart/form-data to JSON for simpler requests.

If you have questions, reply to this email thread in your inbox, or contact support here

If you include the endpoint, headers, and a sample request body, we can confirm the best migration path quickly.