创建 Claude LLM Responses 任务

POST /v3/ai_optimization/claude/llm_responses/task_post

接口说明

/v3/ai_optimization/claude/llm_responses/task_post 用于提交 Claude 大模型响应任务。你可以根据参数，向指定模型请求结构化回答。

这是标准异步模式：创建任务，本平台完成采集/生成后，再通过结果接口、postback_url 或 pingback_url 获取结果。若你的业务不要求实时返回，推荐使用此方式。

如果你的系统需要即时结果，建议改用对应的 Live 模式接口；Live 模式无需分别发起 POST 和 GET 请求。

计费与执行说明

• 本接口在创建任务时会进行预扣费 USD 0.01
• 按换算规则，参考预扣约 ¥0.1600 / 次
• 如果最终 LLM 实消耗低于 USD 0.01，差额会退回账户余额
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

限制与规则：

• 所有 POST 数据使用 JSON（UTF-8）格式
• 请求体是 JSON 数组：[{ ... }]
• 每分钟最多可发起 2000 次 API 调用
• 单次 POST 最多可 100 个任务
• 若单次请求 100 个任务，出部分会返回错误 40006
• 标准模式任务最长可能需要 72 小时完成
• 若 72 小时未完成，任务会被标记为失败，且预扣的 USD 0.01 会退回
• 如果你的账户余额为负，即使任务已成功完成，也无法获取结果

结果获取方式

任务创建后，可通过以下方式拿到结果：

1. 使用任务唯一标识 id 获取结果
2. 创建任务时设置 postback_url，任务完成后本平台会将结果 POST 到该地址
3. 创建任务时设置 pingback_url，任务完成后本平台会向该地址发送通知

注意事项：

• 若你的服务器在 10 秒未响应，连接会因时被中止
• 此时任务会被转 /v3/ai_optimization/claude/llm_responses/tasks_ready/ 列表
• 返回的错误码与错误信息取决于你的服务器
• postback_url 返回的数据会以 gzip 压缩格式发送

---

请求方式

POST https://api.seermartech.cn/v3/ai_optimization/claude/llm_responses/task_post

请求参数

以下为任务对象中可用字段说明。

字段名	类型	说明
user_prompt	string	填。发送给 AI 模型的问题或任务描述；最多 500 个字符。
model_name	string	填。模型名称，模型名和版本名；如果只传基础模型名，默认自动使用最新版本。例如传 claude-opus-4-0 时，系统会自动使用 claude-opus-4-20250514。可通过 /v3/ai_optimization/claude/llm_responses/models 获取可用模型列表。
max_output_tokens	integer	可选。AI 输出的最大 token 数；最小值 1，最大值 4096，默认值 2048。**注意：**如果 web_search=true 或使用了推理模型，输出 token 可能该限制。若 use_reasoning=true，该字段最小值为 1025。
temperature	float	可选。控制输出随机性；值越高，结果越发散；值越低，结果越稳定。取值范围 0 到 1，默认 0.7。不能与 top_p 同时使用。
top_p	float	可选。控制输出多样性，通过限制 token 选择范围来实现；取值范围 0 到 1，默认 null。不能与 temperature 同时使用。
web_search	boolean	可选。是否启用联网搜索，以便模型访问并引用当前网页信息；默认 false。支持该能力的模型请参考 /v3/ai_optimization/claude/llm_responses/models。成本以响应中的 cost 字段为准。
force_web_search	boolean	可选。是否强制 AI 使用联网搜索；启用前提是 web_search=true。默认 false。**注意：**即使设置为 true，也不保证最终响应一定引用网页来源。
web_search_country_iso_code	string	可选。联网搜索所使用地区的 ISO 国家代码。可选值：AR、AT、AU、BE、BR、CA、CH、CL、CN、DE、DK、ES、FI、FR、GB、HK、ID、IN、IT、JP、KR、MX、MY、NL、NO、NZ、PH、PL、PT、RU、SA、SE、TR、TW、US、ZA。
web_search_city	string	可选。联网搜索所使用的城市名称。
system_message	string	可选。用于定义 AI 的角色、语气或行为方式；最多 500 个字符。
message_chain	array	可选。对话历史。数组中每个对象表示一轮上下文， role 和 message：role 支持 user 或 ai，message 最多 500 个字符。数组最多可 10 个消息对象。
use_reasoning	boolean	可选。是否启用推理能力；默认 false。支持推理的模型可通过 /v3/ai_optimization/claude/llm_responses/models 查看。**注意：**设为 true 时，max_output_tokens 最小值为 1025；force_web_search须为 false；且不能使用 temperature 与 top_p。
tag	string	可选。自定义任务标识，最长 255 个字符。可用于在结果中进行业务侧与识别；响应的 data 对象中会返回该值。
postback_url	string	可选。任务完成后接收结果的回调地址。本平台会将结果以 gzip 压缩格式通过 POST 发送到该地址。支持使用 $id 作为任务 id 变量，$tag 作为 URL 编码后的 tag 变量。示例：http://your-server.com/postbackscript?id=$id 或 http://your-server.com/postbackscript?id=$id&tag=$tag。**注意：**特殊字符会被 URL 编码，例如 # 会转为 %23。
pingback_url	string	可选。任务完成通知地址。本平台会通过 GET 请求通知该地址。支持使用 $id 作为任务 id 变量，$tag 作为 URL 编码后的 tag 变量。示例：http://your-server.com/pingscript?id=$id 或 http://your-server.com/pingscript?id=$id&tag=$tag。**注意：**特殊字符会被 URL 编码，例如 # 会转为 %23。

