KoalaImages API

The KoalaImages API allows you to generate high-quality AI images based on a specific prompt, style, and size. Requests use just 1 chat credit per image, or 5 credits for premium model images (Professional Plan only).

Endpoint

POST https://koala.sh/api/image-generation/

Example Request

fetch("https://koala.sh/api/image-generation/", {
    method: "POST",
    headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        prompt: "cat",
        style: "watercolor",
        size: "1024x1024",
        numImages: 1,
        model: "standard"
    })
});

Example Response

[{
    "url": "https://koala.sh/api/image/v2-cnfjk-1g1wf.jpg?width=1024&height=1024&dream",
    "alt": "A sleek black cat lounges on a sunlit windowsill, gazing out at the world with bright green eyes"
}]

Important Note: The API will return a response before the image has been fully generated. This allows the API to return quickly and for you to use the image URL as if it already exists. If you immediately request the image URL, it will take several seconds before it returns a response because it will wait until the image is ready.

Parameters

Response Format

If successful, the API will return a JSON array of objects with the following properties:

Image Generation Time

Images are usually generated within 8-15 seconds. However, if there is high load or downtime with one of our providers, this can take much longer. Our system will automatically handle downtime that lasts even several hours. In very rare cases, it can take a few hours until the image is ready at the provided URL.

Complete Example

// Function to generate images
async function generateImages(prompt, style = "photo", size = "1024x1024", numImages = 1) {
  try {
    const response = await fetch("https://koala.sh/api/image-generation/", {
      method: "POST",
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        prompt,
        style,
        size,
        numImages,
        model: "standard"
      })
    });
    
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    const images = await response.json();
    return images;
  } catch (error) {
    console.error("Error generating images:", error);
    return null;
  }
}

// Example usage
async function main() {
  const images = await generateImages(
    "A majestic mountain landscape with a lake reflecting the sunrise",
    "watercolor",
    "1536x640",
    2
  );
  
  if (images) {
    console.log(`Generated ${images.length} images:`);
    images.forEach((image, index) => {
      console.log(`Image ${index + 1}:`);
      console.log(`URL: ${image.url}`);
      console.log(`Description: ${image.alt}`);
      console.log('---');
    });
  }
}

main();

Error Handling

The API will return appropriate HTTP status codes for different error conditions:

• 400 Bad Request: Invalid parameters or request format
• 401 Unauthorized: Invalid or missing API key
• 402 Payment Required: Insufficient credits
• 403 Forbidden: Premium model requires Professional Plan
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server-side error

Need Help?

If you need additional assistance with the KoalaImages API, please contact us.