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.

Structured output is supported through text.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 reasoning object: effort controls how much the model thinks and detail controls how much of its reasoning is returned (auto, none, summary or full). OpenAI's reasoning.summary is accepted in place of detail and mapped onto it, so a standard OpenAI client works unchanged. 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

    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

    Reasoning configuration. Honoured on the AI Proxy routes; the inference routes accept the object but ignore it.

    effort stringnullable

    How much the model should think before answering. The accepted values come from the selected model's own configuration; a model that does not expose the parameter rejects the request.

    detail stringnullable

    Possible values: [auto, none, summary, full]

    How much of the reasoning trace is returned. auto leaves the decision to the vendor and is always accepted; the other values must be supported by the selected model's configuration.

    summary stringnullable

    OpenAI's equivalent of detail, accepted so a standard OpenAI client works unchanged. auto maps to detail: auto, concise to detail: summary and detailed to detail: full. Any other value is ignored. Used only when detail is absent.

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