Your studio. In code.

Turn everyday product photos into polished images with a simple API.

API_BASEhttps://api.reimaginalo.com

Upload an image
Send a product photo with your preferred settings.
Check the status
Poll the returned ID to see when your image is ready.
Download the result
Retrieve your finished image from the provided URL.

Make your first request

One image. One request.

1curl -X POST "$API_BASE/v1/generations" \
2  -H "Authorization: Bearer $API_KEY" \
3  -H "Idempotency-Key: $REQUEST_KEY" \
4  -F 'image=@shirt.jpg' \
5  -F 'quality=low' \
6  -F 'mode=default'

202 AcceptedPoll the returned ID to retrieve your image.

Set API_BASE, API_KEY, and a unique REQUEST_KEY. Reuse REQUEST_KEY when retrying this image.

Use a local file named shirt.jpg. Set API_BASE and API_KEY before running an example. Python requires requests; JavaScript requires Node.js 20+.

Authentication

Create a named key under Account → API keys and copy it once. Authenticate every request with a bearer token in the Authorization header.

Request header

Authorization: Bearer <api_key>

Your key stays on your server.

Keep keys out of browser code and source control. Each account supports five active keys, valid until revoked. Revocation blocks new requests immediately; accepted generations continue.

API access is available to all accounts. API keys cannot manage subscriptions or other keys.

Endpoints

Choose an endpoint to see everything needed to call it. Examples use API_BASE and API_KEY from the quickstart.

POST/v1/generationsGenerate an image

Generate an image

Upload one product photo. Returns a generation immediately; the image is processed asynchronously.

Inputs

Body: multipart/form-data. Let your HTTP client set Content-Type and its boundary. JSON and remote image URLs are not accepted.

Field	Type	Details
`Authorization`	`string · header`	Required on every endpoint: Bearer <api_key>.
`Idempotency-Key`	`string · header`	Optional, recommended. 1–128 visible ASCII characters, no spaces. Reuse with identical file and settings to retry safely.
`image`	`binary · form`	Required. One JPEG, PNG, WebP, HEIC or HEIF; ≤5 MiB, ≤25 megapixels, ≤12,000 pixels per edge.
`quality`	`string · form`	Optional. Default: low (1 credit); medium costs 1.5 credits; high costs 3 credits.
`mode`	`string · form`	Optional. Default: default (invisible mannequin). Other modes: wall_shadow (studio wall shadow), enhanced_original (polish the original presentation), subtle_movement (natural movement).
`background_color`	`string · form`	Optional. Default: #FFFFFF. Six-digit hex with or without #, normalized to uppercase #RRGGBB. Generated output is JPEG.

Request example

cURL

1curl --request POST "$API_BASE/v1/generations" \
2  -H "Authorization: Bearer $API_KEY" \
3  -H "Idempotency-Key: product-shirt-001" \
4  -F 'image=@shirt.jpg' \
5  -F 'quality=low' \
6  -F 'mode=default' \
7  -F 'background_color=#FFFFFF'

Response 202 Accepted · Generation

application/json · Illustrative example; IDs, dates and URLs will differ.

Response body

1{
2  "id": "ad7cc504-91d3-4b6e-b12f-624b967a8250",
3  "status": "queued",
4  "quality": "low",
5  "mode": "default",
6  "background_color": "#FFFFFF",
7  "created_at": "2026-09-24T10:00:00Z",
8  "completed_at": null,
9  "output": null,
10  "error": null
11}

Response headers

Location: /v1/generations/ad7cc504-91d3-4b6e-b12f-624b967a8250
Retry-After: 3

Explore response fields & types

Field	Type	Details
`id`	`string · UUID`	Unique attempt ID. Use this to poll, including for website regenerations.
`status`	`string · enum`	queued \| processing \| completed \| failed
`quality`	`string · enum`	low \| medium \| high
`mode`	`string · enum`	default \| wall_shadow \| enhanced_original \| subtle_movement
`background_color`	`string`	Normalized uppercase #RRGGBB.
`created_at`	`string · date-time`	Creation time in ISO 8601 format.
`completed_at`	`string \| null`	Completion time (ISO 8601), or null if not available.
`output`	`object \| null`	Available when the individual result is ready; null while pending, on failure, and in history.
`output.url`	`string`	Temporary download URL. Download without your API key.
`output.expires_at`	`string · date-time`	URL expiry (ISO 8601); one hour after retrieval.
`output.content_type`	`string`	image/jpeg
`output.width`	`integer \| null`	Image width in pixels, when available.
`output.height`	`integer \| null`	Image height in pixels, when available.
`error`	`string \| null`	Failure message when status is failed; otherwise null.

