API Beta

Ship image workflows with OpusImg

A small, stable HTTP API for compression, conversion, and background removal. Beta access is included with Pro while we learn from production integrations.

Manage API keys Endpoint reference OpenAPI spec (JSON)

The machine-readable specification is served from this domain at opusimg.com/openapi.json — point your client generator, or your coding assistant, straight at it. An interactive Swagger UI is also available on the API host.

Quickstart

1. Create a keyOpen Developer API in your dashboard. Copy the secret when it appears—it is shown once.
2. Send multipart dataAuthorize with a Bearer key and attach one image field plus endpoint parameters.
3. Handle the resultCompress and convert return bytes; background removal returns a job to poll.

Beta pricing and limits

Access	Included usage	Rate limit	Input
Pro, Business	1,000 operations/month per account	30 requests/minute per account	20 MB maximum

The allowance is per account and shared by all of its keys. During the beta, API operations do not debit AI credits; this beta allowance may change, with notice, when API pricing launches. Higher-volume API pricing is not yet available; when it launches it will be published here at a fixed rate. Get in touch with any questions.

Endpoint reference

Every public endpoint, generated from the OpenAPI specification so it cannot drift from the API. Base URL: https://api.opusimg.com. Authenticate every request with Authorization: Bearer $KEY.

Public API v1

POST/v1/compressBearer key

Compress an image

Re-encode an image at a lower quality, optionally changing format at the same time. Synchronous: the compressed bytes come back in the response body.

Parameters

Name	Type	In	Description
`image`required	file	multipart/form-data	The source image. JPEG, PNG, WebP or AVIF, 20 MB maximum.
`quality`	integer	multipart/form-data	Encoder quality. 75-85 is the usual range.Default: `80`
`format`	string (jpeg \| png \| webp \| avif)	multipart/form-data	Output format. Defaults to the input format.

Responses

