API Reference

IP video cover API

REQUEST ip-cover-api ID 55

Turn a spoken script into a title pair and a vertical 9:16 cover, using a reference photo.

REQUEST https://xiaoapis.com/api/image/ip_cover

Get an API key Console / try it Open Markdown

Overview

口播文案 AI 提炼主标题 / 副标题 / 发布文案 / 话题
人物参考图保持五官一致
无参考图时可按文案场景文生封面
竖版 9:16、image2 1K 快速版
异步任务：立即返回 task_id，支持 notify 回调与任务查询轮询
统一按次计费，内部提炼与出图不对用户二次扣费

Use cases

视频号 / 抖音口播首帧封面
个人 IP / 讲师人设海报
Agent 自动「文案→标题→封面」
批量短视频封面生产
已有封面改版与标题重写

Conventions

Gateway · https://xiaoapis.com
Auth · send key (query or JSON body, as this API specifies)
Response · JSON. Check the business code and the HTTP status, not only HTTP 200

Authentication

Send the platform API key (query parameter key or JSON field key, as this page specifies). Create one in API key management.

REQUEST https://xiaoapis.com/api/image/ip_cover
Content-Type: application/json

{
  "key": "YOUR_API_KEY"
}

Request example

https://xiaoapis.com/api/image/ip_cover?key=你的密钥

Details

接口说明：

IP视频封面：先用 AI 从口播文案（可选封面图）提炼主标题/副标题/发布文案/话题，再用 image2 模型生成 1K 快速版竖版 9:16 封面海报。

灵活入参：

人物照 + 标题 + 副标题
封面 + 文案（AI 提取标题）
仅文案（AI 提取标题，按场景文生封面）
文案 + 人物参考（AI 标题 + 人物一致封面）

创建成功立即返回 task_id；封面完成后通过 notify 回调，或见下方「任务查询说明」：同一 URL 传 action=query + task_id 轮询（查询不扣费）。

计费：本接口统一扣除 30 点（可后台调整）；内部提炼标题与出图不对用户二次计费；失败不扣费。

请求HEADER：

名称	值
Content-Type	application/json

鉴权说明：

key 可放在 URL 查询参数、JSON Body，或 Authorization: Bearer <key>。

请求参数说明：

名称	必填	类型	示例值	说明
action	否	string	query	create（默认）或 query
task_id	查询时必填	string	ip_xxx	创建返回的任务ID
key	是	string	你的密钥	平台 API Key
script	条件	string	口播全文……	口播文案；无 title 时建议必填（别名 content/text）
title	条件	string	短视频稳定获客法	主标题≤12字纯文字；不传则 AI 提炼（别名 main_title）
subtitle	否	string	不靠运气靠方法	副标题≤20字；不传且走 AI 时自动生成
person_url	否	string	https://xx/face.jpg	人物参考图，保持五官一致
cover_url	否	string	https://xx/cover.jpg	已有封面；可辅助 AI 提取，无人物时也可作参考
notify	否	string	https://xx/callback	回调地址可选；也可用本接口 action=query 轮询
publish_text	否	string		发布文案；不传且走 AI 时返回
topics	否	string	#标签1 #标签2	话题；不传且走 AI 时返回
urls	否	array	["人物","封面"]	兼容：第1个人物图，第2个封面图

创建请求示例：

{"key":"你的密钥","script":"很多人问我为什么能把短视频做成稳定获客……","person_url":"https://你的域名/person.jpg","notify":"https://你的域名/callback"}

任务查询说明：

本接口同时支持创建与查询，无需另调其它 URL：

显式查询：传 action=query + task_id（创建返回的 ip_*）
自动识别：仅传 task_id（无 script/title/人物图等创建素材）时，按查询处理
查询不扣费；建议间隔 2～5 秒轮询，直到 status 为 1 或 2
兼容独立入口：/doc/56 /api/image/ip_cover_query

查询请求示例（GET）：

GET /api/image/ip_cover?action=query&task_id=ip_xxx&key=你的密钥

查询请求示例（JSON POST）：

{
  "key": "你的密钥",
  "action": "query",
  "task_id": "ip_xxx"
}

