Skip to content

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"
}

请求体编辑器中 messages 下的 0 表示第一条消息的数组索引,不是要发送的字段。 试用前请把 model 改为实际可用的模型 ID。 发送本地图片时,按下方图文场景把 content 改为文字和图片组成的数组。

试验场​

授权
主体

示例​

场景一:只发送文字 ​

例如,你想让 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
}
JSON

system 写回答要求,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 实测;其他模型的多轮图片能力需按模型核对。

联系加微信 clawpower