Skip to main content

AI Proxy (Preview)

POST 
/api/v2/aiproxy/responses

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

Executes an AI Proxy agent through an OpenAI-compatible Responses 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, it emits a function_call output item that is returned to you to run, and you replay it plus a function_call_output 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

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

    input

    object

    required

    agent

    object

    type stringnullable
    name stringnullablerequired
    version stringnullable
    model stringnullable
    instructions stringnullable
    max_output_tokens int32nullable

    reasoning

    object

    effort stringnullable
    summary stringnullable
    store booleannullable
    stream booleannullable
    previous_response_id stringnullable
    temperature doublenullable
    top_p doublenullable
    parallel_tool_calls booleannullable

    metadata

    object

    nullable

    property name* string
    include string[]nullable

    conversation

    object

    id stringnullable

    metadata

    object

    nullable

    property name* string
    background booleannullable
    max_tool_calls int32nullable
    top_logprobs int32nullable
    safety_identifier stringnullable
    prompt_cache_key stringnullable

    prompt

    object

    id stringnullablerequired

    variables

    object

    nullable

    property name* string
    service_tier stringnullable

    stream_options

    object

    include_obfuscation booleannullable
    truncation stringnullable
    user stringnullabledeprecated
    tools arraynullable
    tool_choice nullable

    text

    object

    format

    object

    nullable

    oneOf

    verbosity stringnullable

Responses​

OK

Loading...