OpenAI Compatible AIProxy Agents

AIProxy agents can be invoked through OpenAI-compatible endpoints, so you can talk to them with the same request/response shapes and the same official OpenAI SDKs you already use.

Two OpenAI APIs are supported:

API	Endpoint
Chat Completions	`POST /api/v2/aiproxy/chat/completions`
Responses	`POST /api/v2/aiproxy/responses`

Both endpoints support:

Streaming and non-streaming responses ("stream": true / false). See Streaming for the event formats.
Server tools — web search, image generation, speech generation and workbench (code execution), which run entirely on the server.
Client tools — standard OpenAI function calling, with the tool executed on your side.

Base URL and authentication

All examples use https://api.serenitystar.ai as the base URL and a placeholder YOUR_API_KEY.

Authenticate with your API key using either:

the dedicated header — X-API-KEY: YOUR_API_KEY, or
a bearer token — Authorization: Bearer YOUR_API_KEY.

Because the bearer form is accepted, the official OpenAI SDKs work out of the box — just set the SDK's api_key and point base_url at the AIProxy endpoint.

The `model` identifier

Unlike a plain OpenAI request, the model field selects which AIProxy agent to run and which underlying model to route to. It is a colon-separated identifier:

{agentCode}:{vendor}:{model}

Part	Required	Description
`agentCode`	Yes	The code of your AIProxy agent.
`vendor`	Yes	The AI vendor to route to (e.g. `OpenAI`, `Anthropic`, `GoogleVertex`).
`model`	Yes	The model identifier at that vendor (e.g. `gpt-5.6-luna`).

Examples:

my-aiproxy-agent:OpenAI:gpt-5.6-luna
my-aiproxy-agent:Anthropic:claude-fable-5
my-aiproxy-agent:GoogleVertex:gemini-3.5-flash

note

Only the first two colons are used as separators, so model identifiers that themselves contain colons (for example an AWS Bedrock ARN) are preserved.

The `extra_body` object

AIProxy-specific execution metadata travels in an extra_body object (snake_case field names). All fields are optional:

Field	Description
`channel`	The channel the execution is attributed to.
`user_identifier`	Identifier of the end user.
`group_identifier`	Identifier of the user's group.

"extra_body": {
    "channel": "my-channel",
    "user_identifier": "user-123",
    "group_identifier": "group-abc"
}

When using an OpenAI SDK, pass this via the SDK's extra_body parameter.

Chat Completions

POST /api/v2/aiproxy/chat/completions

Uses the OpenAI Chat Completions shape: a messages array, max_completion_tokens, stream, and an optional tools array.

Simple request

cURL
curl https://api.serenitystar.ai/api/v2/aiproxy/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "model": "my-aiproxy-agent:OpenAI:gpt-5.6-luna",
    "stream": false,
    "max_completion_tokens": 5000,
    "messages": [
        { "role": "user", "content": "Hello! Tell me a fun fact about Valencia." }
    ],
    "extra_body": {
        "channel": "my-channel",
        "user_identifier": "user-123",
        "group_identifier": "group-abc"
    }
  }'

Set "stream": true to receive chat.completion.chunk events over SSE instead of a single response.

Tools

Two kinds of tools can be declared in the tools array. They can be combined in a single request.

Server tools

Server tools run entirely on the server — there is no round-trip. Send one request and the agent invokes the tool internally and returns the final answer. The response choices still expose the trace: an assistant message with tool_calls, followed by the final assistant content.

Tool	Description	Declaration	Optional fields
Web search	Searches the web and grounds the answer in what it finds.	`{ "type": "web_search" }`	`model`, `vendor`
Image generation	Generates images from the prompt.	`{ "type": "image_generation" }`	`model`, `vendor`
Speech generation	Synthesizes speech audio from text.	`{ "type": "speech_generation" }`	`model`, `vendor`, `voice`, `speed`
Workbench	Runs code in an ephemeral micro-VM — a dedicated, isolated environment spun up per agent session so code executes safely.	`{ "type": "workbench" }`	—

