Skip to main content

AI Proxy (Preview)

POST 
/api/v2/aiproxy/chat/completions

> 🧪 Preview — This endpoint is in preview and its contract may change.

Executes an AI Proxy agent through an OpenAI-compatible Chat Completions API. Call it with the OpenAI SDKs by pointing the base URL at this route and passing your Serenity API key as a Bearer token.

Select the agent with the standard model property using the format agentCode:vendor:model (e.g. generic-proxy:OpenAI:gpt-5.4-mini). Use extra_body for execution attribution only (channel, user_identifier, group_identifier).

The tools array accepts OpenAI function (client) tools — declaration-only: when the model calls one, the call is returned to you to run, and you send the result back on a follow-up request — and AI Proxy server tools that run entirely on the server: web_search, image_generation, speech_generation and workbench. For each server tool, model/vendor (and voice/speed for speech_generation) are optional and fall back to the agent's configured defaults.

Structured output is supported through response_format: text returns plain text, json_object returns free-form JSON, and json_schema constrains the reply to a JSON schema you supply. The requested format is validated against the selected model's capabilities, so a model that cannot honour it is rejected rather than silently ignoring it.

Reasoning models are steered with the top-level reasoning_effort string, which is all the Chat Completions protocol carries. The accepted values come from the selected model's own configuration, so a model that does not expose the parameter rejects the request rather than ignoring it.

When a skill on the agent is configured to require approval, the run pauses and both the approval request and your decision travel as messages in the conversation history. See Skill Approvals for the message shapes and the full flow.

When stream is true, the response is delivered as Server-Sent Events (SSE).

Request​

Query Parameters

    culture string

    Use this param to override the culture of the response. Options: - en (default) - es

Body

required

    extra_body

    object

    The OpenAI extra_body extension object of an AI Proxy request. Carries fields that are not part of the standard OpenAI request body but are used to attribute the AI Proxy agent execution. The agent, vendor and model are selected through the standard model property (agentCode:vendor:model), not here.

    channel stringnullable

    The channel the execution is attributed to.

    user_identifier stringnullable

    Identifies the end user the execution is attributed to (usage tracking and per-user attribution).

    group_identifier stringnullable

    Identifies the group the execution is attributed to.

    messages

    object[]

    nullable

    required

  • Array [

    • oneOf

    name stringnullable

    content

    object

    required

  • ]

    • model stringnullablerequired
    audio nullable
    frequency_penalty floatnullable
    function_call nullabledeprecated
    functions arraynullabledeprecated

    logit_bias

    object

    nullable

    property name* int32
    logprobs booleannullable
    max_completion_tokens int32nullable
    max_tokens int32nullabledeprecated

    metadata

    object

    nullable

    property name* string
    modalities string[]nullable
    n int32nullable
    parallel_tool_calls booleannullable
    prediction nullable
    presence_penalty floatnullable
    prompt_cache_key stringnullable
    reasoning_effort stringnullable

    response_format

    object

    The format the model must reply in. Exactly one of the three shapes.

    oneOf

    Plain text output. The default when response_format is omitted.

    type stringrequired

    Possible values: [text]

    safety_identifier stringnullable
    seed int64nullable
    service_tier stringnullable

    stop

    object

    store booleannullable
    stream booleannullable
    stream_options nullable
    temperature floatnullable

    tool_choice

    object

    allowedTools

    object

    allowed_tools

    object

    required

    mode stringnullablerequired

    tools

    object[]

    nullable

    required

  • Array [

    • type stringnullablerequired

    function

    object

    name stringnullablerequired

  • ]

    • functionTool

    object

    function

    object

    required

    name stringnullablerequired

    customTool

    object

    custom

    object

    required

    name stringnullablerequired

    tools

    object[]

    nullable

  • Array [

    • oneOf

    function

    object

    required

    name stringnullablerequired
    description stringnullable
    parameters nullable
    strict booleannullable

  • ]

    • top_logprobs int32nullable
    top_p floatnullable
    verbosity stringnullable
    web_search_options nullable

Responses​

OK

Loading...