# IP视频封面 API Documentation

> 根据口播文案自动提炼主副标题并生成竖版 IP 封面。支持同一接口创建（默认）与查询（action=query）。统一按次计费（默认 30 点，查询不扣费）。

## Overview

This document describes how to call the **IP视频封面** API.

- **Model / path slug**: `image/ip_cover`
- **Task type**: `async` (`sync` = synchronous, `async` = create task then poll / callback)
- **HTML docs**: `/doc/55`

## Authentication

All API requests require your platform API key as the query parameter `key`:

```
?key=YOUR_API_KEY
```

Get API Key:
1. Sign in to the console
2. Open [API Key Management](/user/key) and create or copy your key
3. Append `key=YOUR_API_KEY` to the request URL (or pass it in form/JSON when the endpoint accepts it)

---

## API Information

- **URL**: `GET|POST https://apis.xiaobao.ink/api/image/ip_cover`
- **Content-Type**: `application/json` (request body commonly `application/json` or `application/x-www-form-urlencoded` for POST)
- **HTTP Method**: `GET / POST`
- **Note**: This endpoint accepts both GET query parameters and POST form/JSON body.

### Request Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `action` | Yes | create\|query，默认 create |
| `task_id` | Yes | 查询时必填 |
| `script` | Yes | 创建：口播文案 |
| `title` | No | 主标题可选 |
| `subtitle` | No | 副标题可选 |
| `person_url` | No | 人物参考可选 |
| `cover_url` | No | 封面参考可选 |
| `notify` | No | 回调可选 |

> **Note**: `key` (API key) is required for authenticated calls even if omitted from the parameter list above.

### Request Example

```
https://apis.xiaobao.ink/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`。

## 请求参数说明：

| 名称 | 必填 | 类型 | 示例值 | 说明 |
| --- | --- | --- | --- | --- |
| 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](/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://apis.xiaobao.ink/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

```json
{
    "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 | 服务端异常或密钥未配置 |

## Usage Flow

1. **Create Task**: Call this API with your `key` and required parameters
2. **Get Task ID**: Read the task id from the response
3. **Wait for Results**: Use the notify/callback URL if provided, or poll the related query endpoint
4. **Get Results**: When the task succeeds, read result URLs / payload from the response

---

_Generated for AI / LLM consumption. Source of truth: `api_list` (same as HTML `/doc/{id}`)._