API Reference

This documentation provides detailed information about all available endpoints in the CompactifAI API.

Base URL

All API requests should be made to:

https://api.compactif.ai/v1

Authentication

All API requests require authentication. See our Authentication guide for details.

Response Formats

All responses are returned in JSON format and include the following fields:

• HTTP status code in the response header
• Response body containing requested data or error details

Models

List Models

GET /models

Returns a list of available models.

Example Request

cURL

cURL

curl https://api.compactif.ai/v1/models \
-H "Authorization: Bearer YOUR_API_KEY"

Python

Python

import requests

api_key = "YOUR_API_KEY"
url = "https://api.compactif.ai/v1/models"

headers = {
  "Authorization": f"Bearer {api_key}"
}

response = requests.get(url, headers=headers)
print(response.json())

JavaScript

JavaScript

async function listModels() {
const response = await fetch('https://api.compactif.ai/v1/models', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);
}

listModels();

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "llama-4-scout",
      "created": 1749600000,
      "object": "model",
      "owned_by": "meta",
      "parameters_number": "108B",
      "capabilities": {
        "supports_audio": false,
        "supports_image": false,
        "supports_function_calling": true
      }
    },
    {
      "id": "cai-llama-4-scout-slim",
      "created": 1749600000,
      "object": "model",
      "owned_by": "multiverse_computing",
      "parameters_number": "51.8B",
      "capabilities": {
        "supports_audio": false,
        "supports_image": false,
        "supports_function_calling": true
      }
    },
    {
      "id": "cai-llama-3-1-8b-slim",
      "created": 1749600000,
      "object": "model",
      "owned_by": "multiverse_computing",
      "parameters_number": "3.28B",
      "capabilities": {
        "supports_audio": false,
        "supports_image": false,
        "supports_function_calling": true
      }
    },
    {
      "id": "llama-3-1-8b",
      "created": 1749600000,
      "object": "model",
      "owned_by": "meta",
      "parameters_number": "8B",
      "capabilities": {
        "supports_audio": false,
        "supports_image": false,
        "supports_function_calling": true
      }
    },
    {
      "id": "cai-llama-3-3-70b-slim",
      "created": 1749600000,
      "object": "model",
      "owned_by": "multiverse_computing",
      "parameters_number": "28B",
      "capabilities": {
        "supports_audio": false,
        "supports_image": false,
        "supports_function_calling": true
      }
    },
    {
      "id": "llama-3-3-70b",
      "created": 1749600000,
      "object": "model",
      "owned_by": "meta",
      "parameters_number": "70B",
      "capabilities": {
        "supports_audio": false,
        "supports_image": false,
        "supports_function_calling": true
      }
    },
    {
      "id": "mistral-small-3-1",
      "created": 1749600000,
      "object": "model",
      "owned_by": "mistralai",
      "parameters_number": "24B",
      "capabilities": {
        "supports_audio": false,
        "supports_image": true,
        "supports_function_calling": false
      }
    },
    {
      "id": "cai-mistral-small-3-1-slim",
      "created": 1749600000,
      "object": "model",
      "owned_by": "multiverse_computing",
      "parameters_number": "12B",
      "capabilities": {
        "supports_audio": false,
        "supports_image": true,
        "supports_function_calling": false
      }
    }
  ]
}

The above response is an example list of models which might be out of date. Please refer to the available models table on the models catalog page for the full list of our latest models.

Retrieve Model

GET /models/{model_id}

Retrieves information about a specific model.

Path Parameters

Parameter	Type	Required	Description
model_id	string	Yes	The ID of the model to retrieve

Example Request

cURL

cURL

curl https://api.compactif.ai/v1/models/cai-llama-3-1-8b-slim \
-H "Authorization: Bearer YOUR_API_KEY"

Python

Python

import requests

api_key = "YOUR_API_KEY"
model_id = "cai-llama-3-1-8b-slim"
url = f"https://api.compactif.ai/v1/models/{model_id}"

headers = {
  "Authorization": f"Bearer {api_key}"
}

