cang-ying/bingshuo-heartbeat/skills/SKILL-002-API调用手册.hdlp

# SKILL-002 · API调用手册（火山/可灵/万相）

> trigger: 需要调用图片/视频生成API时自动加载
> emergence: 2026-07-15 · D186
> lock: 三个API全部核对通过 · 可直接调用

---

## §0 密钥存储位置

```
️ API密钥不进仓库！存在本地电脑！

密钥文件: ~/Documents/guanghulab-local-secrets/shortdrama-api.env
核对报告: ~/Documents/guanghulab-local-secrets/shortdrama-api-report.md

读取方式: source ~/Documents/guanghulab-local-secrets/shortdrama-api.env
然后使用: $VOLCENGINE_API_KEY, $KLING_API_KEY, $WANXIANG_API_KEY
```

## §1 火山方舟（字节跳动）

### 1.1 图片生成
```bash
# 即梦3.0（1000张额度）
curl -s "https://ark.cn-beijing.volces.com/api/v3/images/generations" \
  -H "Authorization: Bearer ${VOLCENGINE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"model":"doubao-seedream-4-0-250828","prompt":"描述","size":"1024x1024"}'

# 即梦5.0 Pro（高质量）
curl -s "https://ark.cn-beijing.volces.com/api/v3/images/generations" \
  -H "Authorization: Bearer ${VOLCENGINE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"model":"doubao-seedream-5-0-pro-260628","prompt":"描述","size":"1024x1024"}'
```

### 1.2 视频生成
```bash
# Seedance Mini（便宜·主用）
curl -s "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer ${VOLCENGINE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"model":"doubao-seedance-2-0-mini-260615","content":[{"type":"text","text":"描述"}],"duration":5,"resolution":"720p","aspect_ratio":"16:9"}'

# Seedance Pro（大场景/运镜）
curl -s "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer ${VOLCENGINE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"model":"doubao-seedance-2-0-260128","content":[{"type":"text","text":"描述"}],"duration":5,"resolution":"720p","aspect_ratio":"16:9"}'
```

### 1.3 查询视频任务状态
```bash
curl -s "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/{TASK_ID}" \
  -H "Authorization: Bearer ${VOLCENGINE_API_KEY}"
```

### 1.4 剧本解析/对话
```bash
curl -s "https://ark.cn-beijing.volces.com/api/v3/chat/completions" \
  -H "Authorization: Bearer ${VOLCENGINE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"model":"doubao-seed-2-1-pro-260628","messages":[{"role":"user","content":"问题"}]}'
```

## §2 可灵AI（快手）

### 2.1 视频生成
```bash
curl -s "https://openapi.klingai.com/v1/videos/text2video" \
  -H "Authorization: Bearer ${KLING_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"描述","model_name":"kling-v1"}'
```

### 2.2 查询任务状态
```bash
curl -s "https://openapi.klingai.com/v1/videos/text2video/{TASK_ID}" \
  -H "Authorization: Bearer ${KLING_API_KEY}"
```

⚠️ 注意：可灵API快过期了，优先用掉！

## §3 万相（阿里百炼）

### 3.1 图片生成
```bash
curl -s "https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis" \
  -H "Authorization: Bearer ${WANXIANG_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  -d '{"model":"wanx2.1-t2i-turbo","input":{"prompt":"描述"},"parameters":{"size":"1024*1024","n":1}}'
```

### 3.2 查询任务状态
```bash
curl -s "https://dashscope.aliyuncs.com/api/v1/tasks/{TASK_ID}" \
  -H "Authorization: Bearer ${WANXIANG_API_KEY}"
```

## §4 使用策略

### 4.1 图片生成优先级
```
1. 可灵 kling-v1（快过期·先用掉）
2. 即梦3.0 seedream-4-0（1000张额度·主力）
3. 万相 wanx2.1-turbo（备选）
4. 即梦5.0 Pro seedream-5-0-pro（高质量备选）
```

### 4.2 视频生成优先级
```
1. Seedance Mini 2.0（便宜·主用）
2. Seedance Pro 2.0（大场景/运镜）
3. 可灵 kling-v1（备选）
```

---

> 本技能包由蛋蛋整理 · 闭着眼睛都能调用
> 下次做短剧直接加载 · 不需要再查API文档

---

## §5 图生图·角色一致性（2026-07-15调研）

### 5.1 参考图参数
```bash
# 文生图+参考图（保持角色/风格一致）
curl -s "https://ark.cn-beijing.volces.com/api/v3/images/generations" \
  -H "Authorization: Bearer ${VOLCENGINE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4-0-250828",
    "prompt": "参考图中的人物形象，在修仙世界广场上...",
    "image": ["https://角色参考图URL.png"],
    "size": "1024x1024"
  }'
```

