设置 Claude LLM Responses 异步任务

POST /v3/ai_optimization/claude/llm_responses/task_post

请求方法：POST
请求路径：/v3/ai_optimization/claude/llm_responses/task_post

本接口用于为指定的 Claude 模型创建异步任务，并根据参数获取结构化响应。任务创建后，系统将在后台执行，完成后可通过任务 ID 查询结果，也可以使用 postback_url 或 pingback_url 接收通知。

该接口采用标准异步任务模式，适合不要求实时返回结果的场景。如果业务需要立即获取响应，请使用实时模式接口。

> 单个任务执行时需要预扣参考费用约 ¥0.0720。如果 LLM 费用低于该金额，差额将退回账户余额。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求限制与任务说明

平台限流以认证说明中的 30/60/120 次/分钟规则为准。

每次 POST 请求最多 100 个任务。 -出 100 个任务的部分将返回错误码 40006。
标准异步任务最长可能需要 72 小时完成。 -过 72 小时仍未完成的任务将标记为失败，并退还预扣费用。
如果账户余额为负，即使任务执行成功，也不会返回任务结果。
可通过任务唯一标识 id 查询已完成任务。
设置 postback_url 或 pingback_url 后，系统可在任务完成时主动通知指定地址。
如果通知服务器 10 秒未响应，连接将因时中断，任务会转移到 tasks_ready 列表。

计费说明

提交任务时即产生任务设置费用。任务费用取决于所使用的模型及请求参数，例如是否启用联网搜索、推理等功能。

参考价约 ¥0.0720 / 任务。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

请求体使用 UTF-8 编码的 JSON 数组格式：

json

[
  {
    "user_prompt": "请分析当前法国游乐园行业的市场性",
    "model_name": "claude-sonnet-4-0"
  }
]

任务参数

参数	类型	填	说明
`user_prompt`	string	是	发送给 AI 模型的问题或任务，最多 500 个字符。
`model_name`	string	是	AI 模型名称，可模型版本。如果只指定基础模型名称，系统将默认使用该模型的最新版本。例如指定 `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` 或使用推理模型时，输出 Token 数可能该限制。启用 `use_reasoning` 时，最小值为 `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` 确认。
`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`。启用后，`max_output_tokens` 最小值为 `1025`；`force_web_search`须为 `false`；不能同时使用 `temperature` 或 `top_p`。
`tag`	string	否	用户自定义任务标识，最多 255 个字符。该值会出现在响应的 `data` 对象中，可用于任务与业务记录。
`postback_url`	string	否	任务完成后接收结果的 URL。系统会向该地址发送任务结果的 POST 请求，采用 gzip 压缩格式。URL 中可使用 `$id` 和 `$tag` 占位符，系统发送请求前会替换为任务 ID 和经过 URL 编码的标签值。
`pingback_url`	string	否	任务完成后的通知 URL。系统会向该地址发送 GET 请求。URL 中可使用 `$id` 和 `$tag` 占位符。

`message_chain` 示例

json

[
  {
    "role": "user",
    "message": "你好，最近怎么样？"
  },
  {
    "role": "ai",
    "message": "我很好，谢谢。今天想讨论哪些主题或项目？"
  }
]

回调 URL 示例

text

https://your-server.example.com/postback?id=$id&tag=$tag
https://your-server.example.com/pingback?id=$id&tag=$tag

postback_url 和 pingback_url 中的特殊字符会进行 URL 编码，例如 # 会编码为 %23。

请求示例

cURL

bash

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

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

post_data = [
    {
        "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=post_data, timeout=30)
response.raise_for_status()

result = response.json()
if result.get("status_code") == 20000:
    print(result)
else:
    print(
        f"请求失败，错误码：{result.get('status_code')}，"
        f"错误信息：{result.get('status_message')}"
    )

TypeScript

typescript

import axios from "axios";

const postData = [
  {
    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
  .post(
    "https://api.seermartech.cn/v3/ai_optimization/claude/llm_responses/task_post",
    postData,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.error("请求失败：", error.response?.data || error.message);
  });

响应结构

接口返回 JSON 数据提交任务的 tasks 数组。

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	API 总体状态码。完整错误码请参考 `/v3/appendix/errors`。
`status_message`	string	API 总体状态信息。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务数量。
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量。
`tasks`	array	已创建任务的详细信息。

`tasks`素字段

字段	类型	说明
`id`	string	系统生成的任务唯一标识，采用 UUID 格式。
`status_code`	integer	任务状态码，通常位于 `10000`–`60000` 范围。
`status_message`	string	任务状态信息。
`time`	string	任务执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。创建任务时通常为 `0`。
`path`	array	当前请求的 API 路径信息。
`data`	object	创建任务时提交的参数。
`result`	array	任务结果数组。创建任务接口返回时为 `null`，需通过任务查询接口获取结果。

响应示例

json

{
  "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": "66f3a8b1-1234-4c56-9abc-1234567890ab",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0500 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
    }
  ]
}

状态码与异常处理

20000：请求成功。
40006：单次请求提交的任务数 100 个。
状态码：表示请求参数、账户状态、任务执行或系统处理异常。

建议客户端始终检查顶层和任务级别的 status_code、status_message，并针对失败任务实现重试、告警及任务状态跟踪机制。完整错误码请参考 /v3/appendix/errors。

实用场景

批量生成市场研究问题的 AI 分析结果，为 SEO团队快速评估行业趋势、用户需求和主题性。
结合联网搜索生成最新行业摘要，帮助运营人员补时效性信息并降低人工检索成本。
通过 message_chain 维护多轮分析上下文，持续完善、竞品或策略的研究结论。
使用 tag 业务任务与记录，便于将异步 AI 结果写回管理系统或数据仓库。
** postback_url 接收完成通知**，在任务完成后自动触发报告生成、审核或 SEO 工作流。

设置 Claude LLM Responses 异步任务 ​

请求限制与任务说明 ​

计费说明 ​

请求参数 ​

任务参数 ​

message_chain 示例 ​

回调 URL 示例 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层响应字段 ​

tasks素字段 ​

响应示例 ​

状态码与异常处理 ​

实用场景 ​

设置 Claude LLM Responses 异步任务

请求限制与任务说明

计费说明

请求参数

任务参数

`message_chain` 示例

回调 URL 示例

请求示例

cURL

Python

TypeScript

响应结构

顶层响应字段

`tasks`素字段

响应示例

状态码与异常处理

实用场景