What happens behind the request

Credits are reserved on acceptance; failed attempts are refunded once. API and website generations share the same credit balance and image library, with your account’s usual availability and expiry rules. Processing continues after the response. Poll the returned ID every 3 seconds, backing off to 15 seconds. An identical idempotent retry returns the same attempt and its current status, even if already completed or failed.

Possible errors: 400 / 422 · 401 · 402 · 409 · 413 · 429 · 5xx. Error format & recovery →

GET/v1/generations/{generation_id}Check status & download

Check status & download

Read one attempt and get a fresh download URL when the image is ready.

Inputs

No request body or query parameters.

Field	Type	Details
`Authorization`	`string · header`	Required on every endpoint: Bearer <api_key>.
`generation_id`	`string · UUID · path`	Required. The id returned by creation or history. Must belong to your account.

Request example

cURL

1curl "$API_BASE/v1/generations/ad7cc504-91d3-4b6e-b12f-624b967a8250" \
2  -H "Authorization: Bearer $API_KEY"

Response 200 OK · Generation

application/json · Illustrative example; IDs, dates and URLs will differ.

Response body

1{
2  "id": "ad7cc504-91d3-4b6e-b12f-624b967a8250",
3  "status": "completed",
4  "quality": "low",
5  "mode": "default",
6  "background_color": "#FFFFFF",
7  "created_at": "2026-09-24T10:00:00Z",
8  "completed_at": "2026-09-24T10:00:30Z",
9  "output": {
10    "url": "https://storage.example.com/result.jpg?token=example",
11    "expires_at": "2026-09-24T11:00:30Z",
12    "content_type": "image/jpeg",
13    "width": 1024,
14    "height": 1536
15  },
16  "error": null
17}

Explore response fields & types

Field	Type	Details
`id`	`string · UUID`	Unique attempt ID. Use this to poll, including for website regenerations.
`status`	`string · enum`	queued \| processing \| completed \| failed
`quality`	`string · enum`	low \| medium \| high
`mode`	`string · enum`	default \| wall_shadow \| enhanced_original \| subtle_movement
`background_color`	`string`	Normalized uppercase #RRGGBB.
`created_at`	`string · date-time`	Creation time in ISO 8601 format.
`completed_at`	`string \| null`	Completion time (ISO 8601), or null if not available.
`output`	`object \| null`	Available when the individual result is ready; null while pending, on failure, and in history.
`output.url`	`string`	Temporary download URL. Download without your API key.
`output.expires_at`	`string · date-time`	URL expiry (ISO 8601); one hour after retrieval.
`output.content_type`	`string`	image/jpeg
`output.width`	`integer \| null`	Image width in pixels, when available.
`output.height`	`integer \| null`	Image height in pixels, when available.
`error`	`string \| null`	Failure message when status is failed; otherwise null.

What happens behind the request

Stop polling at completed or failed. Download output.url without an Authorization header; save the image to your own storage for permanent reuse. The link expires after one hour; call this endpoint again for a fresh one. A failed generation still returns HTTP 200 with status: failed and an error message.

Possible errors: 401 · 404 · 422 · 429 · 5xx. Error format & recovery →

GET/v1/generationsBrowse your history

Browse your history

List your account’s API and website attempts, newest first, in every state.

Inputs

No request body. Send pagination in the URL query string.

Field	Type	Details
`Authorization`	`string · header`	Required on every endpoint: Bearer <api_key>.
`limit`	`integer · query`	Optional. 1–50; default 20.
`offset`	`integer · query`	Optional. 0–10,000; default 0.

Request example

cURL

1curl "$API_BASE/v1/generations?limit=20&offset=0" \
2  -H "Authorization: Bearer $API_KEY"

Response 200 OK · GenerationPage

application/json · Illustrative example; IDs, dates and URLs will differ.

Response body

1{
2  "items": [
3    {
4      "id": "ad7cc504-91d3-4b6e-b12f-624b967a8250",
5      "status": "completed",
6      "quality": "low",
7      "mode": "default",
8      "background_color": "#FFFFFF",
9      "created_at": "2026-09-24T10:00:00Z",
10      "completed_at": "2026-09-24T10:00:30Z",
11      "output": null,
12      "error": null
13    }
14  ],
15  "total": 1
16}

