专利生成 API 技术文档

1. 快速开始

推荐只使用稳定入口 POST /v1/patent/create。接口会立即返回任务编号和绝对地址 poll_url，调用方随后轮询 poll_url 获取进度或结果。

curl -X POST "https://patent.ecoaitech.com/v1/patent/create" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_PATENT_API_KEY" \
  -d '{
    "message": "一种面向锂电池材料制备过程的智能温控优化方法",
    "patent_type": "process",
    "email": ""
  }'

文档示例统一使用 YOUR_PATENT_API_KEY 占位符。真实 Key 由服务方单独发放，不会在公开页面展示。

2. 鉴权与 Key

创建任务接口需要 API Key。获得 Key 后，建议优先放入 HTTP Header，不要放在 URL 查询参数中。

技术人员如需开通，请联系 digi@ecoaitech.com，说明调用场景、预计调用量和回调/轮询方式。

3. 创建专利生成任务

请求 Body

成功响应

{
  "task_id": "pat_20260509_120000_ab12cd",
  "status": "running",
  "is_async": true,
  "poll_url": "https://patent.ecoaitech.com/api/status/pat_20260509_120000_ab12cd/POLL_TOKEN",
  "poll_token": "POLL_TOKEN",
  "retry_after": 10,
  "patent_type": "process",
  "type": "patent"
}

重点字段是 poll_url。它是完整绝对 URL，Dify 或后端可以直接拿它发起下一步轮询。

4. 轮询结果

poll_url 已包含任务编号和轮询 token，不需要再传 API Key。建议按 retry_after 秒间隔轮询，直到返回 done 或 error。

进行中

{
  "status": "running",
  "progress": 45,
  "message": "正在写作第3章..."
}

完成

{
  "status": "done",
  "progress": 100,
  "message": "图表: 4",
  "topic": "一种面向锂电池材料制备过程的智能温控优化方法",
  "result": {
    "md_content": "完整Markdown正文",
    "word_count": 8200,
    "citations": 0,
    "sources": 0,
    "charts": 4,
    "patent_type": "process",
    "download_url": "https://patent.ecoaitech.com/api/download/pat_.../POLL_TOKEN/docx"
  }
}

失败

{
  "status": "error",
  "progress": 0,
  "message": "",
  "error": "生成失败原因"
}

5. 专利类型参数

patent_type 用于让生成管线选择更合适的权利要求布局、附图风格、实施例结构和技术表达方式。Dify 可以把它做成单选框或下拉框。

为保持接口稳定，未来新增类型时会尽量向后兼容。现阶段建议客户系统只暴露以上四个值。

6. Dify 工作流配置

动态表单建议

HTTP 请求节点

Method: POST
URL: https://patent.ecoaitech.com/v1/patent/create
Headers:
  Content-Type: application/json
  X-API-Key: YOUR_PATENT_API_KEY
Body:
{
  "message": "",
  "patent_type": "",
  "email": ""
}

输出处理代码节点

import json

def main(body):
    data = json.loads(body)
    return {
        "is_async": str(data.get("is_async", False)).lower(),
        "poll_url": data.get("poll_url", ""),
        "status": data.get("status", ""),
        "task_id": data.get("task_id", ""),
        "poll_token": data.get("poll_token", ""),
        "patent_type": data.get("patent_type", ""),
        "result": json.dumps(data.get("result", {}), ensure_ascii=False) if data.get("result") else ""
    }

如果已经复用深度报告的输出处理节点，不加 patent_type 也可以跑通；加上后便于后续分流、展示和日志分析。

7. 调用示例

Python

import time
import requests

API_KEY = "YOUR_PATENT_API_KEY"
base_url = "https://patent.ecoaitech.com"

resp = requests.post(
    f"{base_url}/v1/patent/create",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "message": "一种面向锂电池材料制备过程的智能温控优化方法",
        "patent_type": "process",
        "email": ""
    },
    timeout=30,
)
resp.raise_for_status()
task = resp.json()

while True:
    status_resp = requests.get(task["poll_url"], timeout=30)
    status_resp.raise_for_status()
    payload = status_resp.json()
    if payload["status"] == "done":
        markdown = payload["result"]["md_content"]
        download_url = payload["result"]["download_url"]
        break
    if payload["status"] == "error":
        raise RuntimeError(payload.get("error") or "patent generation failed")
    time.sleep(task.get("retry_after", 10))

JavaScript / Node.js

const apiKey = "YOUR_PATENT_API_KEY";

const created = await fetch("https://patent.ecoaitech.com/v1/patent/create", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": apiKey
  },
  body: JSON.stringify({
    message: "一种面向锂电池材料制备过程的智能温控优化方法",
    patent_type: "process",
    email: ""
  })
}).then(r => r.json());

let result;
while (true) {
  const payload = await fetch(created.poll_url).then(r => r.json());
  if (payload.status === "done") {
    result = payload.result;
    break;
  }
  if (payload.status === "error") throw new Error(payload.error || "failed");
  await new Promise(resolve => setTimeout(resolve, (created.retry_after || 10) * 1000));
}

console.log(result.md_content);
console.log(result.download_url);

8. 给 LLM / AI 编程助手的接入提示

把下面这段说明交给 AI 编程助手，通常可以快速生成可用的接入代码。

你要接入 ScholarForce AI 专利生成 API。
Base URL 是 https://patent.ecoaitech.com。
创建任务：POST /v1/patent/create，Header 使用 X-API-Key: YOUR_PATENT_API_KEY。
请求 JSON 至少包含 message，可选 patent_type 和 email。
patent_type 只能使用 auto、software、mechanical、process。
创建接口会返回 is_async=true、status=running、task_id、poll_url、poll_token、retry_after。
必须使用返回的 poll_url 轮询结果；poll_url 是绝对 URL，不需要额外拼接域名。
轮询返回 status=running 表示继续等待；status=done 时读取 result.md_content 和 result.download_url；status=error 时读取 error。
不要把 API Key 写死在前端公开代码中，应放在 Dify 密钥配置、后端环境变量或服务端代理中。

9. 错误码与注意事项

安全建议：客户侧不要把真实 API Key 放入公开网页源码、移动端包或 Git 仓库。Dify 内部工作流可通过 HTTP 请求节点配置 Header；自建系统建议通过后端服务转发。