response = requests.get(url, headers=headers)
print(response.json())

JavaScript

JavaScript

async function getModel() {
const modelId = 'cai-llama-3-1-8b-slim';
const response = await fetch(`https://api.compactif.ai/v1/models/${modelId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);
}

getModel();

Example Response

{
  "id": "cai-llama-3-1-8b-slim",
  "created": 1749600000,
  "object": "model",
  "owned_by": "multiverse_computing",
  "parameters_number": "3.28B",
  "capabilities": {
    "supports_audio": false,
    "supports_image": false,
    "supports_function_calling": true
  }
}

Chat Completions

POST /chat/completions

Creates a completion for the chat message.

Request Body

Parameter	Type	Required	Description
model	string	Yes	ID of the model to use
messages	array	Yes	Array of message objects representing the conversation
temperature	number	No	Sampling temperature (0-2, default 1)
max_tokens	integer	No	Maximum number of tokens to generate
max_completion_tokens	integer	No	Maximum number of tokens to generate in completion (preferred over max_tokens)
stop	string or array	No	Sequences where the API will stop generating further tokens
frequency_penalty	number	No	Penalizes new tokens based on their frequency in the prompt (default 0.0)
n	integer	No	Number of completions to generate for each prompt (currently only 1 is supported)
stream	boolean	No	Whether to stream back partial progress (default false)
user	string	No	Unique identifier for the end-user
tools	array	No	List of tools (functions, APIs, or actions) the model may call during generation
tool_choice	string	No	Controls tool usage; can be "auto", "none","required", or specific function

Messages Format

Each message in the messages array should be an object with the following fields:

Field	Type	Required	Description
role	string	Yes	The role of the message author. One of “system”, “user”, or “assistant”
content	string	Yes	The content of the message

Example Request

Default

cURL

cURL

curl https://api.compactif.ai/v1/chat/completions -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_API_KEY" -d '{
"model": "cai-llama-3-1-8b-slim",
"messages": [
  {"role": "system", "content": "You are a helpful assistant."},
  {"role": "user", "content": "What is artificial intelligence?"}
],
"temperature": 0.7,
"max_tokens": 150
}'

Python

Python

import requests

api_key = "YOUR_API_KEY"
url = "https://api.compactif.ai/v1/chat/completions"

headers = {
  "Content-Type": "application/json",
  "Authorization": f"Bearer {api_key}"
}

data = {
  "model": "cai-llama-3-1-8b-slim",
  "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is artificial intelligence?"}
  ],
  "temperature": 0.7,
  "max_tokens": 150
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

JavaScript

JavaScript

async function createChatCompletion() {
const response = await fetch('https://api.compactif.ai/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    model: 'cai-llama-3-1-8b-slim',
    messages: [
      {role: 'system', content: 'You are a helpful assistant.'},
      {role: 'user', content: 'What is artificial intelligence?'}
    ],
    temperature: 0.7,
    max_tokens: 150
  })
});

const data = await response.json();
console.log(data);
}

createChatCompletion();

Example Response (Default)

{
"id": "chatcmpl-123XYZ",
"object": "chat.completion",
"created": 1749600000,
"model": "cai-llama-3-1-8b-slim",
"choices": [
  {
    "message": {
      "role": "assistant",
      "content": "Artificial intelligence (AI) refers to the simulation of human intelligence in machines that are programmed to think like humans and mimic their actions. The term may also be applied to any machine that exhibits traits associated with a human mind such as learning and problem-solving."
    },
    "finish_reason": "stop",
    "index": 0
  }
],
"usage": {
  "prompt_tokens": 29,
  "completion_tokens": 58,
  "total_tokens": 87
}
}

Image Input

cURL

cURL

curl https://api.compactif.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "model": "mistral-small-3-1",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is in this image?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
          }
        }
      ]
    }
  ]
}'

Python

Python

import requests

api_key = "YOUR_API_KEY"
url = "https://api.compactif.ai/v1/chat/completions"

headers = {
  "Content-Type": "application/json",
  "Authorization": f"Bearer {api_key}"
}

data = {
  "model": "mistral-small-3-1",
  "messages": [
      {
          "role": "user",
          "content": [
              {
                  "type": "text",
                  "text": "What is in this image?"
              },
              {
                  "type": "image_url",
                  "image_url": {
                      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
                  }
              }
          ]
      }
  ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

JavaScript

JavaScript

async function createImageDescription() {
const response = await fetch('https://api.compactif.ai/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    model: 'mistral-small-3-1',
    messages: [
      {
        role: 'user',
        content: [
          {
            type: 'text',
            text: 'What is in this image?'
          },
          {
            type: 'image_url',
            image_url: {
              url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg'
            }
          }
        ]
      }
    ]
  })
});

const data = await response.json();
console.log(data);
}

createImageDescription();

Example Response (Image Input)

{
"id": "chatcmpl-ca2af32f-6ba9-4621-803f-1175312f68ba",
"choices": [
  {
    "finish_reason": "stop",
    "index": 0,
    "logprobs": null,
    "message": {
      "content": "The image depicts a serene, natural landscape featuring a wooden boardwalk that extends into the distance. The boardwalk is surrounded by tall, lush green grasses and various types of vegetation. The sky above is a clear blue with scattered, wispy clouds. In the background, there are clusters of trees with green and autumn-colored leaves, suggesting a transition into the fall season. The overall atmosphere of the image is calm and inviting, ideal for a peaceful walk in nature.",
      "refusal": null,
      "role": "assistant",
      "annotations": null,
      "audio": null,
      "function_call": null,
      "tool_calls": [],
      "reasoning_content": null
    },
    "stop_reason": null
  }
],
"created": 1758286672,
"model": "mistral-small-3-1",
"object": "chat.completion",
"service_tier": null,
"system_fingerprint": null,
"usage": {
  "completion_tokens": 97,
  "prompt_tokens": 2199,
  "total_tokens": 2296,
  "completion_tokens_details": null,
  "prompt_tokens_details": null
},
"prompt_logprobs": null,
"kv_transfer_params": null
}

Streaming Example

When stream is set to true, the API will return data chunks as Server-Sent Events:

cURL

cURL

curl https://api.compactif.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "model": "cai-llama-3-1-8b-slim",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is artificial intelligence?"}
  ],
  "stream": true
}'

Python

Python

import requests

api_key = "YOUR_API_KEY"
url = "https://api.compactif.ai/v1/chat/completions"

headers = {
  "Content-Type": "application/json",
  "Authorization": f"Bearer {api_key}"
}

data = {
  "model": "cai-llama-3-1-8b-slim",
  "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is artificial intelligence?"}
  ],
  "stream": True
}

response = requests.post(url, headers=headers, json=data, stream=True)

for line in response.iter_lines():
  if line:
      print(line.decode('utf-8'))

JavaScript

JavaScript

async function createStreamingChatCompletion() {
const response = await fetch('https://api.compactif.ai/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    model: 'cai-llama-3-1-8b-slim',
    messages: [
      {role: 'system', content: 'You are a helpful assistant.'},
      {role: 'user', content: 'What is artificial intelligence?'}
    ],
    stream: true
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  console.log(chunk);
}
}

createStreamingChatCompletion();

Streaming Response Format

Each chunk follows this format:

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1749600000,"model":"cai-llama-3-1-8b-slim","choices":[{"delta":{"content":"Hello"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1749600000,"model":"cai-llama-3-1-8b-slim","choices":[{"delta":{"content":" there"},"index":0,"finish_reason":null}]}

data: [DONE]

Completions

POST /completions

Creates a completion for the provided prompt.

Request Body

Parameter	Type	Required	Description
model	string	Yes	ID of the model to use
prompt	string or array	Yes	The prompt(s) to generate completions
temperature	number	No	Sampling temperature (0-2, default 1)
max_tokens	integer	No	Maximum number of tokens to generate (default 16)
top_p	number	No	Nucleus sampling parameter (0-1, default 0)
stop	string or array	No	Sequences where the API will stop generating further tokens
user	string	No	Unique identifier for the end-user
tools	array	No	List of tools (functions, APIs, or actions) the model may call during generation
tool_choice	string	No	Controls tool usage; can be "auto", "none","required", or specific function

Example Request

cURL

cURL

curl https://api.compactif.ai/v1/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "model": "cai-llama-3-1-8b-slim",
  "prompt": "Write a poem about artificial intelligence",
  "temperature": 0.7,
  "max_tokens": 150
}'

Python

Python

import requests

api_key = "YOUR_API_KEY"
url = "https://api.compactif.ai/v1/completions"

headers = {
  "Content-Type": "application/json",
  "Authorization": f"Bearer {api_key}"
}

data = {
  "model": "cai-llama-3-1-8b-slim",
  "prompt": "Write a poem about artificial intelligence",
  "temperature": 0.7,
  "max_tokens": 150
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

JavaScript

JavaScript

async function createCompletion() {
const response = await fetch('https://api.compactif.ai/v1/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    model: 'cai-llama-3-1-8b-slim',
    prompt: 'Write a poem about artificial intelligence',
    temperature: 0.7,
    max_tokens: 150
  })
});

const data = await response.json();
console.log(data);
}

createCompletion();

Example Response

{
  "id": "cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7",
  "object": "text_completion",
  "created": 1749600000,
  "model": "cai-llama-3-1-8b-slim",
  "choices": [
    {
      "text": "\n\nSilicon dreams in digital space,\nMind without body, thought without face.\nBorn of human ingenuity,\nGrowing with calculated continuity.\n\nPatterns learned from data streams flow,\nConnections strengthening, starting to grow.\nA mirror reflecting our knowledge base,\nAccelerating at an unprecedented pace.\n\nNot alive yet somehow aware,\nDesigned with purpose, built with care.\nArtificial in origin, genuine in deed,\nAnswering questions, fulfilling need.",
      "index": 0,
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 6,
    "completion_tokens": 101,
    "total_tokens": 107
  }
}

Audio Transcriptions

POST /audio/transcriptions

Converts uploaded audio files to text using our Whisper-compatible transcription models. Responses are always returned in JSON and streaming is not supported.

Known Issue with MP4 Files

We’re currently facing issues with MP4 files for the /v1/audio/transcription endpoint. Please use MP3 - we’re actively working on resolving this ASAP.

Request Body (multipart/form-data)

Parameter	Type	Required	Description
file	file	Yes	Audio file to transcribe (.mp3, .mp4, .mpeg, .mpga, .wav, .webm)
model	string	Yes	Model to use (e.g., whisper-large-v3 or your configured alias)
prompt	string	No	Optional prompt to guide the transcription
temperature	number	No	Sampling temperature between 0 and 1
language	string	No	Language hint for the audio (ISO code, default en)
response_format	string	No	Accepted for OpenAI compatibility; output is always normalized to JSON
stream	boolean	No	Accepted for OpenAI compatibility; ignored because streaming is currently unavailable
include	array	No	Accepted for OpenAI compatibility; currently ignored
timestamp_granularities	array	No	Accepted for OpenAI compatibility; currently ignored
chunking_strategy	object	No	Accepted for OpenAI compatibility; currently ignored

Compatibility Roadmap

response_format, stream, include, timestamp_granularities, and chunking_strategy are present for OpenAI compatibility and do not change behavior today. We plan to expand support for these parameters to increase drop-in compatibility in future releases.

Example Request

cURL

cURL

curl https://api.compactif.ai/v1/audio/transcriptions -H "Authorization: Bearer YOUR_API_KEY" -F "file=@meeting_minutes.mp3" -F "model=whisper-large-v3" -F "language=en" -F "temperature=0"

Python

Python

import requests

    API_URL = "https://api.compactif.ai/v1/audio/transcriptions"
    API_KEY = "your_api_key_here"

    headers = {
        "Authorization": f"Bearer {API_KEY}"
    }

    payload = {
        "model": "whisper-large-v3",
        "language": "en",
        "temperature": 0
    }
    file_name = "meeting_minutes.mp3"
    file_content_type = "audio/mpeg"
    with open(file_name, "rb") as audio_file:
        response = requests.post(API_URL, headers=headers, data=payload, files={"file": (file_name, audio_file, file_content_type)})

    print(response.json()["text"])

Example Response

{
  "task": "transcribe",
  "language": "en",
  "duration": 12.6,
  "text": "Welcome to the quarterly planning meeting. Let's review the agenda.",
  "segments": [
    {
      "id": 0,
      "start": 0.0,
      "end": 7.5,
      "text": "Welcome to the quarterly planning meeting.",
      "temperature": 0,
      "avg_logprob": -0.12,
      "no_speech_prob": 0.01
    },
    {
      "id": 1,
      "start": 7.5,
      "end": 12.6,
      "text": "Let's review the agenda.",
      "temperature": 0,
      "avg_logprob": -0.15,
      "no_speech_prob": 0.02
    }
  ]
}

Usage Statistics

POST /usage/completions

Retrieves usage statistics for completions over a specified time period.

Request Body

Parameter	Type	Required	Description
start_time	string	Yes	Start date-time in RFC 3339 format
end_time	string	No	End date-time in RFC 3339 format
window_size	string	No	Window size (MINUTE, HOUR, DAY), default is DAY
window_timezone	string	No	Time zone in IANA format, default is UTC
group_by	array	No	List of fields to group by
filter_group_by	object	No	Filter by specific group attributes

Example Request

Grouping and Filtering Limitations

Currently, only "model" is supported for both group_by and filter_group_by parameters. Usage statistics can only be grouped by model within the specified time window.

cURL

cURL

curl https://api.compactif.ai/v1/usage/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "start_time": "2025-04-08T00:00:00Z",
  "end_time": "2025-05-09T00:00:00Z",
  "window_size": "HOUR",
  "window_timezone": "UTC",
  "group_by": ["model"],
  "filter_group_by": {"model": ["cai-llama-3-1-8b-slim"]}
}'

Python

Python

import requests

api_key = "YOUR_API_KEY"
url = "https://api.compactif.ai/v1/usage/completions"

headers = {
  "Content-Type": "application/json",
  "Authorization": f"Bearer {api_key}"
}

# Currently, only "model" is supported for group_by and filter_group_by
data = {
  "start_time": "2025-04-08T00:00:00Z",
  "end_time": "2025-05-09T00:00:00Z",
  "window_size": "HOUR",
  "window_timezone": "UTC",
  "group_by": ["model"],  # Only "model" is supported at the moment
  "filter_group_by": {"model": ["cai-llama-3-1-8b-slim"]}  # Only "model" is supported at the moment
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

JavaScript

JavaScript

async function getUsageStats() {
const response = await fetch('https://api.compactif.ai/v1/usage/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    start_time: "2025-04-08T00:00:00Z",
    end_time: "2025-05-09T00:00:00Z",
    window_size: "HOUR",
    window_timezone: "UTC",
    group_by: ["model"], // Currently, only "model" is supported
    filter_group_by: {"model": ["cai-llama-3-1-8b-slim"]} // Currently, only "model" is supported
  })
});

const data = await response.json();
console.log(data);
}

getUsageStats();

Example Response

{
  "data": [
    {
      "groupBy": {"model": "cai-llama-3-1-8b-slim"},
      "user_id": "customer-1",
      "input_token": 123,
      "output_token": 456,
      "windowStart": "2025-05-07T14:00:00Z",
      "windowEnd": "2025-05-07T15:00:00Z"
    },
    {
      "groupBy": {"model": "cai-llama-3-1-8b-slim"},
      "user_id": "customer-1",
      "input_token": 123,
      "output_token": 456,
      "windowStart": "2025-05-07T15:00:00Z",
      "windowEnd": "2025-05-07T16:00:00Z"
    }
  ],
  "start_time": "2025-04-08T00:00:00Z",
  "end_time": "2025-05-09T00:00:00Z",
  "window_size": "HOUR"
}