Explore response fields & types

Field	Type	Details
`items`	`Generation[]`	Attempts on this page; an empty array when there are no results. Same fields as Generation, with output: null.
`total`	`integer`	Total account attempts across all pages.

Field	Type	Details
`id`	`string · UUID`	Unique attempt ID. Use this to poll, including for website regenerations.
`status`	`string · enum`	queued \| processing \| completed \| failed
`quality`	`string · enum`	low \| medium \| high
`mode`	`string · enum`	default \| wall_shadow \| enhanced_original \| subtle_movement
`background_color`	`string`	Normalized uppercase #RRGGBB.
`created_at`	`string · date-time`	Creation time in ISO 8601 format.
`completed_at`	`string \| null`	Completion time (ISO 8601), or null if not available.
`output`	`object \| null`	Available when the individual result is ready; null while pending, on failure, and in history.
`output.url`	`string`	Temporary download URL. Download without your API key.
`output.expires_at`	`string · date-time`	URL expiry (ISO 8601); one hour after retrieval.
`output.content_type`	`string`	image/jpeg
`output.width`	`integer \| null`	Image width in pixels, when available.
`output.height`	`integer \| null`	Image height in pixels, when available.
`error`	`string \| null`	Failure message when status is failed; otherwise null.

What happens behind the request

Increase offset by the number of items received to fetch the next page. Stop when items is empty or offset reaches total. New attempts can shift pages. All account keys can read this history. History never includes download URLs; fetch an individual generation for its output.

Possible errors: 401 · 422 · 429 · 5xx. Error format & recovery →

GET/v1/creditsCheck your balance

Check your balance

Read the credits currently available to your account, shared with the website.

Inputs

No request body, path parameters or query parameters.

Field	Type	Details
`Authorization`	`string · header`	Required on every endpoint: Bearer <api_key>.

Request example

cURL

1curl "$API_BASE/v1/credits" \
2  -H "Authorization: Bearer $API_KEY"

Response 200 OK · Credits

application/json · Illustrative example; IDs, dates and URLs will differ.

Response body

1{
2  "credits_remaining": 12
3}

Explore response fields & types

Field	Type	Details
`credits_remaining`	`number`	Available balance. A JSON number, not necessarily an integer.

What happens behind the request

This is a snapshot, not a reservation. Other submissions can change the balance before your next request. Manage credits and subscriptions on the website.

Possible errors: 401 · 429 · 5xx. Error format & recovery →

The generation lifecycle

Keep polling while queued or processing. completed → download the image. failed → read error; use a new idempotency key if you choose to submit again.

Errors & limits

100 image submissions and 500 reads per minute by default, shared across your account’s API keys. Each submission uploads one image; idempotent replays also count. On 429, wait the Retry-After seconds; on network errors or 5xx responses, use exponential backoff.

Retry without paying twice

Send a unique Idempotency-Key (1–128 visible ASCII characters, no spaces) per intended image. Persist it and reuse the same file and settings after a timeout. Identical retries return the same attempt and current status without another charge; changing the payload returns 409.

Idempotency keys are scoped to your account across API keys and the website, and retained with the generation record. Use a new key to intentionally generate another image, including after a failed attempt. After a local polling timeout, keep polling the same ID instead of submitting a replacement.

HTTP	Description
`400 / 422`	Invalid file, settings, or request fields.
`401`	Missing, invalid, or revoked API key.
`402`	Insufficient credits. Manage your balance on the website.
`404`	Generation missing or belongs to another account.
`409`	Idempotency key already used with different input.
`413`	Upload exceeds the file-size limit.
`429`	Rate limit exceeded. Wait the Retry-After seconds.
`5xx`	Service error. Retry safely with exponential backoff.

Error response

1{
2  "error": {
3    "code": "insufficient_credits",
4    "message": "Not enough credits to generate this image",
5    "request_id": "…"
6  }
7}

Error responses are JSON: error is an object with three string fields. code identifies the error category, message describes the problem, and request_id identifies the request for support. The X-Request-ID response header also carries this identifier. A 429 response includes Retry-After (seconds).

Include X-Request-ID when contacting support. v1 does not provide batches, webhooks, remote URL inputs, or regeneration endpoints.

Manage your API keys OpenAPI specification