覆盖范围

• Create Response（Responses API）

• Chat Completions

• Prompt Cache 会话粘连（x-grok-conv-id，仅 Chat）

• 推理参数（reasoning / reasoning_effort）

A. Responses / Create Response

请求协议

HTTPS

Header

参数名	类型	必填	描述
Content-Type	string	是	application/json
Authorization	string	是	Bearer ${your_AK}

请求 URL

Endpoint 接口模式

POST https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/responses

融合接口模式

POST https://genaiapi.cloudsway.net/v1/responses

请求 Body 参数

参数名	二级参数	三级参数	类型	必填	描述
input	-	-	string | array	是	输入内容；
model	-	-	string	是	模型名；
instructions	-	-	string | null	否	系统提示；勿与 previous_response_id 同用
previous_response_id	-	-	string | null	否	续写上一轮 response
max_output_tokens	-	-	int | null	否	含输出 + 推理的 token 上限
stream	-	-	bool | null	否	SSE 流式输出
temperature	-	-	number | null	否	采样温度，范围 0–2；原厂在 2 时可能异常
top_p	-	-	number | null	否	核采样
reasoning	-	-	object	否	推荐写法，含 effort / summary 等
	effort	-	string | null	否	low / medium / high / xhigh（视模型）
	summary	-	string | null	否	auto / concise / detailed（兼容字段）
	generate_summary	-	string | null	否	兼容字段，建议用 summary
include	-	-	array | null	否	附加输出，如 reasoning.encrypted_content
prompt_cache_key	-	-	string | null	否	缓存路由键
tools	-	-	array | null	否	function / web search 等；function 透传，web_search* 会被平台剥离
	type	-	string	否	工具类型，如 function
	name	-	string	否	函数名（function 工具）
	description	-	string	否	函数描述
	parameters	-	object	否	JSON Schema 参数定义
tool_choice	-	-	string | object	否	工具选择策略
parallel_tool_calls	-	-	bool | null	否	是否并行工具调用
text	-	-	object	否	输出格式配置
	format	-	object	否	输出格式
		type	string	否	如 text / json_schema
		schema	object	否	JSON Schema（type=json_schema 时）
user	-	-	string | null	否	终端用户标识
top_logprobs	-	-	int | null	否	0–8；grok-4.20+ 可能忽略

请求示例

非流式（Endpoint 接口模式）

curl -X POST "https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${your_AK}" \
  -d '{
    "model": "MaaS_Gr_4.6_20260812",
    "input": "Explain prompt caching in one paragraph.",
    "instructions": "You are Grok, a helpful AI assistant.",
    "max_output_tokens": 1024,
    "reasoning": {
      "effort": "medium",
      "summary": "detailed"
    },
    "store": true
  }'

非流式（融合接口模式）

curl -X POST "https://genaiapi.cloudsway.net/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${your_AK}" \
  -d '{
    "model": "MaaS_Gr_4.6_20260812",
    "input": "Explain prompt caching in one paragraph.",
    "reasoning": { "effort": "high" }
  }'

流式

curl -N -X POST "https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${your_AK}" \
  -d '{
    "model": "MaaS_Gr_4.6_20260812",
    "input": "Write a haiku about caching.",
    "stream": true,
    "reasoning": { "effort": "low" }
  }'

带 Function Tool

curl -X POST "https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${your_AK}" \
  -d '{
    "model": "MaaS_Gr_4.6_20260812",
    "input": "What is the weather in Tokyo?",
    "tools": [
      {
        "type": "function",
        "name": "get_weather",
        "description": "Get current weather",
        "parameters": {
          "type": "object",
          "properties": {
            "location": { "type": "string" }
          },
          "required": ["location"]
        }
      }
    ],
    "tool_choice": "auto"
  }'

响应示例

非流式

{
  "id": "resp_abc123xyz",
  "object": "response",
  "created_at": 1755676800,
  "model": "MaaS_Gr_4.6_20260812",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "id": "msg_001",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Prompt caching stores KV pairs from unchanged prompt prefixes..."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 128,
    "output_tokens": 64,
    "total_tokens": 192,
    "input_tokens_details": {
      "cached_tokens": 96
    }
  }
}

流式（SSE 片段示例）

data: {"type":"response.created","response":{"id":"resp_abc123xyz","status":"in_progress"}}

data: {"type":"response.output_text.delta","delta":"Prompt caching"}

data: {"type":"response.completed","response":{"id":"resp_abc123xyz","status":"completed","usage":{"input_tokens":128,"output_tokens":64,"total_tokens":192,"input_tokens_details":{"cached_tokens":96}}}}

---

B. Chat Completions

请求协议

HTTPS

Header

参数名	类型	必填	描述
Content-Type	string	是	application/json
Authorization	string	是	Bearer ${your_AK}
x-grok-conv-id	string	否	Prompt Cache 会话粘连 ID；平台从 HTTP 头提取并透传至上游（仅 Chat Completions）

请求 URL

