{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/opper/main/json-schema/opper-chat-request-schema.json",
  "title": "ChatRequest",
  "x-generated": "2026-10-15",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/opper-openapi.json#/components/schemas/ChatRequest",
  "properties": {
    "cache_control": {
      "description": "Opt in to automatic prompt caching for Anthropic-family models: {\"type\":\"ephemeral\"} (optionally \"ttl\":\"1h\"). Places one moving cache breakpoint on the largest cacheable prefix. Also settable per content part for precise placement. Caching is off unless set; no-op on providers with automatic server-side caching (OpenAI",
      "type": "object"
    },
    "custom_model_credentials": {
      "properties": {
        "api_key": {
          "type": "string"
        },
        "base_url": {
          "type": "string"
        },
        "extra": {
          "type": "object"
        },
        "identifier": {
          "type": "string"
        },
        "url": {
          "type": "string"
        }
      },
      "required": [
        "identifier",
        "api_key"
      ],
      "type": "object"
    },
    "max_completion_tokens": {
      "type": "integer"
    },
    "max_tokens": {
      "type": "integer"
    },
    "messages": {
      "items": {
        "properties": {
          "content": {
            "description": "Any value"
          },
          "name": {
            "type": "string"
          },
          "role": {
            "type": "string"
          },
          "tool_call_id": {
            "type": "string"
          },
          "tool_calls": {
            "items": {
              "properties": {
                "extra_content": {
                  "description": "Any value"
                },
                "function": {
                  "properties": {
                    "arguments": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "name",
                    "arguments"
                  ],
                  "type": "object"
                },
                "id": {
                  "type": "string"
                },
                "thought_signature": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "type",
                "function"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "role",
          "content"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "metadata": {
      "type": "object"
    },
    "model": {
      "type": "string"
    },
    "models": {
      "description": "Fallback models tried in order when the model before them fails for any reason (provider error; rate limit; timeout; a member blocked by one of your rules). Same OpenRouter shape: send the primary in model and the rest here; or omit model and the first entry is the primary. Each entry is any model string: a bare pooled name; a provider/model id; an org alias. Not allowed together with a dynamic/<name> route. At most 10 entries. Which model answered is in meta.routing.served and the X-Opper-Served-Model header; the model field still echoes what you sent.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "output_schema": {
      "type": "object"
    },
    "prompt_cache_key": {
      "description": "OpenAI cache-routing key: a stable name for the prompt prefix this request shares with others (e.g. a document id for a fan-out over one context). Forwarded to OpenAI and used to keep requests that share the key on the same cache replica at providers with per-replica prompt caches.",
      "type": "string"
    },
    "reasoning_effort": {
      "type": "string"
    },
    "response_format": {
      "type": "object"
    },
    "service_tier": {
      "description": "Processing tier. flex: discounted and slower; when the provider has no flex capacity the call fails with 429 instead of running at the full price. priority (alias fast): faster at a premium; falls back to the default tier. ultrafast: fastest; falls back to priority then default. default and auto: the provider default. A model without an endpoint for the requested tier runs at the default tier. The tier that ran is in the X-Opper-Served-Service-Tier header.",
      "type": "string"
    },
    "stop": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "stream": {
      "type": "boolean"
    },
    "stream_options": {
      "properties": {
        "include_usage": {
          "type": "boolean"
        }
      },
      "type": "object"
    },
    "temperature": {
      "type": "number"
    },
    "tool_choice": {
      "description": "Any value"
    },
    "tools": {
      "items": {
        "properties": {
          "aspect_ratio": {
            "type": "string"
          },
          "function": {
            "properties": {
              "description": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "parameters": {
                "type": "object"
              }
            },
            "required": [
              "name"
            ],
            "type": "object"
          },
          "model": {
            "type": "string"
          },
          "quality": {
            "type": "string"
          },
          "size": {
            "type": "string"
          },
          "style": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        },
        "required": [
          "type"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "top_p": {
      "type": "number"
    }
  },
  "required": [
    "messages"
  ],
  "type": "object"
}