Topaz Image Enhance
Topaz Labs makes image models that upscale and enhance a photo or a generated image. You send one source image and the output size you want. Topaz returns the image at that size. One route serves all four models. The request is asynchronous. You submit a job, poll it until the status is terminal, then download the image. The route takes a JSON body. Topaz’s own API takes a multipart form, so the field names here are ours where the two differ.Best for
- Low-resolution and compressed photos. Wonder 4 and Wonder 3.5 remove noise, blur and compression artifacts while they upscale.
- Generated images. Bloom 2 adds new detail and texture to AI artwork, illustrations and renders.
- Camera originals. Gigapixel High Fidelity 3 enlarges high-quality photos and keeps their look.
- Large output. Each side can be up to 32,000 pixels.
Models
Each model runs with Topaz’s default settings. Wonder 3.5 enhances at its high strength. Bloom 2 runs at creativity 3 with its automatic prompt and color preservation on. High Fidelity 3 recovers detail at its default strength. Model settings cannot be changed on this route yet.
Endpoints
Request
Send your API key in theX-API-Key header. See Authentication. Set Content-Type: application/json. The examples also send a User-Agent header that names your application.
The model ID:
topaz-wonder-4, topaz-wonder-3.5, topaz-bloom-2 or topaz-gigapixel-high-fidelity-3.The source image. Either a public
https URL, or a data: URI with base64 data of type image/jpeg, image/png or image/tiff. An http URL is rejected.The output width in pixels, 1 to 32,000. Required, together with
output_height. The price follows the output canvas, so the route takes no scale factor and does not derive one side from the other.When the output shape differs from the source shape,
true crops the output to fill the canvas. false letterboxes it.Response
Submit
A 200 status means that Topaz accepted the job. It does not mean that the image is ready.The job ID. Poll
GET /v1/topaz/image/{process_id} with it. There is no handle field: process_id is the value to poll. It works for 7 days.Poll
Processing while the job runs. Completed, Failed or Cancelled when it ends. Poll until you read one of the three terminal values.The URL of the output image. Present only when
status is Completed. The URL is time-limited. A later poll returns a fresh URL.Present when the job did not complete.
error.message explains why. Read it before you resubmit.Example
Submit, poll, download. The submit and the poll use different paths.Tips
- Keep the output shape equal to the source shape. A different shape is letterboxed, or cropped with
crop_to_fill. - Pick the canvas you need, not the largest one. The price grows with the output megapixels.
- Use Wonder 4 when you are unsure. Use Bloom 2 only on generated images, because it invents detail. Use High Fidelity 3 on sources that are already sharp.
- Poll every 3 seconds at first, then back off to 30 seconds. Polls are free and never use a concurrency slot.
Errors and limits
A 200 status on submit means that Topaz accepted the job. It does not mean that the job succeeded. A job that fails later ends withstatus set to Failed or Cancelled, and error.message explains why. Read it before you resubmit.
A failed submit returns an HTTP error status. See Error codes. These request shapes are rejected with 400 before any charge:
Topaz can refuse an output size that its model does not support. Wonder 4 takes an output from 1 to 6 times the source size. The refusal comes back as a 4xx on submit with Topaz’s own message, or as a
Failed job. Neither is charged.
A 5xx status or a timeout on submit does not tell you whether the job was created. Never resubmit blindly. If the submit returned a process_id, poll it. If it returned nothing, check your credits before you try again.
Topaz bills in whole credits, by output megapixels. Each model turns a different number of megapixels into one credit, so the same canvas costs more on Bloom 2 than on High Fidelity 3. Nunchux holds the charge for your canvas at submit and settles it to the credits that Topaz reports when the job ends. A failed job is refunded. See the pricing page for the rates.
Every submit counts toward the simultaneous-jobs cap of your plan for six minutes, however fast the job finishes. A job that ends sooner does not give its slot back early, so a burst of short jobs can return 429 concurrent_limit_exceeded. Wait and retry with backoff. Separately, at most five Topaz jobs per account can be in progress at once. A sixth returns 429 with the code too_many_open_tasks. A job stops counting toward the five when Nunchux settles it, which can be a few seconds after the poll first shows a terminal status, so a submit sent at once can still return 429. See Rate limits, Credits & pricing and the Partner models overview.