# 内容生成技术参考

本文档提供图像和视频生成的完整技术参考。

## 图像生成 API

### generate_image

**完整签名**：
```python
generate_image(
    prompt: str,
    model: str = "z-image",
    size: str = "1:1",
    steps: int = 30,
    negative_prompt: Optional[str] = None
) -> Dict[str, Any]
```

**参数详解**：

- `prompt` (str, 必需)
  - 图像描述文本
  - 建议长度：50-200 字
  - 支持中英文
  - 建议包含：主体 + 风格 + 质量词

- `model` (str, 可选，默认 "z-image")
  - `z-image`: 通用模型，速度快，质量高
  - `wan2.6-image`: 动漫风格专用
  - `qwen-image`: 写实风格专用
  - 选择建议：根据目标风格选择

- `size` (str, 可选，默认 "1:1")
  - `1:1` (1024x1024): 方形，头像、图标
  - `16:9` (1344x768): 横向，风景、场景
  - `9:16` (768x1344): 竖向，人物、手机壁纸
  - `4:3` (1152x896): 传统横向
  - `3:4` (896x1152): 传统竖向

- `steps` (int, 可选，默认 30)
  - 范围：20-100
  - 20-30: 快速预览
  - 30-50: 标准质量（推荐）
  - 50-100: 高质量精细
  - 注意：步数越高，生成时间越长

- `negative_prompt` (str, 可选)
  - 不希望出现的元素
  - 示例：`"低质量, 模糊, 变形, 多余的手指"`
  - 仅部分模型支持

**返回值**：
```python
{
    "image_url": "https://...",  # 图像 URL
    "width": 1024,               # 宽度
    "height": 1024,              # 高度
    "model": "z-image",          # 使用的模型
    "seed": 12345                # 随机种子（如果支持）
}
```

**错误代码**：
- `400`: 参数错误（提示词为空、尺寸不支持等）
- `429`: 请求过于频繁
- `500`: 生成失败（模型错误、超时等）

### generate_images_batch

**完整签名**：
```python
generate_images_batch(
    prompts: List[str],
    model: str = "z-image",
    size: str = "1:1",
    steps: int = 30
) -> List[Dict[str, Any]]
```

**参数详解**：

- `prompts` (List[str], 必需)
  - 多个提示词列表
  - 建议数量：2-10 个
  - 每个提示词遵循 `generate_image` 的规则

- 其他参数同 `generate_image`

**返回值**：
```python
[
    {"image_url": "...", "width": 1024, "height": 1024},
    {"image_url": "...", "width": 1024, "height": 1024},
    ...
]
```

**性能优化**：
- 批量生成比多次单独调用快 30-50%
- 建议一次不超过 10 个
- 超过 10 个考虑分批处理

## 视频生成 API

### generate_video

**完整签名**：
```python
generate_video(
    prompt: str,
    model: str = "wan2.6-video",
    duration: int = 6,
    size: str = "16:9",
    image_url: Optional[str] = None
) -> Dict[str, Any]
```

**参数详解**：

- `prompt` (str, 必需)
  - 视频描述文本
  - 建议长度：50-300 字
  - 必须包含：场景 + 动作 + 镜头运动
  - 示例：`"小猫在草地上奔跑，镜头跟随，阳光明媚"`

- `model` (str, 可选，默认 "wan2.6-video")
  - `wan2.6-video`: 通用高质量（推荐）
  - `wan2.6-video-flash`: 快速生成
  - `kling-v2-6`: 复杂运动场景

- `duration` (int, 可选，默认 6)
  - 范围：5-10 秒
  - 5 秒：快速动作、特写
  - 6 秒：标准镜头（推荐）
  - 10 秒：完整场景

- `size` (str, 可选，默认 "16:9")
  - `16:9`: 横屏视频
  - `9:16`: 竖屏视频
  - `1:1`: 方形视频

- `image_url` (str, 可选)
  - 起始帧图像 URL
  - 用于图生视频模式
  - 如果提供，视频将从此图像开始

**返回值**：
```python
{
    "video_url": "https://...",  # 视频 URL
    "duration": 6,               # 时长（秒）
    "width": 1344,               # 宽度
    "height": 768,               # 高度
    "model": "wan2.6-video",     # 使用的模型
    "fps": 24                    # 帧率
}
```

**错误代码**：
- `400`: 参数错误
- `413`: 提示词过长
- `429`: 请求过于频繁
- `500`: 生成失败

### create_image_to_video_workflow

**完整签名**：
```python
create_image_to_video_workflow(
    image_prompt: str,
    video_prompt: str,
    style: str = "anime"
) -> Dict[str, Any]
```

**参数详解**：

- `image_prompt` (str, 必需)
  - 图像生成提示词
  - 用于生成起始帧

- `video_prompt` (str, 必需)
  - 视频生成提示词
  - 描述动作和运动

- `style` (str, 可选，默认 "anime")
  - 视觉风格
  - 影响图像和视频的生成

**返回值**：
```python
{
    "workflow_id": "...",        # 工作流 ID
    "image_node_id": "...",      # 图像节点 ID
    "video_node_id": "...",      # 视频节点 ID
    "status": "created"          # 状态
}
```

## 模型对比

### 图像生成模型

| 模型 | 风格 | 速度 | 质量 | 适用场景 |
|------|------|------|------|----------|
| z-image | 通用 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 默认选择，平衡性能 |
| wan2.6-image | 动漫 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 二次元角色、动漫场景 |
| qwen-image | 写实 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 真实场景、人物摄影 |

### 视频生成模型

