API Documentation

Looking for the complete API reference with all endpoints and schemas? Check out our API Reference (OpenAPI/Swagger)

1. Introduction

Welcome to the Footprint AI API Documentation. Our API provides a powerful and flexible way to integrate AI capabilities into your applications, including:

• OSSGPT - State-of-the-art language models for text generation and understanding

• Whisper - High-quality speech-to-text transcription models

• Stable Diffusion - Powerful text-to-image generation models

Our API is designed to be fully compatible with the OpenAI API specification, allowing for easy migration and integration with existing tools and libraries.

2. Authentication

To access the Kafeido API, you need an API key. You can generate and manage your API keys from the API Keys page.

Include your API key in the `Authorization` header of your requests, using the `Bearer` token scheme.

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx

Failure to provide a valid API key will result in a `401 Unauthorized` response.

3. Quick Start

Follow these steps to make your first API request:

1. Obtain an API key from your API Keys page.

2. Use your API key to make a request to the chat completions endpoint:

curl https://api.footprint.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "model": "gpt-oss-20b",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  }'

Replace `sk-xxxxxxxxxxxxxxxxxxxxxxxx` with your actual API key.

4. Endpoint Reference

Detailed documentation for each available endpoint will be provided here.

{
  "model": "gpt-oss-20b",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "temperature": 0.7
}

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-oss-20b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 10,
    "total_tokens": 30
  }
}

curl https://api.footprint.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F file="@/path/to/audio.mp3" \
  -F model="whisper-large-v3"

{
  "text": "This is a test transcription."
}

{
  "object": "list",
  "data": [
    {
      "id": "gpt-oss-20b",
      "object": "model",
      "created": 1677649479,
      "licence": "Apache 2.0",
      "input_format": "MODEL_FORMAT_TEXT",
      "output_format": "MODEL_FORMAT_TEXT"
    },
    {
      "id": "whisper-large-v3",
      "object": "model",
      "created": 1677649479,
      "licence": "Apache 2.0",
      "input_format": "MODEL_FORMAT_AUDIO",
      "output_format": "MODEL_FORMAT_TEXT"
    },
    {
      "id": "stable-diffusion-xl",
      "object": "model",
      "created": 1677649479,
      "licence": "Apache 2.0",
      "input_format": "MODEL_FORMAT_TEXT",
      "output_format": "MODEL_FORMAT_IMAGE"
    }
  ]
}

Model Formats:

• MODEL_FORMAT_TEXT - Text input or output

• MODEL_FORMAT_AUDIO - Audio input (mp3, wav, etc.)

• MODEL_FORMAT_IMAGE - Image output

Available Models by Type

• Text Generation: gpt-oss-20b (TEXT → TEXT)

• Audio Transcription: whisper-large-v3, whisper-medium, whisper-small (AUDIO → TEXT)

• Image Generation: stable-diffusion-v1-5, stable-diffusion-xl (TEXT → IMAGE)

5. Rate Limits & Quotas

To ensure fair usage and system stability, our API implements rate limiting based on your subscription plan.

Rate limits are enforced per API key. When you exceed your quota, you'll receive a 429 Too Many Requests response. Monitor your usage on the Dashboard page.

{
  "error": {
    "message": "Rate limit exceeded. You have used 10,000 of your 10,000 tokens for this month.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

6. Error Codes Reference

Our API uses conventional HTTP response codes to indicate the success or failure of requests.

Error Response Format

All errors follow a consistent JSON format:

{
  "error": {
    "message": "A human-readable error message",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

7. Best Practices

Follow these best practices to get the most out of the Kafeido API:

8. SDKs and Libraries

Since our API is OpenAI-compatible, you can use the official OpenAI SDKs with a custom base URL:

pip install openai

# Usage
import openai

client = openai.OpenAI(
    base_url="https://api.footprint.ai/v1",
    api_key="sk-xxxxxxxxxxxxxxxxxxxxxxxx",
)

npm install openai

// Usage
import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'https://api.footprint.ai/v1',
  apiKey: 'sk-xxxxxxxxxxxxxxxxxxxxxxxx',
});

We also provide our own SDK for advanced features. Check out the Kafeido SDK for more details.

For more SDK options and language support, visit the OpenAI Libraries documentation.