API Reference

IP 视频封面 API

REQUEST ip-cover-api ID 55

销豹 IP 视频封面 API 根据口播文案自动提炼主副标题，并用人物参考图生成竖版 9:16 视频号/抖音封面海报，一套接口完成「标题+封面」。

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

获取 API Key 工作台 / 调试打开 Markdown

概述

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

适用场景

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

调用约定

网关 · https://apis.xiaobao.ink
鉴权 · 请求携带 key（Query 或 JSON Body，以本接口为准）
回包 · JSON；请同时校验业务码与 HTTP 状态，不要只看 200

鉴权

请求需携带平台 API Key（查询参数 key 或 JSON 字段 key，以本接口说明为准）。在控制台 API Key 管理创建密钥。

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

{
  "key": "YOUR_API_KEY"
}

请求示例

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

详细说明

接口说明：

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	本次扣除点数

返回示例

{"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}}

错误码

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

常见问题

什么是 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 轮询即可。

完整控制台文档（含调试台）：/doc/55