Skip to main content

​
Quick Start

The Oxen.ai chat completions API is fully OpenAI-compatible. You can use the OpenAI SDK, curl, or any HTTP client that speaks the OpenAI chat format. Base URL: https://hub.oxen.ai/api/ai Endpoint: POST /ai/chat/completions Browse all available models. 
curl -X POST https://hub.oxen.ai/api/ai/chat/completions \
  -H "Authorization: Bearer $OXEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {"role": "user", "content": "What is a great name for an ox?"}
    ]
  }'

​
Authentication

Every request requires a Bearer token in the Authorization header. You can find your API key in your account settings. 
Authorization: Bearer $OXEN_API_KEY
API key

​
Response Format

The API returns an OpenAI-compatible JSON response: 
{
  "id": "chatcmpl-af41f027-e4d5-4c4b-ac40-625fb4ebfb1e",
  "object": "chat.completion",
  "created": 1774040155,
  "model": "claude-sonnet-4-6",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "How about \"Beauregard\"?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 11,
    "completion_tokens": 4,
    "total_tokens": 15
  }
}
FieldDescription
idUnique identifier for the completion
objectAlways "chat.completion"
createdUnix timestamp of when the completion was created
modelThe model that generated the response
choicesArray of completion choices (typically one)
choices[].message.contentThe generated text
choices[].finish_reasonWhy generation stopped: "stop" (natural end) or "length" (hit max_tokens)
usageToken counts for the request

​
Parameters

ParameterTypeDefaultDescription
modelstringrequiredModel name, e.g. "claude-sonnet-4-6", "gpt-5-4-2026-03-05", "gemini-3-1-flash-lite-preview"
messagesarrayrequiredArray of message objects with role and content
max_tokensintegermodel defaultMaximum number of tokens to generate
temperaturefloatmodel defaultSampling temperature (0-2). Lower is more deterministic.
streambooleanfalseEnable streaming with server-sent events

​
Messages

Each message in the messages array has a role and content:
RoleDescription
systemSets the behavior and context for the model
userThe user’s input
assistantPrevious model responses (for multi-turn conversations)
{
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is the capital of France?"},
    {"role": "assistant", "content": "The capital of France is Paris."},
    {"role": "user", "content": "What is its population?"}
  ]
}

​
Streaming

Set "stream": true to receive responses as server-sent events (SSE). Each event is a chat.completion.chunk object with a delta instead of a message. 
curl -X POST https://hub.oxen.ai/api/ai/chat/completions \
  -H "Authorization: Bearer $OXEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-1-flash-lite-preview",
    "messages": [
      {"role": "user", "content": "Write a haiku about data."}
    ],
    "stream": true
  }'
Each SSE line is prefixed with data: and contains a JSON chunk: 
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1774040190,"model":"gemini-3-1-flash-lite-preview","choices":[{"index":0,"delta":{"content":"hello"},"finish_reason":null}]}
The stream ends with: 
data: [DONE]

​
Vision

Models that support vision (such as gemini-3-1-pro-preview or claude-sonnet-4-6) accept images in the messages array. For full details and examples including base64 encoding and video understanding, see Vision Language Models. 
curl -X POST https://hub.oxen.ai/api/ai/chat/completions \
  -H "Authorization: Bearer $OXEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-1-pro-preview",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "What is in this image?"},
          {"type": "image_url", "image_url": {"url": "https://oxen.ai/assets/images/homepage/hero-ox.png"}}
        ]
      }
    ]
  }'

​
Documents (PDFs)

Attach a document with a file content part. Place the document before the text part for the best results. Pass the file inline as a base64 data URL in file.file_data: 
FILE_DATA="data:application/pdf;base64,$(base64 < report.pdf | tr -d '\n')"
curl -X POST https://hub.oxen.ai/api/ai/chat/completions \
  -H "Authorization: Bearer $OXEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "file", "file": {"filename": "report.pdf", "file_data": "'"$FILE_DATA"'"}},
          {"type": "text", "text": "Summarize the key findings in this document."}
        ]
      }
    ]
  }'
You can also reference a document by URL (handy for files generated in a workspace) by passing it in file.file_url. Pass exactly one of file_data (a base64 data URL) or file_url; the URL must be publicly accessible (and unexpired, if presigned). 
curl -X POST https://hub.oxen.ai/api/ai/chat/completions \
  -H "Authorization: Bearer $OXEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "file", "file": {"file_url": "https://arxiv.org/pdf/1706.03762"}},
          {"type": "text", "text": "Summarize the key findings in this document."}
        ]
      }
    ]
  }'
Only application/pdf is supported, and a document must be 24 MB or smaller; other inputs return a 400. Referencing files by OpenAI file_id is not supported. Inline the file with file_data or pass file_url.

​
Audio