---

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/ai_optimization/claude/llm_responses/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "system_message": "请以商务会议沟通风格回复",
 "message_chain": [
 {
 "role": "user",
 "message": "你好，最近法国线下娱乐市场有什么变化？"
 },
 {
 "role": "ai",
 "message": "你好，我可以从市场需求、消费趋势和区域表现几个维度为你分析。"
 }
 ],
 "max_output_tokens": 1024,
 "temperature": 0.3,
 "web_search_country_iso_code": "FR",
 "model_name": "claude-sonnet-4-0",
 "web_search": true,
 "user_prompt": "请说明当前法国游乐园行业的市场性和发展"
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/ai_optimization/claude/llm_responses/task_post"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

payload = [
 {
 "system_message": "请以商务会议沟通风格回复",
 "message_chain": [
 {
 "role": "user",
 "message": "你好，最近法国线下娱乐市场有什么变化？"
 },
 {
 "role": "ai",
 "message": "你好，我可以从市场需求、消费趋势和区域表现几个维度为你分析。"
 }
 ],
 "max_output_tokens": 1024,
 "temperature": 0.3,
 "web_search_country_iso_code": "FR",
 "model_name": "claude-sonnet-4-0",
 "web_search": True,
 "user_prompt": "请说明当前法国游乐园行业的市场性和发展"
 }
]

response = requests.post(url, headers=headers, json=payload)
print(response.json)

TypeScript

import axios from "axios";

