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.

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

    text

    object

    jsonSchema

    object

    json_schema

    object

    required

    name stringnullablerequired
    description stringnullable
    schema required
    strict booleannullable

    jsonObject

    object

    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...