Endpoint 接口模式

POST https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/chat/completions

融合接口模式

POST https://genaiapi.cloudsway.net/v1/chat/completions

请求 Body 参数

参数名	二级参数	三级参数	四级参数	类型	必填	描述
model	-	-	-	string	是	模型名；
messages	-	-	-	array	是	对话消息（text / image）
	role	-	-	string	是	system / user / assistant / tool
	content	-	-	string | array	是	文本或多模态内容
		type	-	string	否	多模态类型，如 text / image_url
		text	-	string	否	文本片段
		image_url	url	string	否	图片 URL
max_completion_tokens	-	-	-	int | null	否	可见输出 token 上限（不含推理 / 工具）；Grok 保留此字段
max_tokens	-	-	-	int | null	否	已废弃，建议用 max_completion_tokens
stream	-	-	-	bool | null	否	SSE 流式
stream_options	-	-	-	object	否	流式选项
	include_usage	-	-	bool	否	流结束前带 usage；未设时默认 true
temperature	-	-	-	number | null	否	采样温度 0–2
top_p	-	-	-	number | null	否	核采样
n	-	-	-	int | null	否	生成条数
user	-	-	-	string | null	否	终端用户标识
prompt_cache_key	-	-	-	string | null	否	缓存粘滞路由
reasoning_effort	-	-	-	string | null	否	推理强度 low / medium / high / xhigh
tools	-	-	-	array | null	否	函数工具，最多 128
	type	-	-	string	否	固定 function
	function	name	-	string	否	函数名
	function	description	-	string	否	函数描述
	function	parameters	-	object	否	JSON Schema
tool_choice	-	-	-	string | object	否	none / auto / required / 指定 function
parallel_tool_calls	-	-	-	bool | null	否	是否并行工具调用
response_format	-	-	-	object	否	输出格式
	type	-	-	string	否	text / json_object / json_schema
	json_schema	-	-	object	否	JSON Schema 定义
frequency_penalty	-	-	-	number | null	否	-2\~2；推理模型不支持
presence_penalty	-	-	-	number | null	否	-2\~2；grok-3 / 推理模型不支持
stop	-	-	-	array | null	否	最多 4 个停止串；推理模型不支持
deferred	-	-	-	bool | null	否	true 时返回 request_id，异步取结果（Grok 扩展）
reasoning_split	-	-	-	bool | null	否	推理拆分（Grok 扩展，LlmChatCompletionRequest）
tool_stream	-	-	-	bool | null	否	工具流式（Grok 扩展）

请求示例

Prompt Cache — Turn 1（建立缓存，Endpoint 接口模式）

curl -X POST "https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${your_AK}" \
  -H "x-grok-conv-id: conv_abc123" \
  -d '{
    "model": "MaaS_Gr_4.6_20260812",
    "messages": [
      {"role": "system", "content": "You are Grok, a helpful and truthful AI assistant built by xAI."},
      {"role": "user", "content": "What is prompt caching?"},
      {"role": "assistant", "content": "Prompt caching stores KV pairs from unchanged prompt prefixes so they can be reused on subsequent requests. This makes responses faster and cheaper."}
    ]
  }'

Prompt Cache — Turn 2（Cache HIT，前缀不变、追加新消息）

curl -X POST "https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${your_AK}" \
  -H "x-grok-conv-id: conv_abc123" \
  -d '{
    "model": "MaaS_Gr_4.6_20260812",
    "messages": [
      {"role": "system", "content": "You are Grok, a helpful and truthful AI assistant built by xAI."},
      {"role": "user", "content": "What is prompt caching?"},
      {"role": "assistant", "content": "Prompt caching stores KV pairs from unchanged prompt prefixes so they can be reused on subsequent requests. This makes responses faster and cheaper."},
      {"role": "user", "content": "Show me a code example."}
    ]
  }'

融合接口模式 + 推理 + 流式

curl -N -X POST "https://genaiapi.cloudsway.net/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${your_AK}" \
  -d '{
    "model": "MaaS_Gr_4.6_20260812",
    "messages": [
      {"role": "user", "content": "Solve: 17 * 23"}
    ],
    "reasoning_effort": "high",
    "max_completion_tokens": 2048,
    "stream": true
  }'

响应示例

非流式

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1755676800,
  "model": "MaaS_Gr_4.6_20260812",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Here is a simple Python example of prompt caching concepts:\n\n```python\n# Turn 1: establish prefix\nmessages = [system_msg, user_msg_1]\n# Turn 2: append new turn, prefix unchanged\nmessages.append(assistant_msg_1)\nmessages.append(user_msg_2)\n```"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 256,
    "completion_tokens": 128,
    "total_tokens": 384,
    "prompt_tokens_details": {
      "cached_tokens": 192
    }
  }
}

流式（SSE 片段示例）

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"Here"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" is"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":256,"completion_tokens":128,"total_tokens":384,"prompt_tokens_details":{"cached_tokens":192}}}

data: [DONE]