AI 长文生成接口接入实践：鉴权、参数与异步任务结果获取

1. 背景与适用场景

长文与结构化内容的自动生成，是内容生产链路里的一类通用需求：给定一句主题或若干素材，期望产出带章节目录与正文的成稿，用于草稿起草、资料整理、多语言内容生产等场景。

本文以云市场上架的一款「长文智能生成」接口为样例，梳理其接入方式、参数设计、返回结构与工程化接入要点。该接口采用异步提交模型——createTask 仅负责提交写作任务并返回任务标识，正文内容需通过任务查询类接口（任务列表 / 文章详情）获取。相关思路同样适用于其他异步任务型内容生成接口。

2. 接口概览

• 接口名：createTask
• 协议：HTTPS，请求方法 POST
• 返回格式：JSON
• 鉴权方式：支持两种
  • 简单身份认证：请求头 Authorization: APPCODE <appcode>
  • 签名认证：AppKey & AppSecret 签名（适合服务端对调用做更强约束的场景）
• 调用地址：以云市场商品页或 API 网关控制台为准；代码样例中以 HOST 常量指代网关域名，所有请求均以 https 协议发起。
• 任务模型：提交（createTask）→ 轮询任务状态（preparing / writing / success）→ 获取正文。

3. 请求参数

请求体（Body，application/json）字段如下：

参数提示：topic 为必填项，内容越明确，产出与预期的偏差越小；reference_list 用于约束生成依据，适合需要引用特定来源的场景。

4. 返回结构

createTask 成功时返回统一网关结构，关键字段在 showapi_res_body：

{
   
  "showapi_res_code": 0,
  "showapi_res_id": "",
  "showapi_res_error": "",
  "showapi_res_body": {
   
    "task_id": "034537",
    "task_status": "preparing",
    "topic": "",
    "ret_code": 0,
    "ret_msg": "提交成功"
  }
}

字段含义：

注意：createTask 本身不返回正文。拿到 task_id 后，需调用任务查询类接口，待 task_status 变为 success 再读取成稿内容。

5. 错误码与排查

该接口未单独定义错误码表，异常沿用 API 网关通用错误处理：当 showapi_res_code 非 0 时，showapi_res_error 携带具体描述。常见情形：

失败时的返回形态（通用网关格式示例）：

{
   
  "showapi_res_code": 1234,
  "showapi_res_error": "APPCODE is expired",
  "showapi_res_body": ""
}

6. 频控与合规

• 计量：调用按次计量，仅当 HTTP 响应状态码为 200 时计入调用次数，非 200 不计入（具体计量规则以云市场商品页公示为准）。
• 内容合规：接口产出由模型生成，需自行对成稿做事实与合规审核，不应直接作为权威结论对外发布。
• 数据安全：请求中的主题与引用链接属于业务输入，建议在传输层使用 HTTPS，不在日志中明文落盘敏感主题；用途限定在授权范围内。
• 用途边界：生成内容应遵守相关平台的内容规范，避免用于侵权或虚假信息场景。

7. 多语言接入示例

以下示例均使用简单身份认证（APPCODE）。HOST 为网关域名常量，实际值以控制台为准；所有请求以 https 协议发起，请求地址为 HOST 拼接 /createTask。

Python

import requests

HOST = "aiarticle.market.alicloudapi.com"   # 以控制台为准
APPCODE = "YOUR_APPCODE"                     # 从环境变量或密钥管理读取，勿硬编码
PATH = "/createTask"


def create_task(topic, lang="1", reference_list=""):
    url = HOST + PATH                         # 实际以 https 协议访问
    headers = {
   
        "Authorization": f"APPCODE {APPCODE}",
        "Content-Type": "application/json",
    }
    payload = {
   "topic": topic, "lang": lang}
    if reference_list:
        payload["reference_list"] = reference_list
    resp = requests.post(url, headers=headers, json=payload, timeout=15)
    return resp.status_code, resp.json()