| 模型 | 速度 | 质量 | 运动复杂度 | 适用场景 |
|------|------|------|------------|----------|
| wan2.6-video | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 默认选择，高质量 |
| wan2.6-video-flash | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | 快速预览 |
| kling-v2-6 | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 复杂运动、高要求 |

## 尺寸规格

### 图像尺寸

| 比例 | 分辨率 | 像素数 | 适用场景 |
|------|--------|--------|----------|
| 1:1 | 1024x1024 | 1.05M | 头像、图标、方形构图 |
| 16:9 | 1344x768 | 1.03M | 横向场景、风景、电影 |
| 9:16 | 768x1344 | 1.03M | 竖向人物、手机壁纸 |
| 4:3 | 1152x896 | 1.03M | 传统横向、人物半身 |
| 3:4 | 896x1152 | 1.03M | 传统竖向、人物全身 |

### 视频尺寸

| 比例 | 分辨率 | 适用场景 |
|------|--------|----------|
| 16:9 | 1344x768 | 横屏视频，电脑观看 |
| 9:16 | 768x1344 | 竖屏视频，手机短视频 |
| 1:1 | 1024x1024 | 方形视频，社交媒体 |

## 提示词工程

### 质量关键词库

**通用质量词**：
```
masterpiece, best quality, highly detailed,
ultra HD, 8K, professional, perfect composition,
sharp focus, vivid colors, high resolution
```

**光照效果**：
```
cinematic lighting, soft lighting, dramatic lighting,
natural light, golden hour, studio lighting,
rim lighting, volumetric lighting
```

**艺术风格**：
```
anime style, realistic style, cartoon style,
oil painting, watercolor, digital art,
concept art, photorealistic, illustration
```

**镜头效果**：
```
depth of field, bokeh, shallow focus,
wide angle, telephoto, macro,
low angle, high angle, eye level
```

### 负面提示词库

**通用负面词**：
```
low quality, blurry, distorted, deformed,
ugly, bad anatomy, bad proportions,
duplicate, watermark, signature, text
```

**人物负面词**：
```
extra fingers, missing fingers, extra limbs,
bad hands, bad face, asymmetric eyes,
unrealistic skin, bad teeth
```

**场景负面词**：
```
cluttered, messy, chaotic, unnatural colors,
poor composition, bad perspective,
overexposed, underexposed
```

## 性能基准

### 生成时间（参考）

**图像生成**：
- 20 steps: ~5-10 秒
- 30 steps: ~10-15 秒
- 50 steps: ~15-25 秒
- 100 steps: ~30-60 秒

**视频生成**：
- 5 秒视频: ~30-60 秒
- 6 秒视频: ~40-80 秒
- 10 秒视频: ~60-120 秒

**批量生成**：
- 单次 5 张: ~50-75 秒（比单独生成快 30%）
- 单次 10 张: ~100-150 秒（比单独生成快 40%）

### 成本估算（Token 消耗）

**图像生成**：
- 单张图像: ~1000 tokens
- 批量 5 张: ~3000 tokens
- 批量 10 张: ~5000 tokens

**视频生成**：
- 5 秒视频: ~5000 tokens
- 6 秒视频: ~6000 tokens
- 10 秒视频: ~10000 tokens

## 错误处理

### 常见错误及解决方案

**错误 1: "Prompt too short"**
- 原因：提示词少于 10 个字
- 解决：添加更多描述细节

**错误 2: "Invalid size"**
- 原因：尺寸参数不在支持列表中
- 解决：使用标准尺寸（1:1, 16:9, 9:16, 4:3, 3:4）

**错误 3: "Model not available"**
- 原因：模型名称错误或模型不可用
- 解决：检查模型名称拼写，使用默认模型

**错误 4: "Generation timeout"**
- 原因：生成时间过长
- 解决：降低 steps 参数，或稍后重试

**错误 5: "Content policy violation"**
- 原因：提示词包含不当内容
- 解决：修改提示词，移除敏感内容

### 重试策略

**建议重试次数**：
- 图像生成：最多 3 次
- 视频生成：最多 2 次

**重试间隔**：
- 第 1 次重试：立即
- 第 2 次重试：等待 5 秒
- 第 3 次重试：等待 10 秒

**指数退避**：
```python
import time

def generate_with_retry(func, max_retries=3):
    for i in range(max_retries):
        try:
            return func()
        except Exception as e:
            if i == max_retries - 1:
                raise
            wait_time = 2 ** i  # 1, 2, 4 秒
            time.sleep(wait_time)
```

## 最佳实践总结

### 图像生成

1. **提示词长度**：50-200 字最佳
2. **质量词**：始终添加质量关键词
3. **步数**：30-50 步平衡质量和速度
4. **批量生成**：相似任务使用批量 API
5. **预览优先**：先低步数预览，确认后高质量生成

### 视频生成

1. **提示词结构**：场景 + 动作 + 镜头 + 氛围
2. **运动描述**：明确描述运动方式和速度
3. **时长选择**：6 秒是最佳平衡点
4. **图生视频**：先生成高质量图像，再转视频
5. **镜头运动**：避免过于复杂的镜头运动

### 性能优化

1. **缓存结果**：保存成功的生成结果
2. **参数复用**：记录成功的参数组合
3. **批量处理**：合并相似任务
4. **异步生成**：长时间任务使用异步模式
5. **错误处理**：实现重试机制

## 参考资料

- [图像生成 API 文档](https://example.com/image-api)
- [视频生成 API 文档](https://example.com/video-api)
- [提示词工程指南](https://example.com/prompt-guide)