const postArray = [
 {
 system_message: "请以商务会议沟通风格回复",
 message_chain: [
 {
 role: "user",
 message: "你好，最近法国线下娱乐市场有什么变化？"
 },
 {
 role: "ai",
 message: "你好，我可以从市场需求、消费趋势和区域表现几个维度为你分析。"
 }
 ],
 max_output_tokens: 1024,
 temperature: 0.3,
 web_search_country_iso_code: "FR",
 model_name: "claude-sonnet-4-0",
 web_search: true,
 user_prompt: "请说明当前法国游乐园行业的市场性和发展"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/ai_optimization/claude/llm_responses/task_post",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postArray
})
 .then((response) => {
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

---

响应说明

接口返回 JSON 数据 tasks 数组，用于描述本次提交的任务信息。

顶层响应字段

字段名	类型	说明
version	string	当前 API 版本。
status_code	integer	通用状态码。完整列表参考 /v3/appendix/errors。建议在业务中做好异常与错误处理。
status_message	string	通用状态信息。完整列表参考 /v3/appendix/errors。
time	string	执行耗时，单位秒。
cost	float	本次请求总成本，单位 USD。扣费以该字段为准。
tasks_count	integer	tasks 数组中的任务总数。
tasks_error	integer	tasks 数组中返回错误的任务数量。
tasks	array	任务数组。

tasks 数组字段

字段名	类型	说明
id	string	系统中的唯一任务标识，UUID 格式。
status_code	integer	任务状态码，范围通常为 10000-60000。完整列表参考 /v3/appendix-errors/。
status_message	string	任务状态说明。完整列表参考 /v3/appendix-errors/。
time	string	任务处理耗时，单位秒。
cost	float	当前任务成本，单位 USD。
result_count	integer	result 数组中的数量。
path	array	URL 路径。
data	object	与创建任务时传参数一致的对象。
result	array	结果数组。对于本接口的任务提交响应，此处通常为 null。

---

响应示例

{
 "version": "0.1.20250724",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1006 sec.",
 "cost": 0.0102,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "12345678-1234-1234-1234-1234567890ab",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0213 sec.",
 "cost": 0.0102,
 "result_count": 0,
 "path": [
 "v3",
 "ai_optimization",
 "claude",
 "llm_responses",
 "task_post"
 ],
 "data": {
 "api": "ai_optimization",
 "function": "llm_responses",
 "se": "claude",
 "system_message": "请以商务会议沟通风格回复",
 "message_chain": [
 {
 "role": "user",
 "message": "你好，最近法国线下娱乐市场有什么变化？"
 },
 {
 "role": "ai",
 "message": "你好，我可以从市场需求、消费趋势和区域表现几个维度为你分析。"
 }
 ],
 "max_output_tokens": 1024,
 "temperature": 0.3,
 "web_search_country_iso_code": "FR",
 "model_name": "claude-sonnet-4-0",
 "web_search": true,
 "user_prompt": "请说明当前法国游乐园行业的市场性和发展"
 },
 "result": null
 }
 ]
}

---

常见错误与处理建议

40006

单次 POST 请求中的任务数上限 100。 **处理建议：**将任务拆分为多个请求批次发送。

任务时失败

标准模式任务最长可能耗时 72 小时；若时未完成，任务会被标记为失败。 处理建议：

• 通过任务查询接口轮询状态
• 同时 postback_url 或 pingback_url
• 对时任务做自动重试或转人工检查

回调时

如果你的回调服务 10 秒未响应，本平台会中止连接。 处理建议：

• 确保回调接口快速返回 200
• 异步处理回调，阻塞
• 对未成功接收的任务，从 /v3/ai_optimization/claude/llm_responses/tasks_ready/ 补拉结果

参数冲突

以下组合会导致请求不符合规则：

• temperature 与 top_p 同时使用
• use_reasoning=true 时仍传 temperature 或 top_p
• use_reasoning=true 时设置 force_web_search=true
• force_web_search=true 但未开启 web_search

**处理建议：**提交前在业务侧做好参数校验。

实用场景

• 生成行业快：细分行业问题并启用 web_search，快速获取某国家/城市的最新市场概况， SEO 选题与策划。
• 评估地区需求：结合 web_search_country_iso_code 和 web_search_city，分析目标地区的消费趋势、竞争格局或本地热点，支持区域化投放与本地化建设。
• 构建多轮研究助手：通过 message_chain 保留上下文，让模型基于历史对话持续补分析，适合研究、SERP 解读和专题深挖。
• 统一品牌表达：使用 system_message 约束输出语气、结构和角色设定，批量生成更符合品牌规范的 SEO 研究结论或客户汇报素材。
• 异步处理大批量问答任务：对非实时分析需求批量创建任务，并通过 postback_url/pingback_url 回收结果，降低人工检索和整理成本。