SeerMarTech API 文档

主题

设置 Gemini LLM Responses 任务 ​

POST /v3/ai_optimization/gemini/llm_responses/task_post

接口说明 ​

通过本接口，你可以向指定的 Gemini 模型提交结构化生成任务，并在任务完成后异步获取结果。

这是标准异步模式：创建任务，再通过结果查询接口、id、或回调地址获取结果。如果你的业务不要求实时返回，推荐使用该方式。任务完成时间取决于系统负载。

如果你需要即时结果，可改用 实时（Live）模式；Live 模式通常不需要分开进行 POST 提交和 GET 获取。

请求地址 ​

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

计费说明 ​

  • 该接口在创建任务时扣费
  • 每个任务执行前会自动预扣 USD 0.01
  • 参考价约 ¥0.1600 / 次
  • 如果最终模型费用低于 USD 0.01，差额会退回账户余额
  • 若任务在 72 小时未完成，任务会被标记为失败，预扣费用会退回
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

使用限制 ​

  • 所有 POST 数据使用 JSON（UTF-8 编码）
  • 请求体为 JSON 数组：[{ ... }]
  • 每分钟最多可发送 2000 次 API 调用
  • 每次 POST 最多 100 个任务
  • 如果单次 POST 中任务数 100，出部分将返回错误 40006

任务完成与回调机制 ​

标准模式任务最长可能需要 72 小时完成。

可通过以下方式获取结果：

  1. 使用任务唯一标识 id 获取结果
  2. 在创建任务时设置 postback_url
  3. 在创建任务时设置 pingback_url

回调说明 ​

  • postback_url：任务完成后，本平台会向该地址发送 POST 请求，并以 gzip 压缩格式推送结果
  • pingback_url：任务完成后，本平台会向该地址发送 GET 通知

你可以在 URL 中使用以下占位符：

  • $id：任务 ID
  • $tag：URL 编码后的自定义标签

例如：

  • http://your-server.com/postbackscript?id=$id
  • http://your-server.com/postbackscript?id=$id&tag=$tag
  • http://your-server.com/pingscript?id=$id
  • http://your-server.com/pingscript?id=$id&tag=$tag

注意事项：

  • 若回调地址特殊字符，会自动进行 URL 编码
  • 例如 # 会被编码为 %23
  • 如果你的服务器在 10 秒未响应，连接会因时被中止，任务会转 tasks_ready 列表
  • 若账户余额为负，即使任务执行成功，也无法获取结果

请求参数 ​

下表为创建任务时可用字段。

字段名类型说明
user_promptstring填。发送给 AI 模型的问题或任务描述；最长 500 个字符。
model_namestring填。AI 模型名称。由模型名和版本组成；若传基础模型名，系统会自动补为最新版本。例如传 gemini-1.5-pro 时，可能自动设置为 gemini-1.5-pro-002。可通过 /v3/ai_optimization/gemini/llm_responses/models 获取可用模型列表。
max_output_tokensinteger可选。AI 响应的最大 token 数。最小值 1，最大值 4096，默认值 2048。**注意：**若 web_search=true，或请求中使用了推理模型，最终输出 token 可能该限制。**注意 2：**若 use_reasoning=true，该值最小为 1024。
temperaturefloat可选。控制输出随机性。值越高，结果越发散；值越低，结果越聚焦。最小值 0，最大值 2，默认值 1.3。
top_pfloat可选。控制输出多样性，通过限制候选 token 范围来影响生成结果。最小值 0，最大值 1，默认值 0.9。
web_searchboolean可选。是否启用联网搜索以获取当前网页信息。启用后，模型可访问并引用实时网页。默认值 false。支持该能力的模型请查询 /v3/ai_optimization/gemini/llm_responses/models。该参数会影响最终费用，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
system_messagestring可选。用于定义 AI 的角色、语气或行为规则；最长 500 个字符。
message_chainarray可选。对话历史。数组中的每个对象表示一轮上下文消息， role 和 message 字段。role 支持 user 或 ai；message 为消息文本，最长 500 个字符。最多可传 10 个消息对象。
use_reasoningboolean可选。是否启用推理能力。启用后，模型会进行推理再生成回答。支持该能力的模型请查询 /v3/ai_optimization/gemini/llm_responses/models。默认值 false。**注意：**若设为 true，max_output_tokens 最小为 1024。**注意 2：**对于 Gemini Pro 模型，use_reasoning 会自动设为 true。
tagstring可选。用户自定义任务标识，最长 255 个字符。可用于结果匹；提交后会在响应的 data 对象中返回。
postback_urlstring可选。任务完成后接收结果的回调地址。平台会向该地址发送带 gzip 压缩结果的 POST 请求。支持 $id 和 $tag 占位符。
pingback_urlstring可选。任务完成后的通知地址。平台会向该地址发送 GET 请求。支持 $id 和 $tag 占位符。

