OpenAI Compatibility

Caesar provides OpenAI-compatible endpoints that let you use existing OpenAI client libraries to access Caesar’s research API. With minimal code changes, you can integrate Caesar into applications already using the OpenAI SDK.

Getting started

To use Caesar with the OpenAI SDK:

1. Point the base URL to https://api.caesar.xyz/compat
2. Use your Caesar API key
3. Use caesar-research as the model name

1
from openai import OpenAI
2
3
client = OpenAI(
4
    api_key="YOUR_CAESAR_API_KEY",
5
    base_url="https://api.caesar.xyz/compat"
6
)
7
8
response = client.chat.completions.create(
9
    model="caesar-research",
10
    messages=[
11
        {"role": "user", "content": "What are the latest developments in quantum computing?"}
12
    ]
13
)
14
15
print(response.choices[0].message.content)

Available endpoints

Including files in research

Caesar extends the OpenAI chat completions format to support file attachments for document-grounded research. This is a two-step process:

$
curl -X POST https://api.caesar.xyz/research/files \
>
  -H "Authorization: Bearer YOUR_CAESAR_API_KEY" \
>
  -F "file=@document.pdf"

1
{
2
  "id": "9c6f8b1a-2a4f-4a35-86b9-0d0b5e25d5e5",
3
  "filename": "document.pdf",
4
  "size": 245678,
5
  "created_at": "2025-01-15T10:30:00Z"
6
}

1
{
2
  "model": "caesar-research",
3
  "messages": [
4
    {
5
      "role": "user",
6
      "content": [
7
        {
8
          "type": "text",
9
          "text": "Summarize the key findings from this document"
10
        },
11
        {
12
          "type": "file",
13
          "file": {
14
            "filename": "document.pdf",
15
            "fileData": "9c6f8b1a-2a4f-4a35-86b9-0d0b5e25d5e5"
16
          }
17
        }
18
      ]
19
    }
20
  ]
21
}

Python example with files

1
import requests
2
from openai import OpenAI
3
4
# Step 1: Upload file
5
upload_response = requests.post(
6
    "https://api.caesar.xyz/research/files",
7
    headers={"Authorization": "Bearer YOUR_CAESAR_API_KEY"},
8
    files={"file": open("report.pdf", "rb")}
9
)
10
file_id = upload_response.json()["id"]
11
12
# Step 2: Research with file context
13
client = OpenAI(
14
    api_key="YOUR_CAESAR_API_KEY",
15
    base_url="https://api.caesar.xyz/compat"
16
)
17
18
response = client.chat.completions.create(
19
    model="caesar-research",
20
    messages=[
21
        {
22
            "role": "user",
23
            "content": [
24
                {"type": "text", "text": "What are the main conclusions in this report?"},
25
                {"type": "file", "file": {"filename": "report.pdf", "fileData": file_id}}
26
            ]
27
        }
28
    ]
29
)
30
31
print(response.choices[0].message.content)

Research configuration

Caesar extends the OpenAI format with a metadata object for fine-tuning research behavior:

1
{
2
  "model": "caesar-research",
3
  "messages": [{"role": "user", "content": "Your query"}],
4
  "metadata": {
5
    "reasoning_loops": 3,
6
    "source_timeout": 60,
7
    "reasoning_mode": true,
8
    "allow_early_exit": true,
9
    "exclude_social": false,
10
    "system_prompt": "Focus on peer-reviewed sources"
11
  }
12
}

Streaming

Enable streaming to receive results as Server-Sent Events:

1
stream = client.chat.completions.create(
2
    model="caesar-research",
3
    messages=[{"role": "user", "content": "Latest AI research trends"}],
4
    stream=True
5
)
6
7
for chunk in stream:
8
    if chunk.choices[0].delta.content:
9
        print(chunk.choices[0].delta.content, end="")

Response format

Responses follow the OpenAI format with Caesar’s research content:

1
{
2
  "id": "f2f6e5db-2c7d-4f56-bb0c-5a6b6a7a9b10",
3
  "object": "chat.completion",
4
  "created": 1705312200,
5
  "model": "caesar-research",
6
  "choices": [
7
    {
8
      "index": 0,
9
      "message": {
10
        "role": "assistant",
11
        "content": "Based on current research...\n\n## References\n[1] https://example.com/source1\n[2] https://example.com/source2"
12
      },
13
      "finish_reason": "stop"
14
    }
15
  ],
16
  "usage": {
17
    "prompt_tokens": 0,
18
    "completion_tokens": 0,
19
    "total_tokens": 0
20
  }
21
}

Supported parameters

Request fields

Response fields

Limitations

Ignored parameters

These OpenAI parameters are accepted but have no effect:

• logprobs, top_logprobs
• logit_bias
• presence_penalty, frequency_penalty
• response_format
• tools, tool_choice
• user

Error handling

Errors follow the OpenAI format:

1
{
2
  "error": {
3
    "message": "Invalid API key",
4
    "type": "authentication_error"
5
  }
6
}