When model/vendor (and the speech voice/speed) are omitted, the agent falls back to its configured defaults.

cURL — web search
curl https://api.serenitystar.ai/api/v2/aiproxy/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "model": "my-aiproxy-agent:OpenAI:gpt-5.6-luna",
    "stream": false,
    "max_completion_tokens": 5000,
    "messages": [
        { "role": "user", "content": "Search the Web for Serenity Star AI and tell me what you find." }
    ],
    "tools": [
        { "type": "web_search", "model": "gpt-5.4-mini", "vendor": "OpenAI" }
    ],
    "extra_body": { "channel": "my-channel" }
  }'

You can declare several server tools at once and let the agent pick the right one for the prompt:

"tools": [
    { "type": "web_search", "model": "gpt-5.4-mini", "vendor": "OpenAI" },
    { "type": "image_generation", "model": "gpt-image-1", "vendor": "OpenAI" },
    { "type": "speech_generation", "model": "tts-1", "vendor": "OpenAI", "voice": "echo", "speed": 2.0 },
    { "type": "workbench" }
]

Client tools

Client tools are standard OpenAI function calling: the model decides to call the function, you execute it on your side, and you send the result back for the model to complete its answer. In Chat Completions, tools use the nested function shape.

Step 1 — request that triggers the tool call.

cURL
curl https://api.serenitystar.ai/api/v2/aiproxy/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "model": "my-aiproxy-agent:Anthropic:claude-fable-5",
    "stream": false,
    "max_completion_tokens": 512,
    "messages": [
        { "role": "user", "content": "What is the weather like in Paris right now? Use the tool." }
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "Get the current weather for a given city",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "city": { "type": "string", "description": "The city name" }
                    },
                    "required": ["city"]
                }
            }
        }
    ],
    "extra_body": { "channel": "my-channel" }
  }'

The response comes back with finish_reason: "tool_calls" and a tool_call carrying an id and the arguments:

{
    "choices": [
        {
            "finish_reason": "tool_calls",
            "message": {
                "role": "assistant",
                "tool_calls": [
                    {
                        "id": "call_abc123",
                        "type": "function",
                        "function": { "name": "get_weather", "arguments": "{\"city\":\"Paris\"}" }
                    }
                ]
            }
        }
    ]
}

Step 2 — run the function and send the result back. Append the assistant message (with the tool_calls) and a role: "tool" message whose tool_call_id matches the id from step 1.

cURL
curl https://api.serenitystar.ai/api/v2/aiproxy/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "model": "my-aiproxy-agent:Anthropic:claude-fable-5",
    "stream": false,
    "max_completion_tokens": 512,
    "messages": [
        { "role": "user", "content": "What is the weather like in Paris right now? Use the tool." },
        {
            "role": "assistant",
            "tool_calls": [
                {
                    "id": "call_abc123",
                    "type": "function",
                    "function": { "name": "get_weather", "arguments": "{\"city\":\"Paris\"}" }
                }
            ]
        },
        {
            "role": "tool",
            "tool_call_id": "call_abc123",
            "content": "{\"city\":\"Paris\",\"temperature_c\":18,\"condition\":\"light rain\",\"humidity\":72}"
        }
    ],
    "extra_body": { "channel": "my-channel" }
  }'

The final response contains the assistant answer that reflects the tool result.

Responses

POST /api/v2/aiproxy/responses

Uses the OpenAI Responses shape: an input array, max_output_tokens, stream, and an optional tools array. Note that in the Responses API tools are a flat array ({ "type": "function", "name", ... }) and the model returns a function_call output item.

Simple request

cURL
curl https://api.serenitystar.ai/api/v2/aiproxy/responses \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "model": "my-aiproxy-agent:OpenAI:gpt-5.6-luna",
    "stream": false,
    "max_output_tokens": 5000,
    "input": [
        { "role": "user", "content": "Hello! Tell me a fun fact about Valencia." }
    ],
    "extra_body": {
        "channel": "my-channel",
        "user_identifier": "user-123",
        "group_identifier": "group-abc"
    }
  }'

