KoalaImages API

The KoalaImages API allows you to easily generate high-quality AI images from multiple models.

The Standard model uses Leonardo Phoenix 1.0 and costs just 1 chat credit per image. The Premium model utilizes a higher quality version of Leonardo Phoenix 1.0 for better results and costs 5 credits per image.

We also offer access to OpenAI GPT Image (10-25 credits depending on quality) and Ideogram 3.0 (3 credits). All models except for the Standard model require a Professional Plan subscription to access.

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",
        enhancePrompt: "on"
    })
});

Example Response

[{
    "url": "https://koala.sh/api/image/v2-cnfjk-1g1wf.jpg"
}]

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",
        enhancePrompt: "on"
        // For 'gpt-image-1' model, you can also include:
        // quality: "medium",  // or "high" (costs more credits)
        // referenceImages: ["https://example.com/image1.jpg", "https://example.com/image2.jpg"]
      })
    });
    
    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.