KoalaImages API

The KoalaImages API generates high-quality AI images from a selection of leading models. Credits are charged per generated image; the cost depends on the chosen model and quality setting.

Sample Output

A few images produced through this API. All generated with gpt-image-2 at quality: medium. Click any image to see the exact request that produced it.

style: photostyle: photostyle: watercolorstyle: isometric

Models

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: "gpt-image-2",
        quality: "medium",
        enhancePrompt: "on",
        generateAltText: true
    })
});

Example Response

[{
    "url": "https://koala.sh/api/image/v2-cnfjk-1g1wf.jpg",
    "alt": "A watercolor painting of a tabby cat with bright green eyes"
}]

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: "gpt-image-2",
        quality: "fast", // "medium" or "high" cost more credits
        enhancePrompt: "on",
        generateAltText: true // populates the response's alt field
        // For 'gpt-image-2' you can also include:
        // referenceImages: ["https://example.com/image1.jpg", "https://example.com/image2.jpg"],
        // preserveOriginal: true  // store the raw PNG for maximum quality
      })
    });
    
    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}: ${image.url}`);
      if (image.alt) {
        console.log(`  Alt: ${image.alt}`);
      }
    });
  }
}

main();

Error Handling

The API returns standard HTTP status codes for different error conditions:

Need Help?

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