Tools

As with Chat Completions, both server tools and client tools are declared in the tools array and can be combined.

Server tools

The available server tools and their optional fields are identical to Chat Completions:

"tools": [
    { "type": "web_search", "model": "gpt-5.4-mini", "vendor": "OpenAI" },
    { "type": "image_generation", "model": "gpt-image-1", "vendor": "OpenAI" },
    { "type": "speech_generation", "model": "tts-1", "vendor": "OpenAI", "voice": "echo", "speed": 2.0 },
    { "type": "workbench" }
]

cURL — web search
curl https://api.serenitystar.ai/api/v2/aiproxy/responses \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "model": "my-aiproxy-agent:OpenAI:gpt-5.6-luna",
    "stream": false,
    "max_output_tokens": 5000,
    "input": [
        { "role": "user", "content": "Search the Web for Serenity Star AI and tell me what you find." }
    ],
    "tools": [
        { "type": "web_search", "model": "gpt-5.4-mini", "vendor": "OpenAI" }
    ],
    "extra_body": { "channel": "my-channel" }
  }'

The server runs the tool internally and returns the final answer. The output array still shows the trace: a function_call, a function_call_output, and the final assistant message.

Client tools

Client tools follow OpenAI function calling for the Responses API. Tools are declared flat, and the model returns a function_call output item (with a call_id, name, and arguments).

Step 1 — request that triggers the function call.

cURL
curl https://api.serenitystar.ai/api/v2/aiproxy/responses \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "model": "my-aiproxy-agent:Anthropic:claude-fable-5",
    "stream": false,
    "max_output_tokens": 5000,
    "input": [
        { "role": "user", "content": "What is the weather like in Berlin right now? Use the tool." }
    ],
    "tools": [
        {
            "type": "function",
            "name": "get_weather",
            "description": "Get the current weather for a given city",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": { "type": "string", "description": "The city name" }
                },
                "required": ["city"]
            }
        }
    ],
    "extra_body": { "channel": "my-channel" }
  }'

The response output contains a function_call item:

{
    "output": [
        {
            "type": "function_call",
            "call_id": "call_abc123",
            "name": "get_weather",
            "arguments": "{\"city\":\"Berlin\"}"
        }
    ]
}

Step 2 — run the function and send the result back. Replay the function_call in input, then append a function_call_output item with the same call_id.

cURL
curl https://api.serenitystar.ai/api/v2/aiproxy/responses \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "model": "my-aiproxy-agent:Anthropic:claude-fable-5",
    "stream": false,
    "max_output_tokens": 5000,
    "input": [
        { "role": "user", "content": "What is the weather like in Berlin right now? Use the tool." },
        {
            "type": "function_call",
            "call_id": "call_abc123",
            "name": "get_weather",
            "arguments": "{\"city\":\"Berlin\"}"
        },
        {
            "type": "function_call_output",
            "call_id": "call_abc123",
            "output": "{\"city\":\"Berlin\",\"temperature_c\":12,\"condition\":\"overcast\",\"humidity\":80}"
        }
    ],
    "tools": [
        {
            "type": "function",
            "name": "get_weather",
            "description": "Get the current weather for a given city",
            "parameters": {
                "type": "object",
                "properties": { "city": { "type": "string" } },
                "required": ["city"]
            }
        }
    ],
    "extra_body": { "channel": "my-channel" }
  }'

The final response contains the assistant message that reflects the tool result.

OpenAI Compatible AIProxy Agents

The model identifier​

The extra_body object​

Chat Completions​

Simple request​

Tools​

Server tools​

Client tools​

Responses​

Simple request​

Tools​

Server tools​

Client tools​

The `model` identifier

The `extra_body` object

Chat Completions

Simple request

Tools

Server tools

Client tools

Responses

Simple request

Tools

Server tools

Client tools