*** title: OpenAI Compatibility subtitle: Use OpenAI SDKs to access Caesar's research capabilities ------------------------------------------------------------------ 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. This compatibility layer is useful for quick integration and testing. For full access to Caesar's features, we recommend using the native [Research API](/api-reference/research/create-research). ## 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 ```python from openai import OpenAI client = OpenAI( api_key="YOUR_CAESAR_API_KEY", base_url="https://api.caesar.xyz/compat" ) response = client.chat.completions.create( model="caesar-research", messages=[ {"role": "user", "content": "What are the latest developments in quantum computing?"} ] ) print(response.choices[0].message.content) ``` ```typescript import OpenAI from "openai"; const client = new OpenAI({ apiKey: "YOUR_CAESAR_API_KEY", baseURL: "https://api.caesar.xyz/compat" }); const response = await client.chat.completions.create({ model: "caesar-research", messages: [ { role: "user", content: "What are the latest developments in quantum computing?" } ] }); console.log(response.choices[0].message.content); ``` ```bash curl https://api.caesar.xyz/compat/chat/completions \ -H "Authorization: Bearer YOUR_CAESAR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "caesar-research", "messages": [ {"role": "user", "content": "What are the latest developments in quantum computing?"} ] }' ``` ## Available endpoints | Endpoint | Description | | ------------------------------- | ------------------------------------- | | `POST /compat/chat/completions` | Chat completions format (recommended) | | `POST /compat/completions` | Text completions format | Both endpoints trigger Caesar's research workflow. The last user message becomes the research query, and the response includes synthesized findings with citations. *** ## 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: First, upload your files using the Caesar files endpoint: ```bash curl -X POST https://api.caesar.xyz/research/files \ -H "Authorization: Bearer YOUR_CAESAR_API_KEY" \ -F "file=@document.pdf" ``` Response: ```json { "id": "9c6f8b1a-2a4f-4a35-86b9-0d0b5e25d5e5", "filename": "document.pdf", "size": 245678, "created_at": "2025-01-15T10:30:00Z" } ``` Include the file ID in your chat completion request using multimodal content parts: ```json { "model": "caesar-research", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Summarize the key findings from this document" }, { "type": "file", "file": { "filename": "document.pdf", "fileData": "9c6f8b1a-2a4f-4a35-86b9-0d0b5e25d5e5" } } ] } ] } ``` **Important:** The `fileData` field must contain the Caesar file UUID returned from the upload endpoint, not base64 data or a URL. Files are only supported on `/compat/chat/completions`, not `/compat/completions`. ### Python example with files ```python import requests from openai import OpenAI # Step 1: Upload file upload_response = requests.post( "https://api.caesar.xyz/research/files", headers={"Authorization": "Bearer YOUR_CAESAR_API_KEY"}, files={"file": open("report.pdf", "rb")} ) file_id = upload_response.json()["id"] # Step 2: Research with file context client = OpenAI( api_key="YOUR_CAESAR_API_KEY", base_url="https://api.caesar.xyz/compat" ) response = client.chat.completions.create( model="caesar-research", messages=[ { "role": "user", "content": [ {"type": "text", "text": "What are the main conclusions in this report?"}, {"type": "file", "file": {"filename": "report.pdf", "fileData": file_id}} ] } ] ) print(response.choices[0].message.content) ``` *** ## Research configuration Caesar extends the OpenAI format with a `metadata` object for fine-tuning research behavior: ```json { "model": "caesar-research", "messages": [{"role": "user", "content": "Your query"}], "metadata": { "reasoning_loops": 3, "source_timeout": 60, "reasoning_mode": true, "allow_early_exit": true, "exclude_social": false, "system_prompt": "Focus on peer-reviewed sources" } } ``` | Parameter | Type | Default | Description | | ------------------ | ------- | ------- | ----------------------------- | | `reasoning_loops` | integer | auto | Research iterations (1-10) | | `source_timeout` | integer | auto | Seconds per source (3-180) | | `reasoning_mode` | boolean | auto | Use advanced reasoning models | | `allow_early_exit` | boolean | auto | Complete early if sufficient | | `exclude_social` | boolean | auto | Exclude social media sources | | `system_prompt` | string | - | Custom synthesis instructions | When `metadata` is omitted, Caesar uses **auto mode** to intelligently configure parameters based on your query. See [Research Parameters](/documentation/get-started/research-parameters) for details. *** ## Streaming Enable streaming to receive results as Server-Sent Events: ```python stream = client.chat.completions.create( model="caesar-research", messages=[{"role": "user", "content": "Latest AI research trends"}], stream=True ) for chunk in stream: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="") ``` ```typescript const stream = await client.chat.completions.create({ model: "caesar-research", messages: [{ role: "user", content: "Latest AI research trends" }], stream: true }); for await (const chunk of stream) { process.stdout.write(chunk.choices[0]?.delta?.content || ""); } ``` *** ## Response format Responses follow the OpenAI format with Caesar's research content: ```json { "id": "f2f6e5db-2c7d-4f56-bb0c-5a6b6a7a9b10", "object": "chat.completion", "created": 1705312200, "model": "caesar-research", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Based on current research...\n\n## References\n[1] https://example.com/source1\n[2] https://example.com/source2" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0 } } ``` Caesar appends a **References** section to responses with numbered citations linking to source URLs. *** ## Supported parameters ### Request fields | Field | Support | | ------------- | -------------------------------------- | | `model` | Accepted (use `caesar-research`) | | `messages` | Fully supported | | `prompt` | Fully supported (completions endpoint) | | `stream` | Fully supported | | `max_tokens` | Accepted for compatibility | | `temperature` | Accepted for compatibility (0-2) | | `top_p` | Accepted for compatibility (0-1) | | `stop` | Accepted for compatibility | | `seed` | Accepted for compatibility | | `metadata` | Caesar extension for research config | ### Response fields | Field | Support | | ------------------------- | --------------------------------- | | `id` | Fully supported (Caesar job UUID) | | `object` | Fully supported | | `created` | Fully supported | | `model` | Echo of request model | | `choices` | Always length 1 | | `choices[].message` | Fully supported | | `choices[].finish_reason` | Fully supported | | `usage` | Included (values are 0) | *** ## Limitations Usage statistics return 0 for all token fields. Caesar uses research-based pricing rather than token counting. The `n` parameter is not supported. Responses always contain exactly one choice. Tool/function calling is not supported. Caesar focuses on research synthesis rather than tool use. File attachments only work with `/compat/chat/completions`, not the text completions endpoint. ### 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: ```json { "error": { "message": "Invalid API key", "type": "authentication_error" } } ``` | Status | Meaning | | ------ | ------------------------------------------------------------- | | 400 | Invalid request (missing required fields, invalid parameters) | | 401 | Invalid or missing API key | | 429 | Rate limit exceeded | | 500 | Internal server error | For full access to Caesar's features including real-time progress events, collections, and detailed research metadata, use the [Research API](/api-reference/research/create-research) directly.