code, data = create_task("新能源汽车行业上半年发展综述")
print(code, data)

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class CreateTask {
   
    static final String HOST = "aiarticle.market.alicloudapi.com"; // 以控制台为准
    static final String APPCODE = System.getenv("APPCODE");          // 从环境变量读取

    public static void main(String[] args) throws Exception {
   
        String url = HOST + "/createTask"; // 实际以 https 协议访问
        String body = "{\"topic\":\"新能源汽车行业上半年发展综述\",\"lang\":\"1\"}";

        HttpRequest req = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Authorization", "APPCODE " + APPCODE)
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(body))
                .build();

        HttpResponse<String> resp = HttpClient.newHttpClient()
                .send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(resp.statusCode() + " " + resp.body());
    }
}

PHP

<?php
$HOST = "aiarticle.market.alicloudapi.com"; // 以控制台为准
$APPCODE = getenv("APPCODE");
$url = $HOST . "/createTask";               // 实际以 https 协议访问
$body = json_encode(["topic" => "新能源汽车行业上半年发展综述", "lang" => "1"]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: APPCODE " . $APPCODE,
    "Content-Type: application/json",
]);
$resp = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $code . " " . $resp;

Node.js

const https = require('https'); // 该接口使用 https 协议
const HOST = "aiarticle.market.alicloudapi.com"; // 以控制台为准
const APPCODE = process.env.APPCODE;

const data = JSON.stringify({
   
  topic: "新能源汽车行业上半年发展综述",
  lang: "1",
});

const options = {
   
  hostname: HOST,
  path: "/createTask",
  method: "POST",
  headers: {
   
    "Authorization": `APPCODE ${
     APPCODE}`,
    "Content-Type": "application/json",
    "Content-Length": Buffer.byteLength(data),
  },
};

const req = https.request(options, (res) => {
   
  let raw = "";
  res.on("data", (c) => (raw += c));
  res.on("end", () => console.log(res.statusCode, raw));
});
req.on("error", (e) => console.error(e));
req.write(data);
req.end();

curl

HOST="aiarticle.market.alicloudapi.com"   # 以控制台为准，实际以 https 协议访问
curl -X POST "${HOST}/createTask" \
  -H "Authorization: APPCODE YOUR_APPCODE" \
  -H "Content-Type: application/json" \
  -d '{"topic":"新能源汽车行业上半年发展综述","lang":"1"}'

8. 接入工程要点

• 重试策略：仅对网络错误与 5xx 做重试，采用指数退避；4xx（参数错误、鉴权失败）不应重试，需先修正请求。
• 幂等：createTask 每次调用都会产生新任务，客户端应基于业务主键去重，避免重复提交造成多余计量。
• 超时与兜底：设置合理的连接与读取超时；对返回结构做字段存在性判断，缺失关键字段时进入异常分支而非直接取值。
• 密钥安全：APPCODE / AppKey 通过环境变量或密钥管理服务注入，不写入源码与前端；服务端调用时避免将其下发到不可信环境。
• 结果轮询：提交后按 task_status 轮询，状态变为 success 再读取正文；轮询间隔递增并设上限，避免空转。

9. 技术 FAQ

Q：topic 是必填吗？不传会怎样？
是必填项。缺失 topic 时网关会返回参数校验错误（showapi_res_code 非 0），需补全后重试。

Q：lang 缺省是什么语言？
缺省按中文处理；传入 2 时生成英文内容。

Q：调用 createTask 后返回里没有正文，正常吗？
正常。该接口为异步提交模型，仅返回 task_id 与任务状态，正文需通过任务查询类接口在 task_status 变为 success 后获取。

Q：APPCODE 与 AppKey 有什么区别？
APPCODE 是简单身份认证，适合服务端到服务端直接调用；AppKey & AppSecret 签名认证在请求侧做签名，适合对调用来源有更强约束要求的场景。两者选其一即可。

Q：返回非 200 会计入调用次数吗？
根据网关计量规则，仅当 HTTP 响应状态码为 200 时计入调用次数，非 200 不计入。

Q：如何控制调用频率？
在客户端做令牌桶或信号量限流，并对 5xx 与频率受限错误做退避，避免短时突发超过配额。

10. 小结

本文以长文智能生成接口为样例，梳理了异步任务型内容生成接口的通用接入链路：明确 createTask 的提交—轮询—取数模型，掌握 topic / reference_list / lang 三个请求字段与 showapi_res_body 中的任务标识、状态字段，理解网关通用错误的排查方式，并在多语言示例基础上落实重试退避、幂等、超时兜底与密钥安全等工程化要点。这套思路可迁移到同类异步内容生成接口的接入工作中。