做节日活动页时，如何用 API 快速生成对联内容

最近整理节日活动、小程序互动、内容工具类功能时，经常会遇到一个很轻量但很有意思的需求：用户输入一句上联，系统自动生成一句可用的下联。

如果只是做一个 demo，当然可以直接把 prompt 丢给大模型；但如果要把它放进页面、后台工具、活动生成器里，最好还是封装成一个稳定的接口调用。极数本源 ApiZero 的 ai-couplet 接口就是这种定位：传入上联关键词，接口返回上联和 AI 生成的下联，整体接入非常轻。

官方页面：https://apizero.cn/marketplace/ai-couplet

这个接口适合做什么

ai-couplet 是一个智能对联生成 API。它的核心能力很直白：接收一个 keyword，返回结构化的 shanglian 和 xialian。

比较适合这些场景：

春节、中秋、开业、婚庆等活动页里的对联生成器
小程序、H5 页面里的趣味互动功能
内容工具站里的文案灵感生成模块
企业活动后台里的祝福语、标语、横幅素材辅助生成
AI 工作流中的中文创意文本生成节点

对开发者来说，它的好处是不用自己维护复杂的生成逻辑，只需要把用户输入转成一次 POST 请求，再把返回结果展示到页面上。

基本接入信息

接口地址：

text 复制代码

POST https://v1.apizero.cn/api/ai-couplet

请求头：

Header	必填	说明
`X-Api-Key`	否	携带 API Key 可获得更高调用频度和更快速率
`Content-Type`	建议	POST JSON 请求建议使用 `application/json`

请求参数：

参数	类型	必填	说明
`keyword`	string	是	上联关键词，官方说明为 1 到 30 字

最小请求示例：

bash 复制代码

curl -X POST "https://v1.apizero.cn/api/ai-couplet" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "春风拂面花自笑"
  }'

如果已经申请了 API Key，可以这样加请求头：

bash 复制代码

curl -X POST "https://v1.apizero.cn/api/ai-couplet" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "春风拂面花自笑"
  }'

2026-05-29 实测返回

我用匿名方式传入：

json 复制代码

{
  "keyword": "春风拂面花自笑"
}

拿到的返回如下：

json 复制代码

{
  "code": 0,
  "msg": "成功",
  "data": {
    "shanglian": "春风拂面花自笑",
    "xialian": "秋雨润心月常愁"
  },
  "request_id": "mpqmiseyf5d90e3b"
}

返回结构很好理解：

字段	类型	说明
`code`	number	状态码，`0` 表示成功
`msg` / `message`	string	状态说明。实测返回为 `msg`，官方示例中也可能出现 `message`
`data.shanglian`	string	本次输入或整理后的上联
`data.xialian`	string	AI 生成的下联
`request_id`	string	本次请求 ID，方便排查和日志追踪

实际开发时，我建议对状态说明字段做一层兼容：

javascript 复制代码

const message = data.msg || data.message || "";

这样即使不同文档示例或版本里字段名略有差异，业务展示层也不会太脆。

Python 调用示例

后端服务里可以封装成一个很小的函数：

python 复制代码

import requests


def generate_couplet(keyword: str, api_key: str | None = None) -> dict:
    headers = {
        "Content-Type": "application/json",
    }
    if api_key:
        headers["X-Api-Key"] = api_key

    resp = requests.post(
        "https://v1.apizero.cn/api/ai-couplet",
        headers=headers,
        json={"keyword": keyword},
        timeout=15,
    )
    resp.raise_for_status()
    result = resp.json()

    if result.get("code") != 0:
        raise RuntimeError(result.get("msg") or result.get("message") or "生成失败")

    return result["data"]


couplet = generate_couplet("春风拂面花自笑")
print("上联:", couplet["shanglian"])
print("下联:", couplet["xialian"])

页面展示时，可以直接把 shanglian 和 xialian 映射到两行文案：

text 复制代码

上联：春风拂面花自笑
下联：秋雨润心月常愁

JavaScript 调用示例

Node.js 18+ 或现代浏览器环境可以直接用 fetch：

javascript 复制代码

async function generateCouplet(keyword, apiKey) {
  const headers = {
    "Content-Type": "application/json",
  };

  if (apiKey) {
    headers["X-Api-Key"] = apiKey;
  }

  const res = await fetch("https://v1.apizero.cn/api/ai-couplet", {
    method: "POST",
    headers,
    body: JSON.stringify({ keyword }),
  });

  if (!res.ok) {
    throw new Error(`HTTP ${res.status}`);
  }

  const data = await res.json();
  if (data.code !== 0) {
    throw new Error(data.msg || data.message || "生成失败");
  }

  return data.data;
}

const result = await generateCouplet("春风拂面花自笑");
console.log(`上联：${result.shanglian}`);
console.log(`下联：${result.xialian}`);

如果是在前端页面里直接调用，建议把 API Key 放在服务端，不要硬编码到浏览器代码中。前端可以请求自己的后端接口，由后端再转发到 ApiZero，这样更方便做缓存、日志和调用频率控制。

接到业务里的一个简单思路

一个常见的实现流程可以这样设计：

用户在页面输入上联或关键词
前端做基础校验，比如不能为空、长度不超过 30 字
前端请求自己的后端接口
后端调用 ai-couplet
后端把 shanglian、xialian 返回给前端
前端展示结果，并提供复制、重新生成、保存图片等按钮

如果要提升体验，可以额外加两个小设计：

对相同输入做短时间缓存，避免用户连续点击时重复请求
给生成结果加"一键复制"和"重新生成"按钮，适合活动页和小程序互动

这类功能的难点通常不在接口调用，而在交互闭环：用户输入、等待、展示、复制或分享，整条链路越短，体验越好。