KoalaChat API

The KoalaChat API allows you to integrate our powerful chat capabilities into your applications, including image understanding (vision) and file attachments (PDFs, documents, and code). Each request to KoalaChat uses 1 chat credit by default. Higher-tier models consume more chat credits per request — see the model list below.

Endpoint

POST https://koala.sh/api/gpt/

Models

The default model used is GPT-5.6 Luna. To specify a different model, you can use the model parameter with one of the following values:

• gpt-5.6-luna (default, uses 1 chat credit)
• gpt-5.4-mini (uses 1 chat credit)
• gemini-3.6-flash (uses 1 chat credit)
• gpt-5.6-terra (uses 2 chat credits)
• gpt-5.4 (uses 2 chat credits)
• gpt-5.5 (uses 3 chat credits)
• gpt-5.6-sol (uses 3 chat credits)
• claude-4.5-haiku (uses 1 chat credit)
• claude-sonnet-5 (uses 2 chat credits)
• claude-opus-5 (uses 3 chat credits)
• gemini-3.1-pro (uses 2 chat credits)

Older values (gpt-5-mini, gemini-3-flash,gpt-5.3-chat-latest, claude-4.6-sonnet, claude-opus-4-7, claude-opus-4-8) are still accepted and continue to work.

Example Request

fetch("https://koala.sh/api/gpt/", {
    method: "POST",
    headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        input: "what is the most popular dog breed?",
        realTimeData: true,
    })
});

Example Response

{"output": "The most popular dog breed in 2024 is the French Bulldog, retaining the top spot for the second consecutive year ([source](https://www.akc.org/most-popular-breeds/))."}

Parameters

Note on Conversation History: If you provide inputHistory and outputHistory, they must be of the same length. These arrays help maintain conversation context for multi-turn interactions.

Complete Example with Conversation History

// First message
const response1 = await fetch("https://koala.sh/api/gpt/", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    input: "What are the top 3 dog breeds for families?",
    model: "gpt-5.6-luna",
    realTimeData: true
  })
});

const data1 = await response1.json();
const aiResponse1 = data1.output;
console.log(aiResponse1);

// Second message (with conversation history)
const response2 = await fetch("https://koala.sh/api/gpt/", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    input: "Which of these is best for apartments?",
    inputHistory: ["What are the top 3 dog breeds for families?"],
    model: "gpt-5.6-luna",
    outputHistory: [aiResponse1],
    realTimeData: true
  })
});

const data2 = await response2.json();
console.log(data2.output);

Real-Time Data

Setting realTimeData to true allows the API to access current information from the web. This is useful for questions about current events, recent statistics, or any topic that requires up-to-date information.

If you don't need real-time data, you can omit this parameter to get faster responses.

Attachments: Images (Vision), Documents & Code

KoalaChat can read images and extract the text of documents and code files. Attach files to your request with the attachments parameter and the model will use them alongside your prompt. Attachments require a JSON POST request, apply to the current input only, and you can include up to 10 per message.

In most cases an attachment only needs a url. The file type is detected from the URL's file extension, or from the server's Content-Type header when the URL doesn't have one, so extensionless image and document URLs work too:

If an attachment cannot be downloaded (the URL returns an error, times out, or is not a public https URL), the request is rejected with a 400 response and the error code ATTACHMENT_FETCH_FAILED, so you never pay credits for a reply generated without your file. The error message names the failing attachment.

Images (Vision)

All current KoalaChat models support image input. Supported formats: JPG, PNG, GIF, and WebP, up to 5MB per image. The URL must be publicly accessible, since the image is fetched while your request is processed. Image attachments don't cost extra: the request uses the same number of chat credits as a text-only request for the selected model.

fetch("https://koala.sh/api/gpt/", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    input: "What is shown in this image?",
    model: "gpt-5.6-luna",
    attachments: [
      { url: "https://example.com/photo.jpg" }
    ]
  })
});

PDFs & Office Documents

Supported formats: PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX, and ODT. The URL can be any publicly accessible URL. Text is extracted from the first 50 pages and included with your message. Documents beyond your plan's monthly document processing allowance consume additional chat credits.

Text & Code Files

Supported formats: TXT, CSV, MD, HTML, XML, JSON, TEX, LATEX, BIB, IPYNB, and common code files (PY, JS, TS, JSX, TSX, JAVA, C, CPP, CS, GO, RS, RB, PHP, SWIFT, KT). Any publicly accessible HTTPS URL works, and files up to 500KB are supported.

Uploading Files

If you don't have a publicly accessible URL for a file, upload it first:

POST https://koala.sh/api/upload/

Send the file as multipart/form-data in a field named file. The file name must include its extension. The response contains the url to use in attachments. Maximum file size depends on your plan (up to 20MB on Professional and higher plans, 2MB on free accounts). Uploaded files are stored temporarily (1 day on free accounts, 90 days on paid plans), and images are moderated and optimized after upload.

// 1. Upload the file
const formData = new FormData();
formData.append("file", fileBlob, "app.py");

const uploadResponse = await fetch("https://koala.sh/api/upload/", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY" },
  body: formData
});

const { url } = await uploadResponse.json();

// 2. Attach it to a chat request
const response = await fetch("https://koala.sh/api/gpt/", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    input: "Review this code and suggest improvements.",
    attachments: [{ url }]
  })
});

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
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server-side error

Best Practices

For optimal results when using the KoalaChat API:

• Be specific in your prompts to get more accurate and relevant responses
• Use conversation history for multi-turn interactions to maintain context
• Enable real-time data only when you need up-to-date information
• Consider using GPT-5.6 Sol or Claude Opus 5 for the most demanding queries, and Claude Sonnet 5 for nuanced responses at a lower credit cost

Need Help?

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