POST /api/v1/chat/completionsReturns full JSON by default. When `stream=true`, returns an SSE stream. If `modalities: ["image"]` is included, image results are in `choices[].message.images`.
Back to Chat endpoint list Request parameters Field Type Required Description
modelstring Yes GlobalRouter model ID.
messagesarray Yes Message array, with each item containing role and content.
providerstring No 指定 GlobalRouter Provider 偏好；这里是 GR 的 provider string，不是 OpenRouter 官方 provider object。
streamboolean No Whether to use SSE streaming output.
stream_optionsobject No Streaming options, such as include_usage.
temperaturenumber No 采样温度，范围 0 到 2。
top_pnumber No 核采样概率，范围 0 到 1。
max_completion_tokensinteger No Maximum output token count.
max_tokensinteger No 最大输出 token 数，兼容旧请求；新请求优先使用 max_completion_tokens。
reasoningobject No 推理models配置，例如 effort、summary 或 provider 支持的推理选项。
reasoning_effortstring No reasoning.effort 的快捷字段；不能与 reasoning.effort 设置为不同值。
toolsobject[] No Tool definitions.
tool_choicestring | object No Tool selection strategy, such as auto or a specific tool.
response_formatobject No Structured output configuration.
stopstring | string[] No Stop sequences.
userstring No Application-side user identifier.
modalitiesstring[] No Triggers image output when image is included.
image_configobject No Image output configuration.
_routerobject No Routing metadata, such as provider or routing.
Response fields Field Type Required Description
idstring Yes Chat completion ID。
choicesobject[] Yes Generated result list.
choices[].messageobject No Assistant message returned for non-streaming responses.
choices[].deltaobject No Incremental content in streaming chunks.
usageobject No Usage summary for tokens or image tasks.
openrouter_metadataobject Yes Metadata such as provider and generation_id.
Notes The Chat API requires an API key with the chat scope; image output also uses task capability and the corresponding model permissions. `provider` 是 GlobalRouter 的 provider string；OpenRouter 官方 Chat Completion 文档中的同名字段是 object。 POST /api/v1/chat/completionsCopy curl "https://api.globalrouter.com/api/v1/chat/completions" \
-H "Authorization: Bearer $GR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4-pro",
"messages": [
{ "role": "user", "content": "Explain GlobalRouter's value in one sentence." }
],
"provider": "deepseek",
"stream": false,
"stream_options": { "include_usage": true },
"temperature": 0.7,
"top_p": 0.9,
"max_completion_tokens": 256,
"reasoning": { "effort": "medium" },
"tools": [
{
"type": "function",
"function": {
"name": "lookup_model",
"description": "Look up model information",
"parameters": {
"type": "object",
"properties": { "model": { "type": "string" } },
"required": ["model"]
}
}
}
],
"tool_choice": "auto",
"response_format": { "type": "json_object" },
"stop": ["###"],
"user": "user_123",
"_router": {
"route": "balanced",
"metadata": { "project": "docs-demo" }
}
}'POST /api/v1/chat/completionsCopy curl "https://api.globalrouter.com/api/v1/chat/completions" \
-H "Authorization: Bearer $GR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kimi-k3",
"messages": [
{
"role": "user",
"content": "请用要点总结 GlobalRouter 接入多模型 provider 时的上线检查清单。"
}
],
"provider": "moonshot",
"stream": false,
"max_completion_tokens": 512,
"reasoning": {
"effort": "medium"
}
}'POST /api/v1/chat/completionsCopy curl "https://api.globalrouter.com/api/v1/chat/completions" \
-H "Authorization: Bearer $GR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kimi-k2.7-code",
"messages": [
{
"role": "user",
"content": "Review this TypeScript function and point out one likely edge case."
}
],
"provider": "moonshot",
"stream": false,
"max_completion_tokens": 512,
"reasoning": {
"effort": "medium"
}
}'POST /api/v1/chat/completionsCopy curl "https://api.globalrouter.com/api/v1/chat/completions" \
-H "Authorization: Bearer $GR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kimi-k2.7-code-highspeed",
"messages": [
{
"role": "user",
"content": "快速给出一个 Python asyncpg upsert 参数检查 checklist。"
}
],
"provider": "moonshot",
"stream": false,
"max_completion_tokens": 512,
"reasoning": {
"effort": "low"
}
}'POST /api/v1/chat/completionsCopy curl "https://api.globalrouter.com/api/v1/chat/completions" \
-H "Authorization: Bearer $GR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kimi-k2.6",
"messages": [
{
"role": "user",
"content": "用三句话解释为什么模型 catalog 和 provider relation 需要解耦。"
}
],
"provider": "moonshot",
"stream": false,
"max_completion_tokens": 512,
"reasoning": {
"effort": "low"
}
}'POST /api/v1/chat/completionsCopy curl "https://api.globalrouter.com/api/v1/chat/completions" \
-H "Authorization: Bearer $GR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4-pro",
"messages": [
{
"role": "user",
"content": "推理一下：为什么同一个 model_id 可以绑定多个 provider relation？"
}
],
"provider": "deepseek",
"stream": false,
"max_completion_tokens": 512,
"reasoning": {
"effort": "medium"
}
}'POST /api/v1/chat/completionsCopy curl "https://api.globalrouter.com/api/v1/chat/completions" \
-H "Authorization: Bearer $GR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4-flash",
"messages": [
{
"role": "user",
"content": "快速列出一次线上模型同步脚本 apply 前的风险检查。"
}
],
"provider": "deepseek",
"stream": false,
"max_completion_tokens": 512,
"reasoning": {
"effort": "low"
}
}'POST /api/v1/chat/completionsCopy curl "https://api.globalrouter.com/api/v1/chat/completions" \
-H "Authorization: Bearer $GR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5.2",
"messages": [
{
"role": "user",
"content": "请把这段发布说明改写成面向运维同学的 checklist。"
}
],
"provider": "zhipu",
"stream": false,
"max_completion_tokens": 512,
"reasoning": {
"effort": "medium"
}
}'POST /api/v1/chat/completionsCopy curl "https://api.globalrouter.com/api/v1/chat/completions" \
-H "Authorization: Bearer $GR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5.1",
"messages": [
{
"role": "user",
"content": "请生成一个简短 SQL 执行前置检查模板，避免包含任何真实密钥。"
}
],
"provider": "zhipu",
"stream": false,
"max_completion_tokens": 512,
"reasoning": {
"effort": "medium"
}
}'POST /api/v1/chat/completionsCopy curl "https://api.globalrouter.com/api/v1/chat/completions" \
-H "Authorization: Bearer $GR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5v-turbo",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "请说明这张参考图适合作为什么类型的产品视觉素材。"
},
{
"type": "image_url",
"image_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_5_imageToimage.png"
}
}
]
}
],
"provider": "zhipu",
"stream": false,
"max_completion_tokens": 512,
"reasoning": {
"effort": "low"
}
}'200 Response Copy {
"id": "chatcmpl_123",
"object": "chat.completion",
"model": "deepseek-v4-pro",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "GlobalRouter 用一个接口聚合主流模型，并让成本和可靠性交付更可见。"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 18,
"completion_tokens": 26,
"total_tokens": 44
},
"openrouter_metadata": {
"provider": "deepseek",
"generation_id": "req_123"
}
}