儿童AI成语卡片生成接口技术解析：接入流程、参数设计与异步结果获取

本文为面向开发者的技术教程，介绍云市场「儿童 AI 成语卡片生成」接口的能力定位、接入方式与返回结构。内容基于商品页公开文档与在线调试返回整理，仅作技术参考。

一、技术简介

儿童 AI 成语卡片生成接口是一个面向教育场景的工作流类 API。调用方传入一个成语、目标年龄段与画面比例，接口先对输入做意图解析与儿童内容安全审查，再按年龄段改写适龄化的成语释义故事并生成朗读节奏指引；随后产出配图提示词，并行调用文生图与文生音频能力，生成含中文大字的配图与缓慢朗读音频；最后将文本、图片、音频融合为一张可直接用于启蒙教学的学习卡片。

接口采用「创建任务 + 轮询结果」的异步模式：先通过创建接口拿到任务标识，再周期性查询任务状态，待状态变为成功且进度达到 100 后取回完整结果。该模式适合在家长端、小程序、教学系统中按需调用，也便于在后端做结果缓存与重试。

二、能力概览

该接口围绕「一张可用的儿童成语学习卡片」组织能力，核心处理环节如下：

说明：上述能力环节对应返回结构中的多个处理步骤（step），最终由卡片融合步骤汇总。

三、适用场景

• 儿童启蒙 APP / 小程序：根据用户输入的成语即时生成学习卡片，作为日更内容或互动素材。
• 亲子共读：家长输入成语，系统返回适龄故事、配图与朗读音频，辅助家庭阅读。
• 语文素养培养：作为教学辅助素材，提供释义、故事、造句与配图一体化内容。
• 教具图生成：按展示比例（如 16:9、4:3）产出可用于课件或印刷的卡片图。

四、接入流程

整体接入分为开通、调用、轮询三步：

1. 在云市场开通该接口商品，于控制台获取 AppCode（简单身份认证凭证）。
2. 构造 POST 请求，在 Header 中携带 Authorization: APPCODE <appcode>。
3. 在 Body 中传入 idiom、age_group、aspect_ratio 三个字段。
4. 调用创建接口 POST /idiom/execute，拿到任务标识。
5. 以任务标识拼接查询接口路径，轮询 GET /idiom/query/{task_id}。
6. 当返回 status 为 SUCCESS 且 progress 为 100 时，解析 flow_result 取配图地址、音频地址与故事文本。

调用地址（host）为云市场商品页提供的网关域名，登录控制台后可在「接口信息」中查看，本文示例仅保留路径。

五、调用示例与返回结构

5.1 请求参数

创建接口 POST /idiom/execute，请求体为 JSON：

查询接口 GET /idiom/query/{task_id}，task_id 为路径参数。

5.2 多语言调用示例

Python

import requests, time

HOST = "<网关地址>"          # 云市场商品页控制台查看
APPCODE = "<appcode>"       # 控制台获取的 AppCode

headers = {
   "Authorization": f"APPCODE {APPCODE}"}

# 1. 创建任务
create_resp = requests.post(
    f"{HOST}/idiom/execute",
    headers=headers,
    json={
   "idiom": "狐假虎威", "age_group": "5-7岁", "aspect_ratio": "1:1"},
)
body = create_resp.json()["showapi_res_body"]
task_id = body["task_id"]

# 2. 轮询结果
while True:
    q = requests.get(f"{HOST}/idiom/query/{task_id}", headers=headers).json()
    b = q["showapi_res_body"]
    if b["status"] == "SUCCESS" and b["progress"] == 100:
        break
    time.sleep(3)

fr = b["flow_result"]
image_url = fr["step_4_poll_image_status"]["result"]["data"]["result_url"]
print("配图地址:", image_url)

Java

import java.net.http.*;
import java.net.URI;

public class IdiomCard {
   
    static final String HOST = "<网关地址>";
    static final String APPCODE = "<appcode>";

    public static void main(String[] args) throws Exception {
   
        var client = HttpClient.newHttpClient();
        var req = HttpRequest.newBuilder()
            .uri(URI.create(HOST + "/idiom/execute"))
            .header("Authorization", "APPCODE " + APPCODE)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(
                "{\"idiom\":\"狐假虎威\",\"age_group\":\"5-7岁\",\"aspect_ratio\":\"1:1\"}"))
            .build();
        var resp = client.send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(resp.body());
    }
}

Node.js

const axios = require("axios");

const HOST = "<网关地址>";
const APPCODE = "<appcode>";

async function create() {
   
  const r = await axios.post(`${
     HOST}/idiom/execute`, {
   
    idiom: "狐假虎威", age_group: "5-7岁", aspect_ratio: "1:1"
  }, {
    headers: {
    Authorization: `APPCODE ${
     APPCODE}` } });
  return r.data.showapi_res_body.task_id;
}
create().then(id => console.log("task_id:", id));

PHP

<?php
$host = "<网关地址>";
$appcode = "<appcode>";
$ch = curl_init("$host/idiom/execute");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ["Authorization: APPCODE $appcode", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(["idiom"=>"狐假虎威","age_group"=>"5-7岁","aspect_ratio"=>"1:1"]),
  CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);

5.3 返回结构说明

创建接口返回任务标识（字段名以控制台成功响应为准，常见为 task_id）；查询接口返回统一信封，关键字段如下：

