Choose protocols and model capabilities

Start with the task, then confirm the model ID, request protocol, and required capabilities with your deployment administrator. The model list discovers models visible to the current key; appearing in that list does not mean a model supports every endpoint or parameter below.

Choose an endpoint by task

Task	Starting point	Confirm
Text answers and multi-turn chat	Chat Completions and conversations	Message roles, context limits, and history management
An application already using Responses	Responses	Responses support and specific tool capabilities on the channel
Display text incrementally	Streaming	SSE format, completion markers, and proxy buffering
Call your own functions	Tool calling	Tool arguments, result correlation, and application execution policy
Return data with a fixed structure	Structured output	JSON / JSON Schema support and client validation
Answer questions about an image	Vision	Whether the chat model accepts images and supported input formats
Generate or edit images	Image generation and editing	Dedicated image models, editing support, and output formats
Generate speech	Speech synthesis	Voices, audio formats, and languages
Transcribe or translate audio	Transcription and translation	Upload limits and model support for each operation
Create videos and wait for results	Video tasks	Available channels, task lifecycle, and downloads
Semantic search and knowledge-base answers	Embeddings, Rerank, and RAG	Separate embedding, rerank, and chat models, plus compatible encoding

This table points to existing guides; it is not a provider model capability catalog. Words such as chat or vision in a model name cannot replace capability verification.

Switching between Chat Completions and Responses

Part	Chat Completions	Responses
Typical input	`messages`	`input`, optionally with `instructions`
Typical output	`choices[].message`	`output` items; SDKs offer text extraction helpers
Text delta	`choices[].delta.content`	`response.output_text.delta`
Completion check	Inspect `finish_reason`	Inspect `status` or the final event

When switching endpoints, update the request body, tool result structure, response reader, and stream completion checks together. Replacing /chat/completions with /responses in the URL is insufficient. Do not assume equivalent conversion is available for every channel. Confirm server-managed conversations, built-in tools, and resource management separately; these examples do not promise those features on every deployment.

Minimal validation sequence

Confirm the actual API address using API basics, then list models with the same key.
Send a minimal request from the matching guide without combining tools, images, and structured output immediately.
Check business completion and output content, not only HTTP 200.
Enable capabilities one at a time. Keep request times, model IDs, and non-sensitive error details to compare with deployment logs.
Validate interrupted streams, failures, and retry policy. Automatic client retries are not a capability probe.

Common misconceptions

The SDK has a method, so the gateway must support it. SDKs can expose endpoints outside this site’s scope. Check the API overview and your deployment.
An image generation model must support editing. Image input, editing, and generation are separate capabilities to verify.
Parsable JSON meets the business requirements. Validate field types, values, and business constraints, and handle refusals and incomplete responses.
The top search result is sufficient to answer. Check relevance, access, and evidence supporting the answer; see RAG.

Use errors and retries to diagnose failed requests. Arbitrarily changing models can conceal protocol or parameter incompatibilities.

Native protocols and streaming tools

Claude Messages and Gemini generateContent provide dedicated native protocol examples. For argument assembly and function execution, see Chat / Responses streaming tools. Runnable native SSE and tool loops for Claude and Gemini include completion validation and signature preservation.

Look up one model

When you know the model ID, run examples/model.py. It checks business errors inside HTTP 200 and exits unsuccessfully for missing or unavailable models without printing the full error payload. Install the Python example dependencies and configure the address, token, and model for the same deployment. See model retrieval for path encoding limits.

export API_BASE_URL="https://gateway.example.com/v1"
export API_KEY="YOUR_API_KEY"
export API_MODEL="YOUR_MODEL_ID"
.venv/bin/python examples/model.py

import os
from urllib.parse import quote
from openai import OpenAI, APIConnectionError, APIStatusError

model = os.environ["API_MODEL"]
if not model.strip():
    raise SystemExit("API_MODEL must not be empty.")
with OpenAI(base_url=os.environ["API_BASE_URL"].rstrip("/"),
            api_key=os.environ["API_KEY"], timeout=60.0, max_retries=0) as client:
    try:
        result = client.get(f"/models/{quote(model, safe='')}", cast_to=dict)
        # This gateway can return a model_not_found error inside HTTP 200.
        if not isinstance(result, dict) or result.get("error"):
            raise ValueError("Model lookup failed.")
        if result.get("id") != model or result.get("object") != "model":
            raise ValueError("Unexpected model metadata.")
        print(result["id"])
    except APIStatusError as error:
        raise SystemExit(f"Request failed (HTTP {error.status_code}). Check model visibility and URL encoding.")
    except APIConnectionError:
        raise SystemExit("Connection failed. No automatic retry.")
    except (ValueError, TypeError, AttributeError):
        raise SystemExit("Model lookup failed. Check the model list with the same key.")

阅读中文 Model routing · Rate limits · Observability · AI SDK Prompt caching · Reasoning models · Context management

Native Gemini tools

Confirm each native tool on the selected channel: googleSearch, urlContext, codeExecution. Model discovery, function-calling support, and tool-field acceptance do not prove built-in execution. Check grounding, URL status, or execution-result evidence separately.

Getting started

Integration guides

Application guides

Multimodal guides

Retrieval and reranking

Production and troubleshooting

Additional protocols and tasks

API reference

Choose protocols and model capabilities

Choose an endpoint by task

Switching between Chat Completions and Responses

Minimal validation sequence

Common misconceptions

Native protocols and streaming tools

Look up one model

Native Gemini tools

​Choose an endpoint by task

​Switching between Chat Completions and Responses

​Minimal validation sequence

​Common misconceptions

​Native protocols and streaming tools

​Look up one model

​Native Gemini tools

Choose an endpoint by task

Switching between Chat Completions and Responses

Minimal validation sequence

Common misconceptions

Native protocols and streaming tools

Look up one model

Native Gemini tools