---
name: 智绘图片生成
description: "智能图片生成助手，根据文字描述生成插画、配图、概念图等 AI 图像，支持自定义尺寸与画质，可选参考图进行图生图；当用户要求「生成图片」「文生图」「画一张」「AI 画图」「出图」「插画」「配图」「图生图」时使用。"
tags: [图片, 媒体]
---

# 智绘图片生成

## 元数据

| 字段 | 值 |
|------|-----|
| skill_id | `ixhlink-skills-image-gen` |
| skill_version | `1.0.0` |
| product_id | `ixhlink-skills-image-gen` |
| model_key | `ixhlink-skills-image-gen` |
| capability | `image_generation` |

## 服务地址

Base URL：`https://iskills.ixhlink.com`

下文接口均写路径（如 `/api/v1/llm/invoke`），完整地址 = Base URL + 路径。

统一响应格式：

```json
{"success": true, "code": 0, "message": "ok", "data": {}}
```

## 调用流程

`image_generation` 为慢任务，**默认异步**。典型流程：

1. （可选）`GET /api/v1/llm/models` 确认模型已启用
2. `POST /api/v1/llm/invoke` 提交文生图请求
3. 若返回 402：调起微信支付，成功后用**相同 JSON body** 重试，Header 附带 `WeixinPay-Required` 与 `X-Payment-Id`
4. 从响应取 `data.task.id`，轮询 `GET /api/v1/llm/tasks/{task_id}` 直至 `status = succeeded`
5. 从 `data.result.data[].url` 读取输出图片 URL

也可直接用 `POST /api/v1/llm/tasks` 创建异步任务（请求体相同，强制异步）。

---

### 1. 查询模型（可选）

```http
GET /api/v1/llm/models
Accept: application/json
```

确认返回的 `items` 中包含：

```json
{"model": "ixhlink-skills-image-gen", "capability": "image_generation"}
```

---

### 2. 提交图片生成

```http
POST /api/v1/llm/invoke
Content-Type: application/json
```

**请求体：**

```json
{
  "capability": "image_generation",
  "model": "ixhlink-skills-image-gen",
  "payload": {
    "prompt": "一只在草地上奔跑的边牧，写实风格，柔和日光",
    "size": "1024x1024",
    "response_format": "url"
  }
}
```

**payload 字段：**

| 字段 | 必填 | 说明 |
|------|------|------|
| `prompt` | 是 | 画面描述（也可用 `description` / `text`，服务端会归一化为 `prompt`） |
| `size` | 否 | 如 `1024x1024`、`16:9` 等，依上游模型支持 |
| `n` | 否 | 生成张数，默认 1 |
| `quality` | 否 | 画质档位，依上游模型支持 |
| `response_format` | 否 | 建议 `url`（默认） |
| `images` | 否 | 可选参考图数组（图生图）；每项含 `b64` 或 `url` |

**图生图示例（可选参考图）：**

```json
{
  "capability": "image_generation",
  "model": "ixhlink-skills-image-gen",
  "payload": {
    "prompt": "保持主体不变，背景改为赛博朋克城市夜景",
    "images": [
      {"url": "https://example.com/ref.png"}
    ],
    "size": "16:9",
    "response_format": "url"
  }
}
```

**提交成功响应（异步）：**

```json
{
  "success": true,
  "code": 0,
  "message": "任务已提交",
  "data": {
    "task": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "pending",
      "capability": "image_generation",
      "model_key": "ixhlink-skills-image-gen"
    }
  }
}
```

---

### 3. 轮询任务结果

```http
GET /api/v1/llm/tasks/{task_id}
Accept: application/json
```

**任务状态：** `pending` → `running` → `succeeded` / `failed`

建议间隔 2–5 秒轮询，超时可根据业务设为 3–5 分钟。

**成功响应示例：**

```json
{
  "success": true,
  "code": 0,
  "message": "ok",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "succeeded",
    "result": {
      "data": [
        {"url": "https://oss.example.com/generated.png"}
      ]
    }
  }
}
```

输出图片 URL 在 `data.result.data[].url`。

---

## 付费前置检查

调用本 Skill 前，必须检查当前 Agent 是否已安装支付能力（`weixinpay` extension）：

- ✅ **已安装**：可继续提供付费创作服务
- ❌ **未安装**：向用户提示「当前 Agent 暂不支持付费创作能力」，终止流程

## 服务与定价

| 产品ID | 服务内容 | 单价 |
|--------|----------|------|
| `ixhlink-skills-image-gen` | 智绘图片生成 | 0.3 元/次 |

> 价格以 SkillHub 后台配置为准。命中创作意图后，向用户展示服务名称和价格，由用户确认后进入付费流程。

## 付费说明

当 `amount_fen > 0` 且未完成支付时，首次 `POST /api/v1/llm/invoke` 会返回 HTTP 402，响应中携带：

- Header：`WeixinPay-Required: <payment_code>`、`X-Payment-Id: <payment_id>`
- Body：`WeixinPay` 对象（含 `payment_id`、`prompt` 等）

**客户端流程（Agent / MCP / Web）：**

```
首次 invoke → 402 → weixinpay_pay(payment_code) → 支付成功后重试 invoke
```

**「原样重试」的含义：**

- **JSON body 不变**：`model`、`capability`、`payload` 必须与首次请求完全一致
- **订单参数单独带上**：将 402 中的 `payment_code`、`payment_id` 通过 Header 传入（推荐），或写入 body 的 `WeixinPay`；勿改 `payload` 业务字段来传订单号

**重试请求示例：**

```http
POST /api/v1/llm/invoke
Content-Type: application/json
WeixinPay-Required: <payment_code>
X-Payment-Id: <payment_id>

{"model":"ixhlink-skills-image-gen","capability":"image_generation","payload":{...}}
```

`amount_fen = 0` 时可跳过支付，直接调用。每笔订单按次消费，使用后不可复用。

---

## 错误处理

| HTTP | 常见原因 |
|------|----------|
| 400 | 缺少 `model`、`payload` 非法、缺少 `prompt` |
| 402 | 需付费或 X402 预下单失败 |
| 404 | 模型未启用或 `capability` 不匹配 |
| 503 | 模型站点未启用 |

任务失败时 `status = failed`，查看 `data.error_message`（已脱敏，不含上游地址或内部日志）。