200: The transformed image bytes, with a Content-Type of image/*.(image/*)
401: No API key, or a key that is invalid, expired or revoked.(application/json)
403: The key's plan or scopes do not permit this operation.(application/json)
413: The input image is larger than 20 MB.(application/json)
422: The request is missing an image, or a parameter is invalid.(application/json)
429: Rate limit or monthly operation cap exceeded. See Retry-After.(application/json)

POST/v1/convertBearer key

Convert an image to another format

Re-encode an image into a different format. Synchronous: the converted bytes come back in the response body.

Parameters

Name	Type	In	Description
`image`required	file	multipart/form-data	The source image. JPEG, PNG, WebP or AVIF, 20 MB maximum.
`format`required	string (jpeg \| png \| webp \| avif)	multipart/form-data	Required. The format to convert to.
`quality`	integer	multipart/form-data	Encoder quality. 75-85 is the usual range.Default: `80`

Responses

200: The transformed image bytes, with a Content-Type of image/*.(image/*)
401: No API key, or a key that is invalid, expired or revoked.(application/json)
403: The key's plan or scopes do not permit this operation.(application/json)
413: The input image is larger than 20 MB.(application/json)
422: The request is missing an image, or a parameter is invalid.(application/json)
429: Rate limit or monthly operation cap exceeded. See Retry-After.(application/json)

POST/v1/remove-backgroundBearer key

Remove an image background

Queue an AI background removal. Asynchronous: returns 202 with a job id immediately, then poll GET /v1/jobs/{id} until status is done.

Parameters

Name	Type	In	Description
`image`required	file	multipart/form-data	The source image. JPEG, PNG, WebP or AVIF, 20 MB maximum.
`background`	string	multipart/form-data	transparent, or a CSS colour to composite the cut-out onto.Default: `"transparent"`
`refine_edges`	boolean	multipart/form-data	Run the edge refinement pass.Default: `true`

Responses

202: The job was queued.(application/json)
401: No API key, or a key that is invalid, expired or revoked.(application/json)
403: The key's plan or scopes do not permit this operation.(application/json)
413: The input image is larger than 20 MB.(application/json)
422: The request is missing an image, or a parameter is invalid.(application/json)
429: Rate limit or monthly operation cap exceeded. See Retry-After.(application/json)

GET/v1/jobs/{id}Bearer key

Get the status of a job

Poll a queued job. Once status is done the response carries a short-lived presigned download_url for the output. Polling does not count toward the monthly operation cap.

Parameters

Name	Type	In	Description
`id`required	string	path	The job id returned when the job was queued.

Responses

200: The current state of the job.(application/json)
401: No API key, or a key that is invalid, expired or revoked.(application/json)
403: The key's plan or scopes do not permit this operation.(application/json)
404: No such job, or it belongs to another key's owner.(application/json)
429: Rate limit exceeded. See Retry-After.(application/json)

Webhooks

GET/v1/webhooksBearer key

List webhook endpoints

List every webhook endpoint registered for this API key's owner.

Responses

200: The registered endpoints.(application/json)
401: No API key, or a key that is invalid, expired or revoked.(application/json)

POST/v1/webhooksBearer key

Register a webhook endpoint

Register an endpoint to receive job_completed and job_failed deliveries. The signing secret is returned once, at creation, and never again.

Parameters

Name	Type	In	Description
`url`required	string	application/json	HTTPS URL to deliver to.
`events`	array of string	application/json	Events to deliver. Defaults to both.Default: `["job_completed","job_failed"]`

Responses

201: Created. Store the secret now.(application/json)
400: The URL or event list is invalid.(application/json)
401: No API key, or a key that is invalid, expired or revoked.(application/json)

DELETE/v1/webhooks/{id}Bearer key

Delete a webhook endpoint

Permanently remove an endpoint. Undelivered retries for it are abandoned.

Parameters

Name	Type	In	Description
`id`required	string	path	The webhook endpoint id.

Responses

204: Deleted.(application/json)
401: No API key, or a key that is invalid, expired or revoked.(application/json)
404: No such endpoint for this owner.(application/json)

PATCH/v1/webhooks/{id}Bearer key

Update a webhook endpoint

Change an endpoint's URL, event list, or enabled state. Send at least one field.

Parameters

Name	Type	In	Description
`id`required	string	path	The webhook endpoint id.
`url`	string	application/json
`events`	array of string	application/json	Events to deliver. Defaults to both.Default: `["job_completed","job_failed"]`
`enabled`	boolean	application/json

Responses

200: The updated endpoint.(application/json)
401: No API key, or a key that is invalid, expired or revoked.(application/json)
404: No such endpoint for this owner.(application/json)

POST/v1/webhooks/{id}/rotate-secretBearer key

Rotate a webhook signing secret

Issue a new signing secret and invalidate the old one immediately. The new secret is returned once.

Parameters

Name	Type	In	Description
`id`required	string	path	The webhook endpoint id.

Responses

200: The new secret.(application/json)
401: No API key, or a key that is invalid, expired or revoked.(application/json)
404: No such endpoint for this owner.(application/json)

Worked examples

Compress

Synchronous image compression. The response body is the transformed image.

curl

curl -X POST https://api.opusimg.com/v1/compress \
  -H "Authorization: Bearer $OPUSIMG_API_KEY" \
  -F "image=@photo.jpg" \
  -F "quality=80" \
  -F "format=webp" \
  --output photo.webp

JavaScript

const form = new FormData();
form.append("image", file);
form.append("quality", "80");
form.append("format", "webp");

const response = await fetch("https://api.opusimg.com/v1/compress", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.OPUSIMG_API_KEY}` },
  body: form,
});
const image = await response.blob();

Convert

Synchronous conversion to JPEG, PNG, WebP, or AVIF.

curl

curl -X POST https://api.opusimg.com/v1/convert \
  -H "Authorization: Bearer $OPUSIMG_API_KEY" \
  -F "image=@photo.png" \
  -F "format=avif" \
  -F "quality=82" \
  --output photo.avif

JavaScript

const form = new FormData();
form.append("image", file);
form.append("format", "avif");
form.append("quality", "82");

const response = await fetch("https://api.opusimg.com/v1/convert", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.OPUSIMG_API_KEY}` },
  body: form,
});
const image = await response.blob();

Remove background

Asynchronous background removal. Poll the returned status URL until the job completes.

curl

curl -X POST https://api.opusimg.com/v1/remove-background \
  -H "Authorization: Bearer $OPUSIMG_API_KEY" \
  -F "image=@portrait.jpg" \
  -F "background=transparent" \
  -F "refine_edges=true"

JavaScript

const form = new FormData();
form.append("image", file);
form.append("background", "transparent");
form.append("refine_edges", "true");

const job = await fetch("https://api.opusimg.com/v1/remove-background", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.OPUSIMG_API_KEY}` },
  body: form,
}).then((response) => response.json());
// GET job.status_url until status is "done".

Job webhooks

Register an endpoint through API v1 to receive job_completed and job_failed events. Deliveries contain job and asset references—not image bytes—and are signed with HMAC-SHA256 in X-OpusImg-Signature. Failed deliveries are retried three times with exponential backoff.

View the webhook management endpoints