{
  "openapi": "3.1.0",
  "info": {
    "title": "AuthAPI",
    "version": "1.0.0",
    "description": "OpenAI-compatible API backed by each user's connected Codex/ChatGPT session."
  },
  "servers": [{ "url": "https://codex.authapi.dev" }],
  "security": [{ "bearerAuth": [] }],
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "cxa API key" },
      "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "cxa_session" }
    },
    "schemas": {
      "AutomaticModelConfiguration": {
        "type": "object", "additionalProperties": false, "required": ["enabled"],
        "properties": {
          "enabled": { "type": "boolean" },
          "confirm_usage": { "type": "boolean", "description": "Must be true whenever enabling; consents to real potentially billable generation attempts." },
          "publish": { "type": "boolean", "default": false, "description": "Explicitly publish verified IDs and safe model metadata, never credentials or owner identifiers." },
          "max_probe_requests_per_day": { "type": "integer", "minimum": 1, "maximum": 16, "default": 16 }
        },
        "allOf": [{ "if": { "properties": { "enabled": { "const": true } }, "required": ["enabled"] }, "then": { "required": ["confirm_usage"], "properties": { "confirm_usage": { "const": true } } } }]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": { "type": "string" },
              "type": { "type": "string" },
              "param": { "type": ["string", "null"] },
              "code": { "type": ["string", "null"] }
            }
          }
        }
      },
      "FunctionDefinition": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" },
          "description": { "type": "string", "maxLength": 4096 },
          "parameters": { "type": "object", "description": "JSON Schema for function arguments; defaults to an empty object schema when omitted", "default": { "type": "object", "properties": {} } },
          "strict": { "type": "boolean" }
        }
      },
      "ChatFunctionTool": {
        "type": "object", "required": ["type", "function"],
        "properties": { "type": { "const": "function" }, "function": { "$ref": "#/components/schemas/FunctionDefinition" } }
      },
      "ResponseFunctionTool": {
        "allOf": [
          { "$ref": "#/components/schemas/FunctionDefinition" },
          { "type": "object", "required": ["type"], "properties": { "type": { "const": "function" } } }
        ]
      },
      "ChatToolCall": {
        "type": "object", "required": ["id", "type", "function"],
        "properties": {
          "id": { "type": "string" }, "type": { "const": "function" },
          "function": { "type": "object", "required": ["name", "arguments"], "properties": { "name": { "type": "string" }, "arguments": { "type": "string", "description": "JSON-encoded arguments" } } }
        }
      },
      "ChatToolChoice": {
        "oneOf": [
          { "type": "string", "enum": ["none", "auto", "required"] },
          { "type": "object", "required": ["type", "function"], "properties": { "type": { "const": "function" }, "function": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" } } } } }
        ]
      },
      "ResponseToolChoice": {
        "oneOf": [
          { "type": "string", "enum": ["none", "auto", "required"] },
          { "type": "object", "required": ["type", "name"], "properties": { "type": { "const": "function" }, "name": { "type": "string" } } }
        ]
      },
      "Message": {
        "oneOf": [
          {
            "type": "object", "required": ["role", "content"],
            "properties": {
              "role": { "type": "string", "enum": ["system", "developer", "user"] },
              "content": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "oneOf": [{ "$ref": "#/components/schemas/ResponseTextInputPart" }, { "$ref": "#/components/schemas/ResponseImageInputPart" }, { "$ref": "#/components/schemas/ChatFileInputPart" }] } }] }
            }
          },
          {
            "type": "object", "required": ["role"],
            "properties": {
              "role": { "const": "assistant" },
              "content": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "object" } }, { "type": "null" }] },
              "tool_calls": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ChatToolCall" } }
            }
          },
          {
            "type": "object", "required": ["role", "tool_call_id", "content"],
            "properties": { "role": { "const": "tool" }, "tool_call_id": { "type": "string" }, "content": { "type": "string" } }
          }
        ]
      },
      "ResponseFunctionCallInput": {
        "type": "object", "required": ["type", "call_id", "name", "arguments"],
        "properties": { "type": { "const": "function_call" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" } }
      },
      "ResponseFunctionCallOutput": {
        "type": "object", "required": ["type", "call_id", "output"],
        "properties": { "type": { "const": "function_call_output" }, "call_id": { "type": "string" }, "output": {} }
      },
      "ResponseTextInputPart": {
        "type": "object", "required": ["type", "text"], "additionalProperties": false,
        "properties": { "type": { "type": "string", "enum": ["text", "input_text", "output_text"] }, "text": { "type": "string" } }
      },
      "ResponseImageInputPart": {
        "oneOf": [
          { "type": "object", "required": ["type", "image_url"], "additionalProperties": false, "properties": { "type": { "const": "input_image" }, "image_url": { "type": "string" } } },
          { "type": "object", "required": ["type", "image_url"], "additionalProperties": false, "properties": { "type": { "const": "image_url" }, "image_url": { "oneOf": [{ "type": "string" }, { "type": "object", "required": ["url"], "additionalProperties": false, "properties": { "url": { "type": "string" } } }] } } }
        ]
      },
      "PdfFileData": {
        "type": "object", "required": ["filename", "file_data"], "additionalProperties": false,
        "description": "Inline PDF only: canonical non-empty base64 with exact application/pdf MIME and decoded %PDF- magic. At most 20971520 decoded bytes per PDF; total JSON request at most 30000000 UTF-8 bytes. A plain .pdf filename is required, at most 255 characters, without paths, colon or control characters. file_id, file_url, remote URLs and other formats are not implemented. No fetch, OCR or text fallback. Native Codex upstream PDF acceptance has not been live verified; upstream rejection fails explicitly.",
        "properties": {
          "filename": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[^/\\\\:\\u0000-\\u001f\\u007f]+\\.[pP][dD][fF]$" },
          "file_data": { "type": "string", "maxLength": 27962056, "pattern": "^data:application/pdf;base64,[A-Za-z0-9+/]+={0,2}$" }
        }
      },
      "ChatFileInputPart": {
        "type": "object", "required": ["type", "file"], "additionalProperties": false,
        "properties": { "type": { "const": "file" }, "file": { "$ref": "#/components/schemas/PdfFileData" } }
      },
      "ResponseFileInputPart": {
        "type": "object", "required": ["type", "filename", "file_data"], "additionalProperties": false,
        "description": "Native input_file PDF, subject to PdfFileData validation and limits. Upstream support remains unverified; errors do not fall back to extracted text.",
        "properties": {
          "type": { "const": "input_file" },
          "filename": { "$ref": "#/components/schemas/PdfFileData/properties/filename" },
          "file_data": { "$ref": "#/components/schemas/PdfFileData/properties/file_data" }
        }
      },
      "ResponseInputItem": {
        "description": "A supported Responses message input. Function items use their dedicated schemas.",
        "oneOf": [
          {
            "type": "object", "required": ["role", "content"], "additionalProperties": false,
            "properties": {
              "type": { "const": "message" },
              "role": { "type": "string", "enum": ["system", "developer", "user"] },
              "content": { "oneOf": [{ "type": "string" }, { "type": "array", "minItems": 1, "items": { "oneOf": [{ "$ref": "#/components/schemas/ResponseTextInputPart" }, { "$ref": "#/components/schemas/ResponseImageInputPart" }, { "$ref": "#/components/schemas/ResponseFileInputPart" }] } }] }
            }
          },
          {
            "type": "object", "required": ["role", "content"], "additionalProperties": false,
            "properties": {
              "type": { "const": "message" }, "role": { "const": "assistant" },
              "content": { "oneOf": [{ "type": "string" }, { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ResponseTextInputPart" } }] }
            }
          }
        ]
      },
      "ResponseFunctionCall": {
        "type": "object", "required": ["id", "type", "call_id", "name", "arguments"],
        "properties": { "id": { "type": "string" }, "type": { "const": "function_call" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string", "enum": ["in_progress", "completed", "incomplete"] } }
      },
      "ResponseOutputItem": {
        "type": "object",
        "description": "A non-function-call Responses output item, such as an assistant message or reasoning item.",
        "not": { "type": "object", "required": ["type"], "properties": { "type": { "const": "function_call" } } }
      },
      "ChatCompletionResponse": {
        "type": "object", "required": ["id", "object", "created", "model", "choices"],
        "properties": {
          "id": { "type": "string" }, "object": { "const": "chat.completion" }, "created": { "type": "integer" }, "model": { "type": "string" },
          "choices": { "type": "array", "items": { "type": "object", "required": ["index", "message", "finish_reason"], "properties": {
            "index": { "type": "integer" },
            "message": { "type": "object", "required": ["role", "content"], "properties": { "role": { "const": "assistant" }, "content": { "type": ["string", "null"] }, "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ChatToolCall" } } } },
            "finish_reason": { "type": "string", "enum": ["stop", "tool_calls"] }
          } } },
          "usage": { "type": "object" }
        },
        "example": { "id": "chatcmpl-example", "object": "chat.completion", "created": 1784563200, "model": "gpt-5.6-sol", "choices": [{ "index": 0, "message": { "role": "assistant", "content": null, "tool_calls": [{ "id": "call_weather", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\":\"Paris\"}" } }] }, "finish_reason": "tool_calls" }], "usage": { "prompt_tokens": 12, "completion_tokens": 8, "total_tokens": 20 } }
      },
      "ChatToolCallDelta": {
        "type": "object", "required": ["index"],
        "properties": { "index": { "type": "integer" }, "id": { "type": "string" }, "type": { "const": "function" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } }
      },
      "ChatCompletionChunk": {
        "type": "object", "required": ["id", "object", "created", "model", "choices"],
        "properties": {
          "id": { "type": "string" }, "object": { "const": "chat.completion.chunk" }, "created": { "type": "integer" }, "model": { "type": "string" },
          "choices": { "type": "array", "items": { "type": "object", "required": ["index", "delta", "finish_reason"], "properties": { "index": { "type": "integer" }, "delta": { "type": "object", "properties": { "role": { "const": "assistant" }, "content": { "type": "string" }, "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ChatToolCallDelta" } } } }, "finish_reason": { "type": ["string", "null"], "enum": ["stop", "tool_calls", null] } } } }
        },
        "examples": [
          { "id": "chatcmpl-example", "object": "chat.completion.chunk", "created": 1784563200, "model": "gpt-5.6-sol", "choices": [{ "index": 0, "delta": { "tool_calls": [{ "index": 0, "id": "call_weather", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\"" } }] }, "finish_reason": null }] },
          { "id": "chatcmpl-example", "object": "chat.completion.chunk", "created": 1784563200, "model": "gpt-5.6-sol", "choices": [{ "index": 0, "delta": { "tool_calls": [{ "index": 0, "function": { "arguments": ":\"Paris\"}" } }] }, "finish_reason": null }] },
          { "id": "chatcmpl-example", "object": "chat.completion.chunk", "created": 1784563200, "model": "gpt-5.6-sol", "choices": [{ "index": 0, "delta": {}, "finish_reason": "tool_calls" }] }
        ]
      },
      "ResponseObject": {
        "type": "object", "required": ["id", "object", "status", "output"],
        "properties": { "id": { "type": "string" }, "object": { "const": "response" }, "status": { "type": "string" }, "output": { "type": "array", "items": { "oneOf": [{ "$ref": "#/components/schemas/ResponseFunctionCall" }, { "$ref": "#/components/schemas/ResponseOutputItem" }] } }, "output_text": { "type": "string" }, "usage": { "type": "object" } },
        "example": { "id": "resp_example", "object": "response", "status": "completed", "output": [{ "id": "fc_example", "type": "function_call", "call_id": "call_weather", "name": "get_weather", "arguments": "{\"city\":\"Paris\"}", "status": "completed" }], "output_text": "", "usage": { "input_tokens": 12, "output_tokens": 8, "total_tokens": 20 } }
      },
      "ResponseStreamEvent": {
        "oneOf": [
          { "type": "object", "required": ["type", "output_index", "item"], "properties": { "type": { "const": "response.output_item.added" }, "output_index": { "type": "integer" }, "item": { "$ref": "#/components/schemas/ResponseFunctionCall" } } },
          { "type": "object", "required": ["type", "item_id", "output_index", "delta"], "properties": { "type": { "const": "response.function_call_arguments.delta" }, "item_id": { "type": "string" }, "output_index": { "type": "integer" }, "delta": { "type": "string" } } },
          { "type": "object", "required": ["type", "item_id", "output_index", "arguments"], "properties": { "type": { "const": "response.function_call_arguments.done" }, "item_id": { "type": "string" }, "output_index": { "type": "integer" }, "arguments": { "type": "string" } } },
          { "type": "object", "required": ["type", "response"], "properties": { "type": { "const": "response.completed" }, "response": { "$ref": "#/components/schemas/ResponseObject" } } }
        ],
        "examples": [
          { "type": "response.output_item.added", "output_index": 0, "item": { "id": "fc_example", "type": "function_call", "call_id": "call_weather", "name": "get_weather", "arguments": "", "status": "in_progress" } },
          { "type": "response.function_call_arguments.delta", "item_id": "fc_example", "output_index": 0, "delta": "{\"city\":\"Par" },
          { "type": "response.function_call_arguments.done", "item_id": "fc_example", "output_index": 0, "arguments": "{\"city\":\"Paris\"}" }
        ]
      }
    },
    "headers": {
      "RequestId": { "description": "Request correlation UUID", "schema": { "type": "string", "format": "uuid" } },
      "RetryAfter": { "description": "Seconds until the upstream account cooldown may be retried", "schema": { "type": "integer", "minimum": 1, "maximum": 3600 } }
    },
    "responses": {
      "ImageError": {
        "description": "Sanitized image request error",
        "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  },
  "paths": {
    "/v1/limits": {
      "get": {
        "summary": "Read the API key owner's current Codex plan limits",
        "description": "API-key-authenticated provider quota endpoint. Returns the same normalized 5-hour, weekly, other, and additional limits schema as /api/provider-usage, scoped to the bearer key's owner, with no account identity or credentials. /limits is an equivalent alias.",
        "operationId": "getLimits",
        "responses": {
          "200": {
            "description": "Current normalized Codex usage windows",
            "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } },
            "content": { "application/json": { "schema": { "$ref": "#/paths/~1api~1provider-usage/get/responses/200/content/application~1json/schema" } } }
          },
          "401": { "description": "Valid bearer API key required", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "Codex must be connected or reconnected", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "502": { "description": "Sanitized upstream or response-schema failure", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "503": { "description": "Provider usage service temporarily rate limited", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "504": { "description": "Provider usage request timed out", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/limits": {
      "get": {
        "summary": "Alias for GET /v1/limits",
        "description": "API-key-authenticated alias for /v1/limits, scoped to the bearer key's owner and returned with Cache-Control: private, no-store.",
        "operationId": "getLimitsAlias",
        "responses": {
          "200": { "$ref": "#/paths/~1v1~1limits/get/responses/200" },
          "401": { "$ref": "#/paths/~1v1~1limits/get/responses/401" },
          "409": { "$ref": "#/paths/~1v1~1limits/get/responses/409" },
          "502": { "$ref": "#/paths/~1v1~1limits/get/responses/502" },
          "503": { "$ref": "#/paths/~1v1~1limits/get/responses/503" },
          "504": { "$ref": "#/paths/~1v1~1limits/get/responses/504" }
        }
      }
    },
    "/api/provider-usage": {
      "get": {
        "summary": "Read the logged-in owner's current Codex plan limits",
        "description": "Fetches provider-reported rolling usage windows through the owner's connected Codex OAuth account. This account endpoint requires the cxa_session cookie, returns only normalized limit data, omits account identity and credentials, classifies 5-hour and weekly windows by duration, and does not fabricate missing windows.",
        "operationId": "getProviderUsage",
        "security": [{ "cookieAuth": [] }],
        "responses": {
          "200": {
            "description": "Current normalized Codex usage windows",
            "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } },
            "content": { "application/json": { "schema": {
              "type": "object",
              "required": ["available", "fetchedAt", "planType", "limits"],
              "properties": {
                "available": { "const": true },
                "fetchedAt": { "type": "string", "format": "date-time" },
                "planType": { "type": ["string", "null"] },
                "limits": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": ["id", "name", "meteredFeature", "allowed", "limitReached", "windows"],
                    "properties": {
                      "id": { "type": "string" },
                      "name": { "type": "string" },
                      "meteredFeature": { "type": ["string", "null"] },
                      "allowed": { "type": "boolean" },
                      "limitReached": { "type": "boolean" },
                      "windows": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "required": ["kind", "label", "usedPercent", "remainingPercent", "windowSeconds", "resetsAt"],
                          "properties": {
                            "kind": { "type": "string", "enum": ["five_hour", "weekly", "other"] },
                            "label": { "type": "string" },
                            "usedPercent": { "type": "number", "minimum": 0, "maximum": 100 },
                            "remainingPercent": { "type": "number", "minimum": 0, "maximum": 100 },
                            "windowSeconds": { "type": "integer", "minimum": 1 },
                            "resetsAt": { "type": "string", "format": "date-time" }
                          }
                        }
                      }
                    }
                  }
                }
              }
            } } }
          },
          "401": { "description": "Logged-in browser session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "Codex must be connected or reconnected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "502": { "description": "Sanitized upstream or response-schema failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "503": { "description": "Provider usage service temporarily rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "504": { "description": "Provider usage request timed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/voice/session": {
      "post": {
        "summary": "Create a WebRTC voice session with optional custom functions",
        "description": "Creates an experimental Codex Frameless Bidi V3 WebRTC session using the authenticated owner's connected Codex account. Supply OpenAI-style flat function tools to register the client-delegation Responses adapter, or set conversation_only to true for a server-instructed no-tools session. Same-origin AuthAPI browsers use a login cookie. External browsers must send their SDP through their own backend, which makes an origin-less bearer request; never expose a cxa key in browser code. The backend resolves delegated text through POST /v1/responses, executes allowlisted functions, and returns outputs over the browser's oai-events data channel; the gateway never executes caller tools.",
        "operationId": "createVoiceSession",
        "security": [{ "cookieAuth": [] }, { "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["sdp"],
            "properties": {
              "sdp": { "type": "string", "maxLength": 131072, "description": "ICE-complete browser WebRTC SDP audio offer" },
              "voice": { "type": "string", "enum": ["juniper", "maple", "spruce", "ember", "vale", "breeze", "arbor", "sol", "cove"], "default": "cove" },
              "instructions": { "type": "string", "minLength": 1, "maxLength": 16384, "pattern": ".*\\S.*", "description": "Live voice instructions that help Frameless Bidi decide when to delegate. Requires tools. Do not blindly copy untrusted voice instructions into the privileged /v1/responses selector instructions." },
              "tools": { "type": "array", "minItems": 1, "maxItems": 128, "items": { "$ref": "#/components/schemas/ResponseFunctionTool" }, "description": "Flat OpenAI function definitions for the client-delegation Responses adapter. A bounded name/description registry is placed in voice instructions. Voice Lab resolves delegations through same-origin /api/voice/responses; external callers resubmit the tools to bearer-authenticated /v1/responses, execute the selected function, and return its output as delegation context." },
              "tool_choice": { "allOf": [{ "$ref": "#/components/schemas/ResponseToolChoice" }], "description": "auto, none, required, or a forced supplied function. Requires tools." },
              "response_model": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "default": "gpt-5.5", "description": "Responses model used for delegated function selection. Requires tools." },
              "conversation_only": { "type": "boolean", "default": false, "description": "Create a fixed-instruction conversational session with delegation disabled. Cannot be combined with tools, tool_choice, instructions, or response_model." }
            },
            "dependentRequired": { "instructions": ["tools"], "tool_choice": ["tools"], "response_model": ["tools"] },
            "allOf": [{
              "not": {
                "required": ["conversation_only"],
                "properties": { "conversation_only": { "const": true } },
                "anyOf": [
                  { "required": ["tools"] }, { "required": ["tool_choice"] },
                  { "required": ["instructions"] }, { "required": ["response_model"] }
                ]
              }
            }],
            "additionalProperties": false
          } } }
        },
        "x-realtime-data-channel": {
          "label": "oai-events",
          "encoding": "UTF-8 JSON; one object per message",
          "createBeforeOffer": true,
          "audioDelivery": "WebRTC media tracks, not data-channel JSON",
          "transcriptEvents": [
            { "type": "input_transcript.added", "role": "user", "textPath": "item.text", "action": "append_to_role_draft" },
            { "type": "output_transcript.added", "role": "assistant", "textPath": "item.text", "action": "append_to_role_draft" },
            { "type": "turn.done", "rolePath": "turn.role", "textPath": "turn.transcript", "action": "replace_role_draft_and_finalize" }
          ],
          "externalBrowserTopology": {
            "browserToApplicationBackend": ["ICE-complete SDP offer", "application voice-session ID plus delegation item ID and text"],
            "applicationBackendToAuthAPI": ["origin-less bearer POST /api/voice/session", "bearer POST /v1/responses with stream=true and parallel_tool_calls=false"],
            "secretRule": "Never expose a cxa API key in browser JavaScript. External browser origins cannot authenticate /api/voice/session with a bearer key.",
            "responseModelMapping": "Copy the session response_model value into the /v1/responses model field.",
            "toolChoiceMapping": "Retain the session's normalized tool_choice and send it as /v1/responses.tool_choice.",
            "instructionsMapping": "Voice instructions control delegation. Use separate trusted Responses instructions for privileged function selection."
          },
          "delegationEvents": [
            { "type": "delegation.created", "direction": "server_to_client", "itemIdPath": "item.id", "handoffIdPath": "item.handoff_id", "handoffIdSemantics": "Optional voice transport metadata; not a Responses call_id.", "inputPath": "item.content[type=input_text].text" },
            { "type": "delegation.context.append", "direction": "client_to_server", "bindingPath": "delegation_item_id", "contentPath": "content[type=input_text].text", "contentSemantics": "Success context contains encoded OpenAI-style function_call_output with the Responses call_id. A pre-call/no-call failure uses sanitized plain text and must not invent a call_id." },
            { "type": "delegation.context.appended", "direction": "server_to_client", "bindingPath": "delegation_item_id" }
          ],
          "clientFunctions": [
            { "type": "function", "name": "change_voice", "strict": true, "parameters": { "type": "object", "properties": { "voice": { "type": "string", "enum": ["cove", "juniper", "maple", "spruce", "ember", "vale", "breeze", "arbor", "sol"] } }, "additionalProperties": false } },
            { "type": "function", "name": "clear_voice_transcript", "strict": true, "parameters": { "type": "object", "properties": {}, "additionalProperties": false } }
          ],
          "customFunctionEvents": [
            { "type": "delegation.created", "direction": "server_to_client", "source": "oai-events", "purpose": "Read item.id and delegated input, then send them to the application's backend. Voice Lab uses same-origin /api/voice/responses; external backends use bearer-authenticated /v1/responses with parallel_tool_calls=false and stream=true." },
            { "type": "response.output_item.added", "direction": "server_to_client", "source": "Responses SSE", "purpose": "Store item.id, item.call_id, and item.name for each selected function_call." },
            { "type": "response.function_call_arguments.delta", "direction": "server_to_client", "source": "Responses SSE", "purpose": "Append bounded argument fragments for the correlated item when needed." },
            { "type": "response.function_call_arguments.done", "direction": "server_to_client", "source": "Responses SSE", "purpose": "Store complete arguments for the correlated item." },
            { "type": "response.output_item.done", "direction": "server_to_client", "source": "Responses SSE", "purpose": "Authoritative completed function_call item, including full arguments when supplied." },
            { "type": "response.completed", "direction": "server_to_client", "source": "Responses SSE", "purpose": "Required terminal success event. Execute only after exactly one allowlisted call has complete valid arguments." },
            { "type": "response.failed", "direction": "server_to_client", "source": "Responses SSE", "purpose": "Terminal failure. Execute nothing and return sanitized failure context." },
            { "type": "error", "direction": "server_to_client", "source": "Responses SSE or oai-events", "purpose": "Execute nothing, sanitize details, and resolve the delegation with safe failure context when possible." },
            { "type": "delegation.context.append", "direction": "client_to_server", "source": "oai-events", "purpose": "Return success or failure context, bound by delegation_item_id. Structured function output must be stringified." },
            { "type": "delegation.context.appended", "direction": "server_to_client", "source": "oai-events", "purpose": "Acknowledges accepted function output context; a missing acknowledgement must not cause blind re-execution." }
          ],
          "customFunctionFailurePolicy": {
            "failClosedOn": ["zero or multiple calls", "unknown function", "invalid or uncorrelated arguments", "schema mismatch", "malformed or truncated SSE", "response.failed", "error", "timeout", "execution exception"],
            "action": "Execute nothing and append sanitized failure context so the live voice turn can continue.",
            "idempotency": "Cache work by delegation.created.item.id; never repeat a side effect for a duplicate event or delayed acknowledgement.",
            "output": "function_call_output.output must be a string. Enforce an application limit and summarize or store large results elsewhere."
          },
          "customFunctionResult": { "type": "delegation.context.append", "delegation_item_id": "delegation_123", "channel": "speakable", "content": [{ "type": "input_text", "text": "Function get_weather completed successfully. {\"type\":\"function_call_output\",\"call_id\":\"call_123\",\"output\":\"{\\\"temperature\\\":72}\"}" }] },
          "noCustomToolsBehavior": "Requests without tools use the existing plain client-delegation voice behavior unless conversation_only is true. conversation_only uses fixed server-owned instructions and disables delegation. Voice Lab always registers its two local webpage tools.",
          "renderingNotes": [
            "Keep separate user and assistant drafts because events can interleave.",
            "Append each added fragment exactly once.",
            "The turn.done transcript is authoritative and replaces the draft; do not append it.",
            "Ignore unknown event types and sanitize error events."
          ]
        },
        "responses": {
          "201": { "description": "Frameless Bidi V3 WebRTC SDP answer created", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["sdp", "protocol"], "properties": { "sdp": { "type": "string" }, "protocol": { "type": "object", "required": ["transport", "architecture", "version", "experimental", "dataChannel", "model", "voice", "delegation"], "properties": { "transport": { "const": "webrtc" }, "architecture": { "const": "frameless-bidi" }, "version": { "const": 3 }, "experimental": { "const": true }, "dataChannel": { "const": "oai-events" }, "model": { "const": "gpt-live-1-codex" }, "voice": { "type": "string" }, "delegation": { "type": "string", "enum": ["client", "none"], "description": "client enables Frameless Bidi client delegations; none identifies a conversation_only session with delegation disabled." }, "responseModel": { "type": "string", "description": "Responses model selected for the adapter; present when tools were registered." }, "functionTransport": { "const": "responses-adapter" }, "toolChoice": { "$ref": "#/components/schemas/ResponseToolChoice" }, "toolCount": { "type": "integer", "minimum": 1, "maximum": 128 } } } } } } } },
          "400": { "description": "Invalid SDP, voice, instructions, tools, tool choice, response model, or JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Login or cxa API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "Browser Origin rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "Codex connection required or must be reconnected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Per-owner session creation rate exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "502": { "description": "Sanitized upstream failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "503": { "description": "Upstream realtime service rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "504": { "description": "Upstream negotiation timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/audio/speech": {
      "post": {
        "summary": "Generate speech with the API-key owner's Codex OAuth session",
        "description": "Uses Codex's GA realtime WebSocket output-audio stream server-side. The completed output transcript is checked against the input before audio is returned.",
        "operationId": "createSpeech",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["input"], "properties": { "model": { "type": "string", "enum": ["codex-tts", "gpt-4o-mini-tts", "gpt-realtime-1.5"], "default": "codex-tts" }, "input": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": ".*\\S.*" }, "voice": { "type": "string", "enum": ["alloy", "ash", "ballad", "cedar", "coral", "echo", "marin", "sage", "shimmer", "verse"], "default": "marin" }, "response_format": { "type": "string", "enum": ["wav", "pcm"], "default": "wav" }, "speed": { "const": 1, "default": 1 }, "instructions": { "type": "string", "maxLength": 500 } }, "additionalProperties": false } } } },
        "responses": {
          "200": { "description": "24 kHz mono 16-bit speech audio", "headers": { "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/pcm": { "schema": { "type": "string", "format": "binary" } } } },
          "400": { "description": "Invalid speech request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "API-key owner has not connected Codex auth", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "Codex reconnect required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "413": { "description": "JSON body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Admission limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "502": { "description": "Sanitized upstream failure or incomplete speech", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "503": { "description": "Upstream rate limited or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "504": { "description": "Generation timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/audio/transcriptions": {
      "post": {
        "summary": "Transcribe audio with the API-key owner's Codex OAuth session",
        "description": "OpenAI-compatible multipart transcription subset backed by the same private batch transcription route used by the Codex prompt box. Audio and transcripts are not logged or stored.",
        "operationId": "createTranscription",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["file", "model"],
                "properties": {
                  "file": { "type": "string", "format": "binary", "description": "Audio file up to 25 MB. Supported containers: FLAC, M4A, MP3/MP4/MPEG/MPGA, OGA/OGG, WAV, and WebM." },
                  "model": { "type": "string", "enum": ["codex-transcribe", "gpt-4o-mini-transcribe"] },
                  "language": { "type": "string", "description": "Optional ISO language code such as en or en-US." },
                  "response_format": { "type": "string", "enum": ["json", "text"], "default": "json" }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Completed transcript", "headers": { "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["text"], "properties": { "text": { "type": "string" } } } }, "text/plain": { "schema": { "type": "string" } } } },
          "400": { "description": "Invalid multipart request, field, or audio format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "API-key owner has not connected Codex auth", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "Codex reconnect required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "413": { "description": "Audio file exceeds 25 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Local admission limit or upstream transcription rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "502": { "description": "Sanitized upstream failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "504": { "description": "Transcription timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/health": {
      "get": {
        "summary": "Check the API key owner's Codex connection health",
        "description": "Authenticates with the normal bearer API key and verifies that its owner's Codex authorization can be refreshed. Credentials must be sent in the Authorization header, not in the URL.",
        "operationId": "checkUserConnectionHealth",
        "responses": {
          "200": { "description": "The API key and its owner's Codex authorization are valid", "content": { "application/json": { "schema": { "type": "object" } } } },
          "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "503": { "description": "The API key is valid but its owner must connect or reconnect Codex", "content": { "application/json": { "schema": { "type": "object" } } } }
        }
      }
    },
    "/v1/models/automatic": {
      "post": {
        "summary": "Retired: model availability is automatic for connected accounts",
        "operationId": "configureAutomaticModels",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "No Enable action is required. This former control returns 410 and never changes policy or queues verification.",
        "responses": {
          "410": {
            "description": "Control retired; discovery is built in"
          },
          "401": {
            "description": "Normal route authentication required"
          }
        },
        "deprecated": true
      }
    },
    "/api/models/automatic": {
      "post": {
        "summary": "Retired: model availability is automatic for connected accounts",
        "operationId": "configureAutomaticModelsSession",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "description": "No Enable action is required. This former control returns 410 and never changes policy or queues verification.",
        "responses": {
          "410": {
            "description": "Control retired; discovery is built in"
          },
          "401": {
            "description": "Normal route authentication required"
          }
        },
        "deprecated": true
      }
    },
    "/api/models": {
      "get": {
        "summary": "Discover published Codex model metadata without credentials",
        "description": "Read-only no-store snapshot. Before first automatic publication activation, retains the legacy verified list. Once active, only the union of currently verified explicitly publishing profiles is returned, including an empty list with no legacy fallback. Private profiles, owner/account identifiers and credentials are never exposed. GET never generates, refreshes provider metadata or schedules paid checks. Public availability is not a guarantee of another account's entitlement, quota or continuous availability.",
        "operationId": "discoverModels",
        "security": [],
        "responses": {
          "200": {
            "description": "Public model IDs and display names; at most 500 models and 262144 response bytes",
            "content": { "application/json": { "schema": {
              "type": "object", "required": ["object", "data"],
              "properties": {
                "object": { "const": "list" },
                "data": { "type": "array", "maxItems": 500, "items": {
                  "type": "object", "additionalProperties": false,
                  "required": ["id", "object", "created", "owned_by", "display_name"],
                  "properties": {
                    "id": { "type": "string", "maxLength": 180 },
                    "object": { "const": "model" },
                    "created": { "const": 0 },
                    "owned_by": { "const": "openai-codex" },
                    "display_name": { "type": "string", "maxLength": 180 }
                  }
                } }
              }
            } } }
          },
          "503": { "description": "Catalog unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/models": {
      "get": {
        "summary": "List available Codex models",
        "operationId": "listModels",
        "description": "No-store owner snapshot for explicitly enrolled owners, including safe automatic flags; GET never generates. Unenrolled owners retain the legacy verified policy with automatic.enabled:false. Without endpoint filter only models verified for both protocols are returned. Metadata candidates alone are never advertised as verified.",
        "parameters": [{ "name": "endpoint", "in": "query", "required": false, "schema": { "type": "string", "enum": ["chat.completions", "responses"] }, "description": "Return models verified for just the selected protocol." }],
        "responses": {
          "200": {
            "description": "OpenAI-compatible model list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": { "const": "list" },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "object": { "const": "model" },
                          "created": { "type": "integer" },
                          "owned_by": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/chat/completions": {
      "post": {
        "summary": "Create a chat completion",
        "description": "Set stream=true for OpenAI-compatible server-sent events ending with data: [DONE]. Native function tools are returned as message.tool_calls; streamed calls use indexed delta.tool_calls fragments and finish_reason=tool_calls.",
        "operationId": "createChatCompletion",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["messages"],
                "properties": {
                  "model": { "type": "string", "default": "gpt-5.6-sol" },
                  "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } },
                  "tools": { "type": "array", "maxItems": 128, "items": { "$ref": "#/components/schemas/ChatFunctionTool" } },
                  "tool_choice": { "$ref": "#/components/schemas/ChatToolChoice" },
                  "parallel_tool_calls": { "type": "boolean", "default": false },
                  "reasoning_effort": { "type": "string", "enum": ["low", "medium", "high", "xhigh", "max", "ultra"], "default": "medium" },
                  "stream": { "type": "boolean", "default": false }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Completion JSON or SSE stream",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } },
              "text/event-stream": {
                "schema": { "type": "string", "description": "Each data line contains an indexed ChatCompletionChunk; the final line is data: [DONE]." },
                "example": "data: {\"id\":\"chatcmpl-example\",\"object\":\"chat.completion.chunk\",\"created\":1784563200,\"model\":\"gpt-5.6-sol\",\"choices\":[{\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":0,\"id\":\"call_weather\",\"type\":\"function\",\"function\":{\"name\":\"get_weather\",\"arguments\":\"{\\\"city\\\"\"}}]},\"finish_reason\":null}]}\n\ndata: {\"id\":\"chatcmpl-example\",\"object\":\"chat.completion.chunk\",\"created\":1784563200,\"model\":\"gpt-5.6-sol\",\"choices\":[{\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\":\\\"Paris\\\"}\"}}]},\"finish_reason\":null}]}\n\ndata: {\"id\":\"chatcmpl-example\",\"object\":\"chat.completion.chunk\",\"created\":1784563200,\"model\":\"gpt-5.6-sol\",\"choices\":[{\"index\":0,\"delta\":{},\"finish_reason\":\"tool_calls\"}]}\n\ndata: [DONE]\n\n"
              }
            }
          },
          "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "400": { "description": "Invalid input, PDF format, filename or unsupported file source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "413": { "description": "JSON request exceeds 30000000 UTF-8 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "502": { "description": "Upstream failure, including rejection of unverified native PDF input; streaming failures use SSE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Upstream Codex account is cooling down; honor Retry-After", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/responses": {
      "post": {
        "summary": "Create a response",
        "description": "OpenAI Responses-style endpoint with native function tools and function_call/function_call_output items. Set stream=true to preserve typed upstream events, including response.function_call_arguments.delta/done, through response.completed.",
        "operationId": "createResponse",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["input"],
                "properties": {
                  "model": { "type": "string", "default": "gpt-5.6-sol" },
                  "input": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "oneOf": [{ "$ref": "#/components/schemas/ResponseInputItem" }, { "$ref": "#/components/schemas/ResponseFunctionCallInput" }, { "$ref": "#/components/schemas/ResponseFunctionCallOutput" }] } }] },
                  "instructions": { "type": "string" },
                  "tools": { "type": "array", "maxItems": 128, "items": { "$ref": "#/components/schemas/ResponseFunctionTool" } },
                  "tool_choice": { "$ref": "#/components/schemas/ResponseToolChoice" },
                  "parallel_tool_calls": { "type": "boolean", "default": false },
                  "reasoning": { "type": "object", "properties": { "effort": { "type": "string" } } },
                  "stream": { "type": "boolean", "default": false }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Response JSON or SSE stream",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ResponseObject" },
                "example": { "id": "resp_example", "object": "response", "status": "completed", "output": [{ "id": "fc_example", "type": "function_call", "call_id": "call_weather", "name": "get_weather", "arguments": "{\"city\":\"Paris\"}", "status": "completed" }], "output_text": "", "usage": { "input_tokens": 12, "output_tokens": 8, "total_tokens": 20 } }
              },
              "text/event-stream": {
                "schema": { "type": "string", "description": "Typed Responses events. Event JSON matches response.output_item.added, response.function_call_arguments.delta/done, and response.completed schemas." },
                "example": "event: response.output_item.added\ndata: {\"type\":\"response.output_item.added\",\"output_index\":0,\"item\":{\"id\":\"fc_example\",\"type\":\"function_call\",\"call_id\":\"call_weather\",\"name\":\"get_weather\",\"arguments\":\"\",\"status\":\"in_progress\"}}\n\nevent: response.function_call_arguments.delta\ndata: {\"type\":\"response.function_call_arguments.delta\",\"item_id\":\"fc_example\",\"output_index\":0,\"delta\":\"{\\\"city\\\":\\\"Par\"}\n\nevent: response.function_call_arguments.done\ndata: {\"type\":\"response.function_call_arguments.done\",\"item_id\":\"fc_example\",\"output_index\":0,\"arguments\":\"{\\\"city\\\":\\\"Paris\\\"}\"}\n\n"
              }
            }
          },
          "400": { "description": "Invalid input, PDF format, filename or unsupported file source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "413": { "description": "JSON request exceeds 30000000 UTF-8 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "502": { "description": "Upstream failure, including rejection of unverified native PDF input; streaming failures use SSE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Upstream Codex account is cooling down; honor Retry-After", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/images/generations": {
      "post": {
        "summary": "Generate an image, optionally using reference images",
        "description": "Without reference_images this generates from text. With one or more reference images, AuthAPI supplies them as native input_image content and forces the native image-generation edit action; it does not rewrite the prompt. Reference inputs are PNG, JPEG, or WebP data URLs; remote URLs are rejected so the upstream cannot be used as an SSRF proxy.",
        "operationId": "generateImage",
        "parameters": [{ "name": "X-Request-Id", "in": "header", "required": false, "description": "Optional canonical UUID correlation ID. Invalid or unsafe values are replaced.", "schema": { "type": "string", "format": "uuid" } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["prompt"],
                "properties": {
                  "model": { "type": "string", "default": "gpt-image-2" },
                  "prompt": { "type": "string" },
                  "reference_image": { "type": "string", "description": "One PNG, JPEG, or WebP base64 data URL." },
                  "reference_images": { "type": "array", "maxItems": 16, "items": { "type": "string" }, "description": "Up to 16 PNG, JPEG, or WebP base64 data URLs." },
                  "size": { "type": "string", "default": "1024x1024" },
                  "quality": { "type": "string", "enum": ["low", "medium", "high"], "default": "medium" },
                  "output_format": { "type": "string", "default": "png" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Base64-encoded image result", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object" } } } },
          "400": { "$ref": "#/components/responses/ImageError" },
          "401": { "$ref": "#/components/responses/ImageError" },
          "403": { "$ref": "#/components/responses/ImageError" },
          "413": { "$ref": "#/components/responses/ImageError" },
          "429": { "$ref": "#/components/responses/ImageError" },
          "500": { "$ref": "#/components/responses/ImageError" },
          "502": { "$ref": "#/components/responses/ImageError" },
          "504": { "$ref": "#/components/responses/ImageError" }
        }
      }
    },
    "/v1/images/edits": {
      "post": {
        "summary": "Generate or edit an image using reference images",
        "description": "OpenAI-compatible reference-image workflow. Send one or more image[] multipart files. PNG, JPEG, and WebP are accepted; at most 16 references and 30 MiB per request.",
        "operationId": "editImage",
        "parameters": [{ "name": "X-Request-Id", "in": "header", "required": false, "description": "Optional canonical UUID correlation ID. Invalid or unsafe values are replaced.", "schema": { "type": "string", "format": "uuid" } }],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["image", "prompt"],
                "properties": {
                  "image": { "type": "array", "maxItems": 16, "items": { "type": "string", "format": "binary" }, "description": "One or more reference images. Repeated image[] fields are supported." },
                  "model": { "type": "string", "default": "gpt-image-2" },
                  "prompt": { "type": "string" },
                  "size": { "type": "string" },
                  "quality": { "type": "string", "enum": ["low", "medium", "high"] },
                  "output_format": { "type": "string", "enum": ["png", "jpeg", "webp"], "default": "png" }
                }
              }
            },
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["prompt"],
                "anyOf": [
                  { "required": ["images"] },
                  { "required": ["reference_image"] },
                  { "required": ["reference_images"] }
                ],
                "properties": {
                  "model": { "type": "string", "default": "gpt-image-2" },
                  "prompt": { "type": "string" },
                  "images": { "type": "array", "maxItems": 16, "items": { "type": "object", "required": ["image_url"], "properties": { "image_url": { "type": "string", "description": "PNG, JPEG, or WebP base64 data URL." } }, "additionalProperties": false } },
                  "reference_image": { "type": "string" },
                  "reference_images": { "type": "array", "maxItems": 16, "items": { "type": "string" } },
                  "size": { "type": "string" },
                  "quality": { "type": "string", "enum": ["low", "medium", "high"] },
                  "output_format": { "type": "string", "enum": ["png", "jpeg", "webp"] }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Base64-encoded edited image", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object" } } } },
          "400": { "$ref": "#/components/responses/ImageError" },
          "401": { "$ref": "#/components/responses/ImageError" },
          "403": { "$ref": "#/components/responses/ImageError" },
          "413": { "$ref": "#/components/responses/ImageError" },
          "429": { "$ref": "#/components/responses/ImageError" },
          "500": { "$ref": "#/components/responses/ImageError" },
          "502": { "$ref": "#/components/responses/ImageError" },
          "504": { "$ref": "#/components/responses/ImageError" }
        }
      }
    }
  }
}