message_chain 示例 ​

json
[
 {
 "role": "user",
 "message": "Hello, what's up?"
 },
 {
 "role": "ai",
 "message": "Hello! I’m doing well, thank you. How can I assist you today?"
 }
]

响应结构 ​

接口返回 JSON 数据， tasks 数组记录本次提交的任务信息。

顶层字段 ​

字段名类型说明
versionstring当前 API 版本
status_codeinteger通用状态码，完整列表见 /v3/appendix/errors
status_messagestring通用状态信息
timestring执行耗时（秒）
costfloat本次请求总费用，单位 USD
tasks_countintegertasks 数组中的任务数量
tasks_errorinteger返回错误的任务数量
tasksarray任务数组

tasks 数组字段 ​

字段名类型说明
idstring任务唯一标识，UUID 格式
status_codeinteger任务状态码，范围通常为 10000-60000
status_messagestring任务状态信息
timestring任务执行耗时（秒）
costfloat单个任务费用，单位 USD
result_countintegerresult 数组数量
patharrayURL 路径
dataobject回显你在 POST 请求中提交的参数
resultarray结果数组；在任务刚创建时通常为 null

建议在集成时做好状态码与异常处理逻辑，因异步执行、回调时、余额不足等影响业务流程。

请求示例 ​

cURL ​

bash
curl --location --request POST "https://api.seermartech.cn/v3/ai_optimization/gemini/llm_responses/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "model_name": "gemini-2.5-flash",
 "user_prompt": "provide information on how relevant the amusement park business is in France now"
 }
]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/ai_optimization/gemini/llm_responses/task_post"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "system_message": "communicate as if we are in a business meeting",
 "message_chain": [
 {
 "role": "user",
 "message": "Hello, what's up?"
 },
 {
 "role": "ai",
 "message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
 }
 ],
 "model_name": "gemini-2.5-flash",
 "user_prompt": "provide information on how relevant the amusement park business is in France now"
 }
]

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

TypeScript ​

typescript
import axios from "axios";

const postArray = [
 {
 system_message: "communicate as if we are in a business meeting",
 message_chain: [
 {
 role: "user",
 message: "Hello, what's up?"
 },
 {
 role: "ai",
 message: "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
 }
 ],
 model_name: "gemini-2.5-flash",
 user_prompt: "provide information on how relevant the amusement park business is in France now"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/ai_optimization/gemini/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
{
 "version": "0.1.20250526",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1071 sec.",
 "cost": 0.0102,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0032 sec.",
 "cost": 0.0102,
 "result_count": 0,
 "path": [
 "v3",
 "ai_optimization",
 "gemini",
 "llm_responses",
 "task_post"
 ],
 "data": {
 "api": "ai_optimization",
 "function": "llm_responses",
 "se": "gemini",
 "system_message": "communicate as if we are in a business meeting",
 "message_chain": [
 {
 "role": "user",
 "message": "Hello, what's up?"
 },
 {
 "role": "ai",
 "message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
 }
 ],
 "model_name": "gemini-2.5-flash",
 "user_prompt": "provide information on how relevant the amusement park business is in France now"
 },
 "result": null
 }
 ]
}

状态与错误处理 ​

  • 顶层 status_code=20000 通常表示请求已成功处理
  • 任务创建成功时，任务级别一般会返回类似 20100 的状态
  • 若单次 POST过 100 个任务，出部分会返回 40006
  • 更完整的错误码和状态信息请参考 /v3/appendix/errors

建议重点处理以下：

  • 任务创建成功，但 result=null：表示任务已异步队列，需后续查询或回调
  • 回调时：你的服务器 10 秒未响应，任务会 tasks_ready
  • 余额不足或为负：即使任务已完成，也可能无法获取结果
  • 参数组合不合法：例如 use_reasoning=true 但 max_output_tokens<1024

实用场景 ​

  • 生成行业机会判断：国家、行业、产品线等背景信息，让模型输出市场性判断， SEO 团队筛选值得的主题方向。
  • 构建搜索简报：结合 system_message 与 message_chain 约束输出风格，批量生成适合编辑团队使用的需求说明。
  • 评估实时趋势话题：启用 web_search 获取当前网页信息，判断某一主题是否备时效性流量价值，支持热点规划。
  • 沉淀多轮分析上下文：通过 message_chain 传既有讨论，让模型基于连续上下文输出更稳定的研究结论，适合专题分析流程。
  • 批量异步处理长文本任务：对大量提示词进行标准模式提交，在非实时场景下降低系统阻塞，适合夜间批处理、报告生成与规模化分析。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API