> For the complete documentation index, see [llms.txt](https://developer.topazlabs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.topazlabs.com/getting-started/faqs.md).

# FAQs

Get your questions answered

Common questions about using the Topaz Labs API. If you can't find the answer here, join our [Developer Discord](https://discord.gg/pUqhyZvRHD), ask on the [Community Forum](https://discord.gg/pUqhyZvRHD), or contact <support@topazlabs.com>.

***

### Getting Started

<details>

<summary>How do I get an API key?</summary>

[Log in](https://account.topazlabs.com), navigate to the "API" tab, enter a name for the key, and click **Create**. Copy it immediately: the key is only shown once. If you lose it, create a new one and delete the old one from the same page. If the page won't load or returns an error, try the direct link above rather than the account dashboard.

</details>

<details>

<summary>Do I need a subscription to use the API?</summary>

No. API usage is paid with credits, not an app subscription. A free Topaz account with credits on it can use every API endpoint. However, our API subscription tiers include many benefits including lower credit costs, automatic top-ups, and more. Reference our [website](https://topazlabs.com/api/) for more about our API plans.

</details>

<details>

<summary>Does my Topaz Studio, Topaz Image Web, or Pro subscription include API access?</summary>

Yes. Anyone can create an account and use our API, as long as they have credits to fund their requests. App subscriptions (Studio, Image Web Pro, and the desktop apps) typically include cloud credits, which can be used to make API calls as well. However, other benefits such as Pro's "unlimited rendering" and "8 concurrent jobs" apply to the web app only. If you bought an app plan by mistake while trying to buy API credits, contact support for a refund.

</details>

<details>

<summary>Is there a free tier or sandbox for testing?</summary>

Not currently. The [Model Playground](https://playground.topazlabs.com/) lets you try models interactively, and any credits on your account (including a small one-time pack) can be used for API testing. If you're evaluating for a production integration, mention it when you contact support and we'll assist you.

</details>

<details>

<summary>Is there a CLI, or can I script the desktop apps?</summary>

No. We do not offer CLI access, and the desktop apps don't expose a scripting interface. The API is the supported path for automation, batch processing, and server-side or headless (including Linux) workflows.

</details>

<details>

<summary>Where can I find sample code?</summary>

The [Image Quickstart](/getting-started/image-quickstart.md) and [Video Quickstart](/getting-started/video-quickstart.md) walk through a complete request. Each model page has a copy-and-paste example request.

</details>

***

### Billing & Credits

<details>

<summary>How is API usage priced?</summary>

There's no flat per-image or per-second price. Image jobs are billed by output megapixels; video jobs are billed by output resolution, duration, and frame rate; and the rate depends on the model family. The [Credit Calculator](https://developer.topazlabs.com/credit-calculator) reflects the same billing logic as the API and is the recommended way to estimate cost before you submit. More information about our model rates are on the [Model Pricing](/getting-started/model-pricing.md) page.

</details>

<details>

<summary>Why does the API cost more than the same job in the web app?</summary>

The API and the apps use different pricing. App subscriptions include unlimited cloud rendering for a flat monthly fee; the API bills each job by its output. Running the same model with the same settings in both will not cost the same, and the credit count shown in an app is not the API price.

</details>

<details>

<summary>What's the difference between API credits and cloud credits?</summary>

They're the same underlying credit and both can pay for API jobs. The difference is the plan that delivers them:

|                              | API subscription                   | Cloud Credits (monthly)                      | One-time credit pack   |
| ---------------------------- | ---------------------------------- | -------------------------------------------- | ---------------------- |
| Billed                       | Monthly                            | Monthly                                      | Once                   |
| Auto top-up when you run out | Yes                                | No                                           | No                     |
| Unused credits               | Roll over while the plan is active | Expire at the end of the billing cycle       | Never expire           |
| Best for                     | Production API workloads           | App users who also call the API occasionally | Testing and low volume |

</details>

<details>

<summary>Which plan should I buy for API usage?</summary>

For anything beyond testing, buy an **API subscription** from [our website](#getting-started). It's the only plan with automatic top-ups, which is what prevents your integration from stopping when the balance hits zero. One-time credit packs work for evaluation. Make sure you purchase from the API page; the "Buy credits" button inside the web app sells Cloud Credits, which look similar but don't top up automatically.

</details>

<details>

<summary>How does auto top-up work?</summary>

When an API subscription's balance reaches zero, we automatically add credits equal to 25% of your monthly plan and charge your card at your plan's per-credit rate. On a 3,000-credit plan, that's 750 credits for $49.75. It repeats as often as needed. Auto top-up is only available on API subscriptions, and it stops working if a payment fails. For issues with auto top-up, contact support.

</details>

<details>

<summary>Do unused credits roll over? Is there a maximum balance?</summary>

On an API subscription, unused credits roll over each month and don't expire while the plan is active. Your balance is capped at 5× your monthly credit volume (a 3,000-credit plan can hold up to 15,000). If you cancel, you keep the balance.

</details>

<details>

<summary>Can I change my plan tier?</summary>

Yes, but not in place. Cancel the current API subscription, then purchase the new tier. Credits already on the account stay with you. If the cancellation is still "pending" and blocks the new purchase, contact support for assistance. Upgrades mid-cycle are prorated.

</details>

<details>

<summary>Are failed jobs charged?</summary>

No. Credits are reserved when a job starts and committed only when it completes. If a job fails, times out, or is cancelled before processing, the reservation is rolled back automatically. If you see a failed job in your ledger that wasn't refunded, send support the process ID or request ID. Take a look at our [API Reference](https://developer.topazlabs.com/reference/) page for more info on how our Image API and Video API each handle failed jobs.

</details>

<details>

<summary>Am I charged if I never download the result?</summary>

Yes. Credits are committed when processing completes, whether or not you fetch the output. If your client crashes mid-job, check `GET /status` (image) or `GET /video/history` (video) for the existing job before resubmitting, and use the cancel endpoint to release credits for a job you no longer need. Output is retained for 7 days, so you can still download it.

</details>

<details>

<summary>What happens if I cancel a job in progress?</summary>

Cancelling before processing starts refunds everything. Cancelling mid-processing charges 1.1 × the completed percentage and refunds the rest (cancel at 50% → 55% charged). For video, `GET /video/{requestId}/cancel-estimate` previews the exact split.

</details>

<details>

<summary>Can I check my credit balance from code?</summary>

Yes. `GET https://api.topazlabs.com/account/v1/credits/balance` with your normal `X-API-Key` header returns the balance. No separate token is needed. You can also see it under **Credits** in your account dashboard.

</details>

<details>

<summary>Where can I see request logs?</summary>

The **API Keys** page in your account shows a transaction log with each job's status and credit usage. It doesn't include request payloads or error details. For debugging a specific failure, poll the job's status endpoint for its `message` / `errorCode`, and include the `process_id` or `requestId` when you contact support.

</details>

<details>

<summary>Do you offer discounts or volume pricing?</summary>

Self-serve plans are fixed. Enterprise plans start at 20,000 credits per month ($1,000/month, one-year commitment) with volume pricing, higher limits, and custom terms; contact <enterprise@topazlabs.com>. If you're between the top self-serve tier and Enterprise, ask support about intermediate options.

</details>

<details>

<summary>My API subscription says "on hold" or auto top-up stopped working</summary>

This almost always means a payment failed (declined card, insufficient funds). Update the payment method in your account, and the subscription and auto top-up resume. If you're out of credits and blocked in the meantime, contact support.

</details>

<details>

<summary>Can I get an alert when credits run low?</summary>

Not yet. Auto top-up on an API subscription prevents interruptions, and you can poll the balance endpoint from your own monitoring.

</details>

***

### Access & Authentication

<details>

<summary>Can I share an API key across my team?</summary>

API keys belong to the account that created them, and jobs draw from that account's credits. You can create multiple named keys on one account and give each team member their own, so you can rotate or revoke them individually. Separate accounts have separate credit balances.

</details>

<details>

<summary>Do you support models hosted on Replicate, fal, or other platforms?</summary>

Topaz models published on third-party platforms are run by those platforms. For issues with their integrations (parameters, pricing, failures), contact that platform's support. Topaz support covers the Topaz API only.

</details>

<details>

<summary>Do you have endpoints or proxies in China?</summary>

No. All requests go to `api.topazlabs.com` directly. If you're seeing connectivity problems from a specific region, send support the endpoint, timestamps, and any errors.

</details>

***

### Jobs and Limits

***

#### Jobs

<details>

<summary>My job has been "Processing" far longer than the ETA. Is something wrong?</summary>

ETAs are estimates and don't include queue time. During high load, jobs can sit at 0% or in post-processing well past the estimate before completing normally. Don't resubmit the same job; that creates a second charge. If a job exceeds the model's processing time limit it fails and is refunded automatically. If a job appears stuck for more than a couple of hours, send support the `process_id` or `requestId`.

</details>

<details>

<summary>Should I poll or use webhooks?</summary>

Either. Polling the status endpoint every few seconds is fine. For production, pass `webhook_url` (image) or `notifications.webhookUrl` (video) and we'll `POST` to you on completion or failure, with retries. For failure responses, see [Error Handling](/getting-started/errors.md).

</details>

<details>

<summary>Is there a status page?</summary>

Yes, our status page is available at [https://status.topazlabs.com](https://status.topazlabs.com/).

</details>

<details>

<summary>Why does my API output look different from the desktop app?</summary>

The models are the same, but the apps apply extra steps the API doesn't: automatic parameter estimation, pre-downsampling, and multi-model pipelines ("Autopilot" in the apps may run denoise, upscale, and sharpen; the API runs the one model you request). To get closer to app results, chain the equivalent models in sequence and set parameters explicitly. Model names also differ between the apps and the API; use the names on the model pages.

</details>

<details>

<summary>What input and output formats are supported?</summary>

Image: JPEG, PNG, and TIFF in; JPEG, PNG, or TIFF out (PNG only for matting and transparent upscale). 16-bit TIFF is processed at 16-bit and preserved on output; embedded ICC profiles are preserved. ProRes, EXR, and other professional output formats are set through `output.videoEncoder` / `output.container` on video requests; some generative video models accept MP4/H.264 input only.

</details>

<details>

<summary>My requests return HTTP 403 with a Cloudflare error (1010, "browser_signature_banned")</summary>

The request was blocked by our web application firewall before reaching the API, usually because the client's fingerprint matches patterns we block. Fix it in this order:

1. Set a descriptive `User-Agent` header that identifies your application (for example `MyApp/1.0 (contact@example.com)`). Default library agents like Python's `urllib` or `python-requests` are frequently blocked.
2. Check the path. The Image API base is `https://api.topazlabs.com/image/v1/` and the Video API is `https://api.topazlabs.com/video/`; a request to a non-existent path (e.g. `/image/v1/process`) can also trigger a block.
3. If it persists, send support the Cloudflare **Ray ID** from the response, your egress IP, and the User-Agent you're sending. We can add an exception for identified traffic.

</details>

<details>

<summary>Is a retried request safe, or will it charge me twice?</summary>

Submissions are not idempotent. If a `POST` succeeded on our side but the response never reached you, retrying it creates a second job and a second charge. Before resubmitting after a client-side timeout, check `GET /status` (image) or `GET /video/history` (video) for a job created in the last few minutes. Status and download calls are safe to retry freely.

</details>

#### Limits

<details>

<summary>What are the file size and resolution limits?</summary>

Image: most models accept up to 256 MP input and output, and `output_width` / `output_height` can each be up to 32,000 px. Uploads over the file-size limit return `413`. Video: source files under 100 GB, uploaded as a single URL at or under 500 MB or as 500 MB multi-part segments above that. Maximum video output resolution and bitrate depend on the encoder you choose (for example H.264 caps at 4096×4096, H.265 at 8192×8192). Full parameter and encoder limits are in [Request Parameters](/getting-started/request-parameters.md).

</details>

<details>

<summary>How long can a job run before it times out?</summary>

Each model family has a processing time limit: roughly 90 minutes for GAN image models, 20 minutes for generative image models, 4 hours for GAN video models, and 17 hours for generative video models (Starlight, Astra, Nyx High Fidelity). A job that exceeds its limit fails with `TIMEOUT_PROCESSING` and is refunded. For very long videos, split the source into shorter segments.

</details>

<details>

<summary>How long are my files and download links available?</summary>

Source and output files are kept for 7 days after processing, then deleted. Image download URLs from `GET /download/{process_id}` expire 1 hour after they're issued; call the endpoint again for a fresh one. Video download URLs last 7 days by default (`expiresIn` in the status response). You can delete video media sooner with `DELETE /video/{requestId}/media`.

</details>

<details>

<summary>Is there a rate limit or concurrency limit?</summary>

There is no fixed requests-per-second limit on self-serve plans. You can submit multiple jobs in parallel across image and video, and they run concurrently; throughput depends on current system load and your credit balance. Enterprise plans include guaranteed capacity. If you do hit a limit you'll receive `429 Too Many Requests`; back off and retry.

</details>

### Data, Security, and Compliance

<details>

<summary>How long do you keep my files?</summary>

Uploaded inputs and processed outputs are deleted 7 days after processing. Delete sooner with `DELETE /video/{requestId}/media` (video) or by letting the retention window expire (image). Download links are private, signed URLs; they aren't publicly listed.

</details>

<details>

<summary>Is my data used to train models?</summary>

No. API inputs and outputs are used only to provide the service. This is covered in our MSA/DPA, available on request from <enterprise@topazlabs.com>.

</details>

<details>

<summary>Where is my data processed and stored?</summary>

In the United States, for all models and both APIs. We don't currently offer EU or other region-specific processing, including on Enterprise plans.

</details>

<details>

<summary>Can I offer Topaz processing to my own customers inside my product?</summary>

Yes. Integrating the API into your platform and billing your users through your own system is a standard use case; your users don't need Topaz accounts or keys. Attribute the models (for example "Powered by Topaz Labs"), and don't imply partnership, endorsement, or co-ownership. For a DPA, no-retention mode, sub-processor list, or custom terms, contact <enterprise@topazlabs.com>.

</details>

<details>

<summary>Are outputs C2PA-compliant?</summary>

Yes. All API model outputs carry C2PA content credentials.

</details>

***

### Still Have a Question?

Email <support@topazlabs.com> with your `process_id` or `requestId`, the endpoint and parameters you sent, the full error response, and the timestamp. For pricing above the self-serve tiers, contact <enterprise@topazlabs.com>.

### Next Steps

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-brackets-curly">:brackets-curly:</i></td><td><h4>Request Parameters</h4></td><td>Learn how we structure API requests.</td><td><a href="/getting-started/request-parameters.md">Request Parameters</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.topazlabs.com/getting-started/faqs.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.