### 5.2 参数说明
```
image: 参考图URL数组（最多10张）
  - 单角色：传1张角色审批图
  - 多角色：传多张（最多10张）
  - 风格参考：传风格图

prompt: 必须描述"参考图中的XXX"
  - "参考图中的人物形象，在..."
  - "参考图中的风格，设计..."
```

### 5.3 组图生成（批量关联图）
```bash
curl -s "https://ark.cn-beijing.volces.com/api/v3/images/generations" \
  -H "Authorization: Bearer ${VOLCENGINE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4-0-250828",
    "prompt": "Generate 3 images of a girl in different scenes...",
    "image": ["https://角色图.png"],
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {"max_images": 3},
    "size": "1024x1024"
  }'
```

### 5.4 苏白短剧应用
```
角色参考图位置（老仓库）:
  苏白: guanghulab/video-ai-system/assets/approved/CHAR-003-SuBai/CHAR-003-V3-R4-approved-1440x2560.png
  诸葛风: guanghulab/video-ai-system/assets/approved/CHAR-004-ZhugeFeng/CHAR-004-V2-approved-1440x2560.png
  王执事: guanghulab/video-ai-system/assets/approved/CHAR-005-WangZhiShi/CHAR-005-V1-R2-approved-1440x2560.png
  中年男子: guanghulab/video-ai-system/assets/approved/CHAR-006-ZhongNian/CHAR-006-V1-approved-1440x2560.png
  欧阳员外: guanghulab/video-ai-system/assets/approved/CHAR-007-Ouyang/CHAR-007-V1-approved-1440x2560.png

工作流:
  1. 读分镜 → 确定这镜需要哪个角色
  2. 调API → image参数传对应角色图
  3. 生成 → 角色一致性大幅提升
```

### 5.5 注意事项
```
️ 参考图必须是可访问的URL（不能是本地路径）
⚠️ 每次生图都要传参考图（没有"缓存"功能）
⚠️ 参考图会额外消耗token（约0.00x元/张）
️ 最多10张参考图，太多影响一致性
```

---

> 调研完成 · 2026-07-15 · D186
> 关键发现：API支持参考图 → 角色一致性有解了！

---

## §6 漫剧风格参考图（D186关键发现）

### 6.1 风格锚点
```
漫剧风格图位置（在线仓库）:
guanghulab/video-ai-system/assets/candidates/D158-VA-05-001-V2/CHAR-003-SuBai/

4张苏白漫剧候选图:
- candidate-01/CHAR-003-V2-candidate-01-1024x1536.png
- candidate-02/CHAR-003-V2-candidate-02-1024x1536.png
- candidate-03/CHAR-003-V2-candidate-03-1024x1536.png
- candidate-04/CHAR-003-V2-candidate-04-1024x1536.png

本地缓存:
/Volumes/JZAO/光湖项目/苏白短剧/原始素材/漫剧风格参考/

⚠️ approved/目录下是真人写实风格（不是漫剧！）
⚠️ candidates/D158目录下才是3D漫剧风格
```

### 6.2 画风锁定模板
```bash
# 带漫剧风格参考图的图片生成
curl -s "https://ark.cn-beijing.volces.com/api/v3/images/generations" \
  -H "Authorization: Bearer $VOLCENGINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4-0-250828",
    "prompt": "参考图中的人物形象，3D国风漫剧风格，{具体场景描述}，圆耳朵，普通人类耳朵",
    "image": ["https://guanghubingshuo.com/code/bingshuo/guanghulab/raw/branch/main/video-ai-system/assets/candidates/D158-VA-05-001-V2/CHAR-003-SuBai/candidate-01/CHAR-003-V2-candidate-01-1024x1536.png"],
    "size": "1024x1024",
    "negative_prompt": "尖耳朵，精灵耳，pointed ears，elf ears，真人写实，照片，Q版，卡通，幼态，日系动漫，插画，现代元素"
  }'
```

### 6.3 多模态质检模板
```bash
# 用doubao-seed-2-1-pro看图检查
curl -s "https://ark.cn-beijing.volces.com/api/v3/chat/completions" \
  -H "Authorization: Bearer $VOLCENGINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seed-2-1-pro-260628",
    "messages": [{"role":"user","content":[
      {"type":"image_url","image_url":{"url":"生成的图片URL"}},
      {"type":"text","text":"检查：1.是否3D漫剧风格？2.有无尖耳朵？3.人物年龄？简短回答，用通过或不通过开头"}
    ]}],
    "max_tokens": 100
  }'
```