主题
GPT 对话补全
POST
/v1/chat/completions
本接口兼容 OpenAI Chat Completions 对话格式:按消息顺序发送文字,或在同一条消息中附上图片、PDF 文件和提示词,即可获取 GPT 生成的文本回答。具体可用能力取决于所选模型。
- 纯文本对话:在
messages中发送文字,适用于问答、解释和摘要。 - 图片理解:将文字和图片放在同一条
user消息中。本地 JPEG 图片可编码为 Base64 data URI;使用前请确认所选模型支持图片输入。 - PDF 与图片核对:将本地 PDF、JPEG 图片和提示词编码后放在同一条
user消息中;订单核对示例见下方场景三。 - 非流式响应:设置
stream: false后,接口返回完整 JSON;回答位于choices[0].message.content,usage提供 token 用量。
适用模型
GPT 全系模型:gpt-astra、gpt-sol、gpt-terra、gpt-luna
Claude 全系模型:claude-sonnet、claude-opus
价格
对话模型按 token 计费,价格随模型和API 密钥分组变化。请查看 大语言模型价格。
认证
使用 ClawPower API Key 进行 Bearer 认证,并在请求头中传入:
Authorization: Bearer <CLAWPOWER_API_KEY>类型 HTTP (bearer)
还没有 API Key?先创建API 密钥,并选择模型支持的分组。
请求体
application/json
填写所选 GPT 或 Claude 对话模型的具体模型 ID,须与API 密钥分组匹配;可用系列见上方适用模型。图片和 PDF 输入能力需按具体模型核对。
按顺序排列的对话消息。图片总结和纯文本调用都至少包含一条 user 消息。需要固定回答要求时,可在 user 消息前加入 system 消息。继续追问时,按顺序重新传入需要参考的历史 user、assistant 消息,再追加新的 user 消息;需要看原图时也要重新附上图片。
最小项数
1可选采样温度;是否支持此参数应按所选模型能力判断。
最小值
0最大值
2可选核采样参数。是否适用于所选 GPT 模型须按该模型能力判断。
最小值
0最大值
1可选输出 token 上限;部分模型可能使用不同的输出上限字段。
最小值
1可选重复惩罚参数。
最小值
-2最大值
2可选新话题倾向参数。
最小值
-2最大值
2可选停止序列;部分模型可能不支持。
最大项数
4可选随机种子;可复现性不作保证。
可选候选回答数量;默认请求只读取第一项。
最小值
1设为 true 时请求流式返回;需由客户端逐段读取 SSE。
默认
false可选输出格式约束;JSON 或 Schema 模式需所选模型支持。
可选工具声明;需所选模型支持工具调用。
可选工具选择策略或指定工具;与 tools 一起使用。
可选对数概率输出开关。
可选每个 token 返回的高概率候选数量。
最小值
0最大值
20可选 token 偏置映射。
可选终端用户标识。
响应
成功返回对话结果。示例值仅说明字段位置。
JSON "id": "string", "object": "string", "created": 0, "model": "string", "choices": [ { "index": 0, "message": { "role": "user", "content": "string" }, "finish_reason": "string" } ], "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0, "prompt_tokens_details": { "cached_tokens": 0 }, "completion_tokens_details": { "reasoning_tokens": 0 } }, "system_fingerprint": "string"
{
}
场景一:只发送文字
例如,你想让 GPT 用三句话解释什么是图像识别。先准备 API Key,并从适用模型中选择一个模型:
bash
export CLAWPOWER_API_KEY='你的 API Key'
export CLAWPOWER_MODEL='从模型列表复制的模型 ID'
curl -sS --fail-with-body 'https://api.clawpowerai.com/v1/chat/completions' \
-H "Authorization: Bearer $CLAWPOWER_API_KEY" \
-H 'Content-Type: application/json' \
--data-binary @- <<JSON
{
"model": "$CLAWPOWER_MODEL",
"messages": [
{"role": "user", "content": "用三句话解释什么是图像识别。"}
],
"stream": false
}
JSON回答位于 choices[0].message.content。这个场景不需要图片编码或上传;本页未对这条具体文字请求单独实测。
场景二:发送本地截图和提示词
例如你有一张本地的抖音截图 screenshot.jpg,想让 GPT 概括其中可见的人物、标识和文字。先把图片编码为 Base64,再与提示词一起发送。沿用上面设置的 CLAWPOWER_API_KEY:
bash
IMAGE_BASE64=$(base64 < screenshot.jpg | tr -d '\n')
curl -sS --fail-with-body 'https://api.clawpowerai.com/v1/chat/completions' \
-H "Authorization: Bearer $CLAWPOWER_API_KEY" \
-H 'Content-Type: application/json' \
--data-binary @- <<JSON
{
"model": "$CLAWPOWER_MODEL",
"messages": [{
"role": "user",
"content": [
{"type": "text", "text": "请用中文概括这张截图中可见的内容,包括人物、平台标识和文字;不要推断视频未展示的动作。"},
{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,$IMAGE_BASE64"}}
]
}],
"stream": false
}
JSON将 screenshot.jpg 换成你的本地图片路径。图片和提示词在同一个请求中发送,不需要再调用其他接口。成功时,仍从 choices[0].message.content 读取总结;usage 是本次 token 用量。
返回的总结
响应结构示例如下。文本内容和 token 数字不是每次请求的固定结果:
json
{
"id": "chatcmpl-example",
"object": "chat.completion",
"model": "<MODEL_ID>",
"choices": [{
"index": 0,
"message": {
"role": "assistant",
"content": "截图顶部有抖音标识;画面中两人在室内木地板场地面对面站立;底部有账号和文字说明。"
},
"finish_reason": "stop"
}],
"usage": {
"prompt_tokens": 2759,
"completion_tokens": 334,
"total_tokens": 3093
}
}choices[0].finish_reason 表示回答结束的原因。图片输入是否可用取决于所选模型;本地 JPEG 图片的 Base64 输入方式已通过公共 API 实测,不能据此推断所有模型都支持图片。图片若为 PNG,需要把请求中的 image/jpeg 改为 image/png;PNG、图片 URL 及流式返回尚未按此场景逐项验证。请求失败时先检查 HTTP 状态和响应体中的 error。
场景三:核对网购订单和收到的商品
例如,你从网购平台下载了订单 PDF,又拍了一张收到的商品及包装照片。你想核对商品名称、颜色、规格和数量是否与订单一致。将本地文件分别保存为 order.pdf 和 package.jpg,沿用前面设置的 CLAWPOWER_API_KEY 与 CLAWPOWER_MODEL:
bash
PDF_BASE64=$(base64 < order.pdf | tr -d '\n')
IMAGE_BASE64=$(base64 < package.jpg | tr -d '\n')
curl -sS --fail-with-body 'https://api.clawpowerai.com/v1/chat/completions' \
-H "Authorization: Bearer $CLAWPOWER_API_KEY" \
-H 'Content-Type: application/json' \
--data-binary @- <<JSON
{
"model": "$CLAWPOWER_MODEL",
"messages": [{
"role": "user",
"content": [
{"type": "text", "text": "请对照订单 PDF 和收到商品的包装图片,核对商品名称、颜色、规格和数量。只根据材料中看得见的信息,列出一致项、不一致项和无法确认项。"},
{"type": "file", "file": {"filename": "order.pdf", "file_data": "data:application/pdf;base64,$PDF_BASE64"}},
{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,$IMAGE_BASE64"}}
]
}],
"stream": false
}
JSON这里的 PDF、图片和提示词通过一次请求发送。file_data 和 image_url.url 填的是文件内容编码,不是本地路径。成功后从 choices[0].message.content 读取核对结果;例如,它可以指出订单与包装上标示的颜色或规格不同,并把照片无法确认的项目单独列出。此方式已使用模拟订单 PDF 和包装图通过公共 API 实测;实际网购订单与照片的识别效果取决于文件清晰度及所选模型对 PDF、图片输入的支持。
对话方式:添加系统提示词
如果希望模型按固定要求回答,可以在用户问题前加入一条 system 消息。例如,让它始终用通俗中文、最多三句话作答。沿用前面设置的 CLAWPOWER_API_KEY 和 CLAWPOWER_MODEL:
bash
curl -sS --fail-with-body 'https://api.clawpowerai.com/v1/chat/completions' \
-H "Authorization: Bearer $CLAWPOWER_API_KEY" \
-H 'Content-Type: application/json' \
--data-binary @- <<JSON
{
"model": "$CLAWPOWER_MODEL",
"messages": [
{"role": "system", "content": "请用通俗中文回答,每次最多三句话;不确定的内容请明确说明。"},
{"role": "user", "content": "什么是图像识别?"}
],
"stream": false
}
JSONsystem 写回答要求,user 写本次问题。使用图片或 PDF 时,也可以在包含图片或文件的 user 消息前加入 system 消息。回答仍从 choices[0].message.content 读取;具体遵循程度取决于所选模型。
对话方式:基于图片继续追问
前面的三个场景展示了发送哪些内容。多轮续问解决的是另一个问题:第一次得到回答后,怎样让 GPT 结合前面的内容继续回答。例如,GPT 已经总结了场景二的截图,你接着想问“截图下方白色卡片写了什么”。
先按场景二发送第一次请求,并在那条 curl 命令末尾加上 > first-response.json,保存第一次的完整响应。然后执行下面的第二次请求。这里使用 jq 读取第一次回答、正确生成 JSON;还需保留前面设置的 CLAWPOWER_API_KEY 和 CLAWPOWER_MODEL,并在当前目录放好 screenshot.jpg。
bash
FIRST_REPLY=$(jq -er '.choices[0].message.content | select(type == "string" and length > 0)' first-response.json)
jq -n \
--arg model "$CLAWPOWER_MODEL" \
--arg assistant "$FIRST_REPLY" \
--rawfile image <(base64 < screenshot.jpg | tr -d '\n') \
'{
model: $model,
messages: [
{
role: "user",
content: [
{type: "text", text: "请用中文概括这张截图中可见的内容,包括人物、平台标识和文字;不要推断视频未展示的动作。"},
{type: "image_url", image_url: {url: ("data:image/jpeg;base64," + $image)}}
]
},
{role: "assistant", content: $assistant},
{role: "user", content: "请把截图下方白色卡片中的文字抄出来;看不清的地方请说明。"}
],
stream: false
}' |
curl -sS --fail-with-body 'https://api.clawpowerai.com/v1/chat/completions' \
-H "Authorization: Bearer $CLAWPOWER_API_KEY" \
-H 'Content-Type: application/json' \
--data-binary @-第二次仍调用 POST /v1/chat/completions。messages 按顺序放入第一次的提问和图片(user)、第一次的回答(assistant)、新的追问(user)。接口不会自动替你保存前一轮对话;如果追问需要看原图,第二次请求也要带上原图。新的回答仍在 choices[0].message.content。上述消息结构已用本地截图通过公共 API 实测;其他模型的多轮图片能力需按模型核对。
