For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://modelgates.ai/docs/_mcp/server.
Chat - Python SDK
The Python SDK and docs are currently in beta. Report issues on GitHub.
Overview
Available Operations
- send - Create a chat completion
send
Sends a request for a model response for the given chat conversation. Supports both streaming and non-streaming modes.
Example Usage
python
from modelgates import ModelGatesimport os with ModelGates( http_referer="<value>", x_open_router_title="<value>", x_open_router_categories="<value>", api_key=os.getenv("MODELGATES_API_KEY", ""),) as open_router: res = open_router.chat.send(messages=[ { "content": "You are a helpful assistant.", "role": "system", }, { "content": "What is the capital of France?", "role": "user", }, ], x_open_router_experimental_metadata="enabled", max_tokens=150, model="openai/gpt-4", stream=False, temperature=0.7) with res as event_stream: for event in event_stream: # handle event print(event, flush=True)Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
messages | List[components.ChatMessages] | :heavy_check_mark: | List of messages for the conversation | [{"content": "Hello!","role": "user"}] |
http_referer | Optional[str] | :heavy_minus_sign: | The app identifier should be your app's URL and is used as the primary identifier for rankings. This is used to track API usage per application. | |
x_open_router_title | Optional[str] | :heavy_minus_sign: | The app display name allows you to customize how your app appears in ModelGates's dashboard. | |
x_open_router_categories | Optional[str] | :heavy_minus_sign: | Comma-separated list of app categories (e.g. "cli-agent,cloud-agent"). Used for marketplace rankings. | |
x_open_router_experimental_metadata | Optional[components.MetadataLevel] | :heavy_minus_sign: | Opt-in to surface routing metadata on the response under modelgates_metadata. Defaults to disabled. | enabled |
cache_control | Optional[components.AnthropicCacheControlDirective] | :heavy_minus_sign: | Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. Currently supported for Anthropic Claude models. | {"type": "ephemeral"} |
debug | Optional[components.ChatDebugOptions] | :heavy_minus_sign: | Debug options for inspecting request transformations (streaming only) | {"echo_upstream_body": true} |
frequency_penalty | OptionalNullable[float] | :heavy_minus_sign: | Frequency penalty (-2.0 to 2.0) | 0 |
image_config | Dict[str, components.ImageConfig] | :heavy_minus_sign: | Provider-specific image configuration options. Keys and values vary by model/provider. See https://modelgates.ai/docs/guides/overview/multimodal/image-generation for more details. | {"aspect_ratio": "16:9","quality": "high"} |
logit_bias | Dict[str, float] | :heavy_minus_sign: | Token logit bias adjustments | {"50256": -100} |
logprobs | OptionalNullable[bool] | :heavy_minus_sign: | Return log probabilities | false |
max_completion_tokens | OptionalNullable[int] | :heavy_minus_sign: | Maximum tokens in completion | 100 |
max_tokens | OptionalNullable[int] | :heavy_minus_sign: | Maximum tokens (deprecated, use max_completion_tokens). Note: some providers enforce a minimum of 16. | 100 |
metadata | Dict[str, str] | :heavy_minus_sign: | Key-value pairs for additional object information (max 16 pairs, 64 char keys, 512 char values) | {"session_id": "session-456","user_id": "user-123"} |
modalities | List[components.Modality] | :heavy_minus_sign: | Output modalities for the response. Supported values are "text", "image", and "audio". | [ "text", "image" ] |
model | Optional[str] | :heavy_minus_sign: | Model to use for completion | openai/gpt-4 |
models | List[str] | :heavy_minus_sign: | Models to use for completion | [ "openai/gpt-4", "openai/gpt-4o" ] |
parallel_tool_calls | OptionalNullable[bool] | :heavy_minus_sign: | Whether to enable parallel function calling during tool use. When true, the model may generate multiple tool calls in a single response. | true |
plugins | List[components.ChatRequestPlugin] | :heavy_minus_sign: | Plugins you want to enable for this request, including their settings. | |
presence_penalty | OptionalNullable[float] | :heavy_minus_sign: | Presence penalty (-2.0 to 2.0) | 0 |
provider | OptionalNullable[components.ProviderPreferences] | :heavy_minus_sign: | When multiple model providers are available, optionally indicate your routing preference. | {"allow_fallbacks": true} |
reasoning | Optional[components.Reasoning] | :heavy_minus_sign: | Configuration options for reasoning models | {"effort": "medium","summary": "concise"} |
response_format | Optional[components.ResponseFormat] | :heavy_minus_sign: | Response format configuration | {"type": "json_object"} |
seed | OptionalNullable[int] | :heavy_minus_sign: | Random seed for deterministic outputs | 42 |
service_tier | OptionalNullable[components.ChatRequestServiceTier] | :heavy_minus_sign: | The service tier to use for processing this request. | auto |
session_id | Optional[str] | :heavy_minus_sign: | A unique identifier for grouping related requests (e.g., a conversation or agent workflow) for observability. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters. | |
stop | OptionalNullable[components.Stop] | :heavy_minus_sign: | Stop sequences (up to 4) | [ "" ] |
stream | Optional[bool] | :heavy_minus_sign: | Enable streaming response | false |
stream_options | OptionalNullable[components.ChatStreamOptions] | :heavy_minus_sign: | Streaming configuration options | {"include_usage": true} |
temperature | OptionalNullable[float] | :heavy_minus_sign: | Sampling temperature (0-2) | 0.7 |
tool_choice | Optional[components.ChatToolChoice] | :heavy_minus_sign: | Tool choice configuration | auto |
tools | List[components.ChatFunctionTool] | :heavy_minus_sign: | Available tools for function calling | [{"function": {"description": "Get weather","name": "get_weather"},"type": "function" } ] |
top_logprobs | OptionalNullable[int] | :heavy_minus_sign: | Number of top log probabilities to return (0-20) | 5 |
top_p | OptionalNullable[float] | :heavy_minus_sign: | Nucleus sampling parameter (0-1) | 1 |
trace | Optional[components.TraceConfig] | :heavy_minus_sign: | Metadata for observability and tracing. Known keys (trace_id, trace_name, span_name, generation_name, parent_span_id) have special handling. Additional keys are passed through as custom metadata to configured broadcast destinations. | {"trace_id": "trace-abc123","trace_name": "my-app-trace"} |
user | Optional[str] | :heavy_minus_sign: | Unique user identifier | user-123 |
retries | Optional[utils.RetryConfig] | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. |
Response
operations.SendChatCompletionRequestResponse
Errors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.BadRequestResponseError | 400 | application/json |
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.PaymentRequiredResponseError | 402 | application/json |
| errors.ForbiddenResponseError | 403 | application/json |
| errors.NotFoundResponseError | 404 | application/json |
| errors.RequestTimeoutResponseError | 408 | application/json |
| errors.PayloadTooLargeResponseError | 413 | application/json |
| errors.UnprocessableEntityResponseError | 422 | application/json |
| errors.TooManyRequestsResponseError | 429 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.BadGatewayResponseError | 502 | application/json |
| errors.ServiceUnavailableResponseError | 503 | application/json |
| errors.EdgeNetworkTimeoutResponseError | 524 | application/json |
| errors.ProviderOverloadedResponseError | 529 | application/json |
| errors.ModelGatesDefaultError | 4XX, 5XX | */* |