Attach audio with an audio_url content part to a model that supports audio input (such as gemini-3-1-pro-preview). Place the audio part before the text part for the best results. 
curl -X POST https://hub.oxen.ai/api/ai/chat/completions \
  -H "Authorization: Bearer $OXEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-1-pro-preview",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "audio_url", "audio_url": {"url": "https://hub.oxen.ai/api/repos/ox/Oxen-AI-Assets/file/main/audio/DoOrDoNot.m4a"}},
          {"type": "text", "text": "Transcribe this clip and summarize it in one sentence."}
        ]
      }
    ]
  }'
To send a local file, base64-encode it into a data: URL and pass it as the audio_url:
Python (OpenAI SDK)
import base64
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OXEN_API_KEY"],
    base_url="https://hub.oxen.ai/api/ai",
)

with open("clip.mp3", "rb") as f:
    audio_url = "data:audio/mp3;base64," + base64.standard_b64encode(f.read()).decode()

response = client.chat.completions.create(
    model="gemini-3-1-pro-preview",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "audio_url", "audio_url": {"url": audio_url}},
                {"type": "text", "text": "What is said in this clip?"},
            ],
        }
    ],
)

print(response.choices[0].message.content)
The URL must be publicly accessible (and unexpired, if presigned). Audio must be 20 MB or smaller; larger files return a 400. Supported formats vary by provider: OpenAI audio models (e.g. gpt-audio) accept only wav and mp3, while Gemini models (e.g. gemini-3-1-pro-preview) additionally accept m4a, aac, ogg, and flac.

​
Tool use

Tool calling (function calling) follows the same OpenAI Chat Completions tool format. You send a tools array describing each function’s JSON Schema; the model may reply with tool_calls instead of plain text. You execute those functions in your app, then send the results back in new tool messages so the model can finish the answer.
ConceptDescription
toolsArray of { "type": "function", "function": { "name", "description", "parameters" } } objects. parameters is a JSON Schema object for the arguments.
tool_choiceOptional. "auto" (default) lets the model decide; "none" disables tools; or force a specific function with {"type": "function", "function": {"name": "..."}}.
Assistant tool_callsWhen finish_reason is "tool_calls", choices[0].message.tool_calls lists each call with id, function.name, and function.arguments (a JSON string).
tool messagesEach result uses role: "tool", tool_call_id matching the call’s id, and content as a string (often JSON your tool returned).

​
Raw curl: first request (tools only)

The model may respond with tool_calls instead of user-facing content: 
curl -X POST https://hub.oxen.ai/api/ai/chat/completions \
  -H "Authorization: Bearer $OXEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-4-2026-03-05",
    "messages": [
      {"role": "user", "content": "What is the weather in Paris?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get current weather for a city",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {"type": "string", "description": "City name"}
            },
            "required": ["city"]
          }
        }
      }
    ]
  }'
Example assistant payload (abbreviated): 
{
  "choices": [
    {
      "finish_reason": "tool_calls",
      "index": 0,
      "message": {
        "content": null,
        "role": "assistant",
        "tool_calls": [
          {
            "function": {
              "arguments": "{\"city\":\"Paris\"}",
              "name": "get_weather"
            },
            "id": "call_GRNwPXnbuQW4Sa3QNB3FYkYw",
            "index": 0,
            "type": "function"
          }
        ]
      }
    }
  ],
  "created": 1774809792,
  "id": "chatcmpl-1ce4aeac-6c34-468a-ba6b-b96c5372a1dc",
  "model": "gpt-5-4-2026-03-05",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 67,
    "prompt_tokens": 572,
    "total_tokens": 639
  }
}
Run your function locally, then call the API again with the full transcript: original messages, the assistant message including tool_calls, and one tool message per call. Replace IDs and tool_calls with values from the first response. Repeat until finish_reason is "stop" (or "length") and there are no new tool_calls.

​
Follow-up request: curl and OpenAI Python SDK

The follow-up HTTP body matches what the OpenAI SDK builds when you append assistant and tool messages in a loop. 
curl -X POST https://hub.oxen.ai/api/ai/chat/completions \
  -H "Authorization: Bearer $OXEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-4-2026-03-05",
    "messages": [
      {
        "role": "user",
        "content": "What is the weather in Paris?"
      },
      {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_01ABC",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\": \"Paris\"}"
            }
          }
        ]
      },
      {
        "role": "tool",
        "tool_call_id": "call_01ABC",
        "content": "{\"temperature_c\": 18, \"conditions\": \"Partly cloudy\"}"
      }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get current weather for a city",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string",
                "description": "City name"
              }
            },
            "required": ["city"]
          }
        }
      }
    ]
  }'

​
Errors

The API returns errors as JSON with an error object and a standard HTTP status code.
StatusMeaning
400Bad request (missing model, empty messages, invalid parameters)
401Invalid or missing API key
429Rate limit exceeded
500Internal server error
{
  "error": {
    "message": "You must specify a model to call"
  }
}