Low-resolution images are one of the most common problems in production media pipelines, whether you are scaling product photos for e-commerce or preparing social assets for high-DPI displays. Wireflow gives you a REST API that connects directly to ClarityAI's upscaler, so you can send a single POST request and receive a sharp, detail-rich result without managing GPU infrastructure yourself. This guide walks through every step, from authentication to polling for results, with working curl and fetch examples you can paste into your own codebase.
What Is ClarityAI and Why Use It for Upscaling?
ClarityAI is an open-source image upscaler originally built by philz1337x as an alternative to Magnific. It uses a Stable Diffusion-based pipeline to reconstruct textures and recover lost detail, supporting scale factors from 1x to 16x (capped at 64 megapixels). Two modes are available: Creative, which adds interpretive detail through a creativity slider, and Crystal, which focuses on faithful reconstruction and excels at portraits and faces. For a hands-on look at this in action, check out the AI image upscaler feature page.
Rather than self-hosting the model or juggling multiple third-party endpoints, you can call ClarityAI through Wireflow's unified API. The platform handles model routing, queuing, and output storage, which means your integration code stays simple even when you chain upscaling with other AI steps like background removal or format conversion.
Prerequisites
Before you start, make sure you have the following ready:
- A Wireflow account. Sign up at wireflow.ai if you have not already.
- An API key. Navigate to Settings > API Keys in the dashboard, generate a new key, and copy it immediately. Keys begin with
sk-and are shown only once. - A source image URL. ClarityAI accepts a publicly accessible image URL as input. If your image is local, upload it to any public host first.
- curl, Node.js, or Python installed on your machine for the code examples below.
You can review the full authentication docs for details on scopes and key rotation.
Step 1: Create a Workflow with a ClarityAI Upscaler Node
Wireflow organizes AI operations as workflows, which are directed graphs of nodes. To upscale an image, you need two nodes: a text input node (for the image URL) and a ClarityAI Crystal Upscaler node. You can build this visually in the canvas editor or create it programmatically.
Here is the curl command to create the workflow via API:
curl -X POST https://www.wireflow.ai/api/v1/workflows \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"name": "ClarityAI Image Upscaler",
"nodes": [
{
"id": "input-1",
"type": "basedNode",
"position": { "x": 0, "y": 0 },
"data": {
"label": "Image URL",
"nodeType": "input:text",
"category": "input",
"params": { "prompt": "" },
"inputs": [],
"outputs": [{ "id": "prompt", "type": "TEXT", "label": "Text" }]
}
},
{
"id": "upscale-1",
"type": "basedNode",
"position": { "x": 500, "y": 0 },
"data": {
"label": "ClarityAI Upscaler",
"nodeType": "process:clarityai_crystal_upscaler",
"category": "process",
"params": { "scale_factor": 2 },
"inputs": [{ "id": "image_url", "type": "IMAGE", "label": "Image" }],
"outputs": [{ "id": "images", "type": "IMAGE", "label": "Upscaled Image" }]
}
}
],
"edges": [
{
"id": "edge-1",
"source": "input-1",
"target": "upscale-1",
"sourceHandle": "out-prompt",
"targetHandle": "in-image_url"
}
]
}'
The response returns a workflow ID. Save it; you will use it for every execution call.
Step 2: Execute the Workflow
With the workflow created, trigger an execution by passing the image URL into the input node. Replace YOUR_WORKFLOW_ID with the ID from Step 1 and provide the image you want to upscale:
curl -X POST https://www.wireflow.ai/api/v1/workflows/YOUR_WORKFLOW_ID/execute \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: upscale-job-001" \
-d '{
"nodes": [
{
"id": "input-1",
"data": {
"params": {
"prompt": "https://example.com/my-low-res-photo.jpg"
}
}
}
],
"edges": []
}'
The API responds with a 201 status and an executionId. The Idempotency-Key header prevents duplicate runs if your client retries the same request within 24 hours. You can learn more about execution handling in the executions documentation.
Step 3: Poll for the Result
Wireflow executions are asynchronous. Poll the status endpoint using exponential backoff until the state changes from RUNNING to COMPLETED or FAILED. A good starting interval is 1 second, multiplied by 1.5 on each attempt, capped at 10 seconds between polls. This approach works well when building AI pipelines that include multiple model calls.
curl https://www.wireflow.ai/api/v1/workflows/executions/EXECUTION_ID/poll \
-H "Authorization: Bearer sk-your-api-key"
A completed response includes each node's output. The upscaler node returns the enhanced image URL in outputs.images. Download or redirect this URL to your storage layer.
Step 4: Integrate with JavaScript (fetch)
For production use, here is a complete fetch implementation that creates and polls an execution. This pattern fits cleanly into any Node.js backend or serverless function, similar to how you would build AI workflows with an API:
const API_BASE = "https://www.wireflow.ai/api/v1";
const API_KEY = "sk-your-api-key";
const WORKFLOW_ID = "YOUR_WORKFLOW_ID";
async function upscaleImage(imageUrl) {
// Start execution
const execRes = await fetch(`${API_BASE}/workflows/${WORKFLOW_ID}/execute`, {
method: "POST",
headers: {
"Authorization": `Bearer ${API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
nodes: [{ id: "input-1", data: { params: { prompt: imageUrl } } }],
edges: []
})
});
const { executionId } = await execRes.json();
// Poll with exponential backoff
let delay = 1000;
while (true) {
await new Promise(r => setTimeout(r, delay));
const pollRes = await fetch(
`${API_BASE}/workflows/executions/${executionId}/poll`,
{ headers: { "Authorization": `Bearer ${API_KEY}` } }
);
const result = await pollRes.json();
if (result.status === "COMPLETED") return result;
if (result.status === "FAILED") throw new Error(result.error);
delay = Math.min(delay * 1.5, 10000);
}
}
This function returns the full execution payload, including the upscaled image URL in the node outputs.
Adjusting Scale Factor and Mode
The ClarityAI node supports several parameters you can configure through the params object when creating or updating the workflow. The most important ones for image enhancement are:
| Parameter | Type | Default | Description |
|---|---|---|---|
scale_factor |
integer | 2 | Upscale multiplier (1 to 16, capped at 64MP output) |
creativity |
float | 0.0 | How much interpretive detail to add (0.0 = faithful, 1.0 = creative) |
output_format |
string | "png" | Output format: png, jpg, or webp |
For product photography where accuracy matters, keep creativity at 0. For artistic assets where you want the model to fill in texture, raise it to 0.3 or 0.5. You can update these parameters on an existing workflow using a PUT request to /workflows/{id}, as described in the workflow management docs.
Handling Errors and Rate Limits
Wireflow returns structured error responses to help you handle failures gracefully. The most common scenarios when running batch image generation or upscaling jobs:
- 402 Insufficient Credits: The response includes
requiredCredits,availableCredits, and abreakdownarray showing per-node costs. Top up your balance before retrying. - 429 Rate Limited: Check the
Retry-Afterheader and wait before sending the next request. Free plans allow 10 requests per minute; Pro plans allow 60. - 500 Server Error: Log the
X-Request-Idheader from the response and contact support with it for fast resolution.
Every response includes X-RateLimit-Remaining so you can throttle proactively. For high-volume pipelines, the rate limits documentation covers all plan tiers and headers in detail.
Triggering Upscaling via Webhook (No API Key Required)
If you want external services like Zapier, CI pipelines, or web forms to trigger upscaling without exposing your API key, use a webhook trigger. Enable webhooks on your workflow in the dashboard, then send a POST to the webhook endpoint:
curl -X POST https://www.wireflow.ai/api/v1/workflow/YOUR_WEBHOOK_ID/trigger \
-H "Content-Type: application/json" \
-d '{"nodes": [{"id": "input-1", "data": {"params": {"prompt": "https://example.com/photo.jpg"}}}]}'
No Authorization header is needed. The endpoint returns a 202 with an executionId you can poll using your API key separately. CORS headers are set to *, so browser-side triggers work out of the box. This setup is useful for content pipelines where contributors upload product photos and the upscaling runs automatically. If you are evaluating other automation tools for AI pipelines, webhooks let you integrate upscaling into any existing orchestration layer without code changes.
Try it yourself: Build this workflow in Wireflow — the nodes are pre-configured with the exact ClarityAI upscaler setup discussed above. Check the
API documentationfor the full endpoint reference.
Frequently Asked Questions
What image formats does ClarityAI accept through the Wireflow API?
ClarityAI accepts JPEG, PNG, and WebP as input. The source must be a publicly accessible URL. Output format is configurable via the output_format parameter in the node settings (png, jpg, or webp).
What is the maximum resolution ClarityAI can produce?
The output is capped at 64 megapixels. With a 2x scale factor on a 4000x3000 input, you get 8000x6000 (48MP). A 16x factor is available for very small inputs but the 64MP cap still applies.
How long does an upscale request take?
Most 2x upscale jobs complete in 10 to 20 seconds depending on input size and current queue depth. Use exponential backoff polling starting at 1 second to avoid unnecessary requests.
Can I chain ClarityAI with other models in a single workflow?
Yes. Wireflow workflows support model chaining, so you can connect a background removal node, an image generation node, or a format conversion node before or after the upscaler.
What does the 402 Insufficient Credits error mean?
It means your account balance cannot cover the execution cost. The response body includes a breakdown array showing per-node credit requirements so you know exactly how much to add.
Is there an official SDK for the Wireflow API?
No official SDK exists. The API is plain REST and JSON, so curl, fetch, axios, Python requests, or any HTTP client works. The API overview provides copy-paste examples for each endpoint.
Can I trigger upscaling from a CI pipeline without an API key?
Yes. Enable webhooks on your workflow and use the /workflow/{webhookId}/trigger endpoint, which requires no authentication. Poll the result separately with your API key.
What is the difference between Creative and Crystal mode?
Crystal mode performs faithful upscaling optimized for faces and portraits. Creative mode adds interpretive detail through a creativity slider, which is better for artistic assets where strict accuracy is less important.