查询返回示例：

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "task_id": "ip_xxx",
    "status": 1,
    "progress": 100,
    "image_url": "https://xiaoapis.com/upload/image/....png",
    "main_title": "短视频稳定获客法",
    "sub_title": "不靠运气靠方法",
    "title_from_ai": true,
    "fail_reason": "",
    "power_cost": 30
  }
}

查询返回字段：

名称	类型	说明
data.task_id	string	任务 ID
data.status	int	0 处理中 / 1 成功 / 2 失败
data.progress	int	进度 0～100
data.image_url	string	封面地址（成功时有值）
data.main_title	string	主标题
data.sub_title	string	副标题
data.fail_reason	string	失败原因（失败时有值）
data.power_cost	number	本任务扣点

返回参数说明：

名称	类型	说明
code	int	状态码，200 表示成功
msg	string	状态信息
data.task_id	string	封面异步任务 ID
data.main_title	string	主标题
data.sub_title	string	副标题
data.publish_text	string	发布文案
data.topics	string	话题标签
data.title_from_ai	boolean	标题是否由 AI 提炼
data.power_cost	number	本次扣除点数

Response example

{"code":200,"msg":"任务创建成功","data":{"id":123,"task_id":"i44bcf50-f2d0-4c26-a467-26f2014a771b","main_title":"短视频稳定获客法","sub_title":"不靠运气靠方法","publish_text":"很多人问我短视频怎么稳定获客，其实方法很简单。","topics":"#短视频获客 #私域引流 #内容营销","title_from_ai":true,"power_cost":30}}

Error codes

HTTP / 业务码	说明
200	任务创建成功
400	参数错误、余额不足、标题提取失败或出图失败
401 / 403	认证失败，请检查 key
500	服务端异常或密钥未配置

FAQ

什么是 IP 视频封面 API？

面向短视频/视频号场景的封面生产能力：可从口播文案自动创作主副标题，再结合人物照片生成竖版 IP 封面海报，适合作为发布首帧。

IP 视频封面 API 怎么调用？

POST /api/image/ip_cover，携带 API Key 与 script（或 title）。提交后立即返回 task_id；可用 notify 回调，或调用任务查询接口 /doc/56 按 task_id 轮询。

传文案后要等标题提炼完才返回吗？

不用。创建接口会立即返回 task_id；系统在后台先提炼标题再提交出图。

如何通过 task_id 查询结果？

调用同一接口 /api/image/ip_cover，传 action=query 与创建返回的 task_id（也可只传 task_id）。status：0 处理中，1 成功，2 失败。查询不扣费。兼容独立入口 /doc/56。

可以只传文案不传人物照吗？

可以。未提供 person_url / cover_url 时，会按标题与文案语义生成对应场景的竖版封面。

标题必须自己写吗？

不必。不传 title 时，接口会用 AI 根据口播文案（可选封面图）提炼主标题、副标题、发布文案与话题；也可自行传入 title/subtitle 跳过提炼。

和 AI 图像接口有什么区别？

AI 图像（/doc/13）是通用文生图/参考图生成；IP 视频封面专做「标题提炼 + 竖版人物海报」编排，出参直接带主副标题，适合口播发布链路。

怎么计费？会不会再扣 Terra / 图像费用？

本接口统一按次扣点（默认 30 点，以控制台为准）。内部标题提炼与出图直连上游，不对用户二次计费，不会记入 Terra 或 AI 图像接口额度。

封面比例和清晰度是多少？

固定竖版 9:16，image2 模型 1K 快速版，适合视频号/抖音首帧。

如何拿到生成结果？

创建返回 task_id 后：① 同一接口 action=query 轮询；② 或填写 notify 接收完成回调（含标题与 image_url）。

画面上会出现口播全文吗？

不会。硬性约束画面文字有且只有主标题（及副标题），不会绘制口播全文、话题标签、水印或 Logo。

适合 AI Agent 吗？

适合。Agent 可读 /model/image/ip_cover.md 与 /model/image/ip_cover_query.md，创建后按 task_id 轮询即可。

Full console doc (with the debugger):/doc/55