{
   
  "showapi_res_id": "6a5d94c53c51f2492b00a536",
  "showapi_res_error": "",
  "showapi_res_body": {
   
    "status": "SUCCESS",
    "flow_name": "儿童成语学习卡片生成",
    "steps_num": 8,
    "progress": 100,
    "flow_result": {
   
      "step_1_idiom_content_adapter": {
   
        "result": {
    "data": {
   
          "result": "狐假虎威的意思是狐狸借着老虎的威风去吓唬别人……",
          "content_variants": [
            {
    "content": "趣味故事文本", "style": "趣味故事", "score": 0.95 }
          ]
        } }
      },
      "step_4_poll_image_status": {
   
        "result": {
    "data": {
   
          "result_url": "<图片资源地址>",
          "task_status": "SUCCEEDED"
        } }
      },
      "step_7_card_data_merger": {
   
        "result": {
    "data": {
   
          "result": "成语学习卡片融合完成",
          "structured_analysis": {
   
            "semantic_structure": {
   
              "core_theme": "狐假虎威",
              "logical_flow": "标题-读音-释义-故事-配图-造句"
            }
          }
        } }
      }
    }
  }
}

要点：

• 信封层 showapi_res_body 承载业务结果；status / progress 标识任务完成度。
• 故事文本与释义在 step_1_idiom_content_adapter；配图地址在 step_4_poll_image_status.result.data.result_url；朗读音频在文生音频对应步骤；卡片融合摘要在 step_7_card_data_merger。
• 不同成语返回的步骤集合一致，但 content_variants 内容与 core_theme 随输入变化。

六、在线调试实录

在商品页「API 调试」中，选择「创建任务」填入 {"idiom":"为虎作伥","age_group":"5-7岁","aspect_ratio":"1:1"}，发送后得到任务标识；切到「查询任务」填入 task_id，待 progress 达到 100、status 为 SUCCESS 后，可看到：

• flow_result.step_1 返回适龄故事与释义，含多个 content_variants（趣味故事、生活造句）及其置信度；
• flow_result.step_4 返回配图 result_url 与 task_status: SUCCEEDED；
• flow_result.step_7 返回卡片融合结果，logical_flow 形如「标题-读音-释义-故事-配图-造句」。

调试时建议先用常见四字成语验证整体链路，再扩展到生僻成语。

七、调用限制与规范

• 认证：仅支持 APPCODE 简单身份认证，凭证通过 Authorization 头传递，勿写入 URL 或日志。
• 异步约束：创建与查询为两个独立接口，务必以 task_id 轮询，不要在创建后立即读取结果。
• 轮询间隔：建议 2–5 秒一次，避免过密请求触发频率限制。
• 频次：单账户 QPS 与每日配额以控制台实时配置为准；批量场景应做客户端限流与排队。
• 超时与重试：查询接口建议设置合理超时；任务处于 RUNNING 时仅重试查询，不要重复创建。
• 合规：传入内容应合法合规，接口已内置儿童安全审查，但仍建议调用方对输入做基础校验。

八、能力边界与免责

• 支持：给定常见四字成语，生成适龄故事、配图与朗读音频；按三档年龄段与五种比例输出。
• 不支持：非成语输入、超出支持年龄段的精确年级映射、对生成内容的二次风格强约束（如指定画师）。
• 边界：生成内容由模型产生，释义与故事为辅助教学素材，不构成权威释义；配图与音频为自动生成，使用前建议人工预览。
• 免责：接口返回内容仅供参考，不对因使用生成内容产生的任何业务或教学决策承担责任；调用方须自行评估内容适用性并承担最终责任。

九、错误码排查

该商品页未提供独立错误码表，异常通常按网关统一约定处理：

排查时优先查看返回体中的 showapi_res_error 与步骤级 message 字段。

十、技术 FAQ

Q1：返回里没有立即出现配图地址，正常吗？
正常。接口为异步工作流，需先创建任务拿到 task_id，再轮询查询接口，待 progress 为 100 后才有完整 flow_result。

Q2：年龄段怎么选？
3-4岁 偏启蒙、5-7岁 基础、8-10岁 进阶；差异体现在释义深度与画风，按受众选择即可。

Q3：画面比例有哪些？
默认 1:1，另支持 16:9、4:3、3:4、9:16，按展示位（卡片、横幅、手机竖屏）选择。

Q4：返回结构里 step 很多，关键取哪些？
故事与释义看 step_1，配图地址看 step_4 的 result_url，朗读音频看文生音频步骤，融合摘要看 step_7。

Q5：如何做工程化接入？
建议封装「创建→轮询→解析」三步，加入前置参数校验、轮询上限、结果缓存与失败告警；多任务场景用队列削峰。

Q6：调用地址在哪里获取？
登录云市场商品页控制台，在「接口信息」中查看网关域名与认证入口。

十一、内容小结

本文梳理了儿童 AI 成语卡片生成接口的接入方式：以 idiom / age_group / aspect_ratio 三参数经 POST /idiom/execute 创建任务，再以 task_id 轮询 GET /idiom/query/{task_id} 取回融合后的故事、配图与音频。工程接入时关注异步轮询、频次控制、凭证安全与内容预览，可较快完成系统集成。返回结构以 showapi_res_body.flow_result 承载各步骤结果，按步骤键取用即可。