# 即梦AI工具封装任务书

## 工具标识
- **tool_id**: `jimeng_ai`
- **工具名称**: 即梦AI生成工具
- **工具描述**: 支持文生图(Seendance 2.0)和图生视频(Seedream Lite 5.0)的AI生成工具
- **分类**: ai

## 功能需求

### 功能1: 文生图 (Seendance 2.0)
- 根据文本提示词生成图片
- 支持正向和负向提示词
- 支持多种尺寸比例
- 支持批量生成(1-4张)
- 支持创意强度调节

### 功能2: 图生视频 (Seedream Lite 5.0)
- 根据图片生成视频
- 支持文本提示词引导
- 支持视频时长设置
- 支持运动强度控制
- 支持首尾帧模式

## 输入Schema

```json
{
  "type": "object",
  "required": ["action"],
  "properties": {
    "action": {
      "type": "string",
      "enum": ["text2image", "image2video", "query_status"],
      "description": "操作类型: text2image(文生图), image2video(图生视频), query_status(查询任务状态)"
    },
    "prompt": {
      "type": "string",
      "description": "正向提示词,描述想要生成的内容"
    },
    "negative_prompt": {
      "type": "string",
      "description": "负向提示词,描述不希望出现的内容",
      "default": ""
    },
    "model": {
      "type": "string",
      "enum": ["seendance_2.0", "seedream_lite_5.0"],
      "description": "模型选择: seendance_2.0(文生图), seedream_lite_5.0(图生视频)",
      "default": "seendance_2.0"
    },
    "aspect_ratio": {
      "type": "string",
      "enum": ["1:1", "16:9", "9:16", "4:3", "3:4"],
      "description": "图片长宽比",
      "default": "1:1"
    },
    "image_count": {
      "type": "integer",
      "minimum": 1,
      "maximum": 4,
      "description": "生成图片数量(文生图)",
      "default": 1
    },
    "cfg_scale": {
      "type": "number",
      "minimum": 1.0,
      "maximum": 20.0,
      "description": "创意强度,值越大越贴近提示词",
      "default": 7.0
    },
    "steps": {
      "type": "integer",
      "minimum": 10,
      "maximum": 50,
      "description": "生成步数,步数越多质量越高",
      "default": 20
    },
    "seed": {
      "type": "integer",
      "description": "随机种子,用于复现结果",
      "default": -1
    },
    "image_url": {
      "type": "string",
      "description": "参考图片URL(图生视频必需)"
    },
    "image_base64": {
      "type": "string",
      "description": "参考图片Base64编码(与image_url二选一)"
    },
    "video_duration": {
      "type": "integer",
      "enum": [3, 5, 10],
      "description": "视频时长(秒),图生视频使用",
      "default": 5
    },
    "motion_strength": {
      "type": "number",
      "minimum": 0.0,
      "maximum": 1.0,
      "description": "运动强度,0为静态,1为最大运动",
      "default": 0.5
    },
    "start_frame": {
      "type": "string",
      "description": "首帧图片(Base64或URL)"
    },
    "end_frame": {
      "type": "string",
      "description": "尾帧图片(Base64或URL)"
    },
    "task_id": {
      "type": "string",
      "description": "任务ID,用于查询任务状态"
    },
    "cookie": {
      "type": "string",
      "description": "认证Cookie"
    },
    "api_key": {
      "type": "string",
      "description": "API密钥(如果使用官方API)"
    }
  }
}
```

## 输出Schema

```json
{
  "type": "object",
  "properties": {
    "task_id": {
      "type": "string",
      "description": "任务唯一标识"
    },
    "status": {
      "type": "string",
      "enum": ["pending", "processing", "completed", "failed"],
      "description": "任务状态"
    },
    "progress": {
      "type": "number",
      "minimum": 0,
      "maximum": 100,
      "description": "任务进度百分比"
    },
    "result": {
      "type": "object",
      "description": "生成结果",
      "properties": {
        "images": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "生成的图片URL列表"
        },
        "videos": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "生成的视频URL列表"
        },
        "metadata": {
          "type": "object",
          "description": "生成元数据",
          "properties": {
            "model": {
              "type": "string",
              "description": "使用的模型"
            },
            "seed": {
              "type": "integer",
              "description": "实际使用的随机种子"
            },
            "duration": {
              "type": "number",
              "description": "生成耗时(秒)"
            }
          }
        }
      }
    },
    "error": {
      "type": "string",
      "description": "错误信息(如果失败)"
    },
    "estimated_time": {
      "type": "integer",
      "description": "预计完成时间(秒)"
    }
  },
  "required": ["task_id", "status"]
}
```

## 实现要求

1. **技术栈**: Python 3.12+, FastAPI, uvicorn, httpx, pydantic
2. **API端点**:
   - GET `/health` - 健康检查(必需)
   - POST `/generate` - 创建生成任务(文生图或图生视频)
   - GET `/status/{task_id}` - 查询任务状态和结果
3. **核心功能**:
   - 提交生成任务并返回task_id
   - 查询任务状态和结果
   - 支持Base64和URL两种图片输入方式
4. **错误处理**:
   - 参数验证(Pydantic模型)
   - API调用失败处理
   - 详细的错误日志
5. **环境**: 使用uv创建Python环境
6. **端口**: 默认8000,支持 `--port` 参数

## 参考实现

参考项目中其他AI生成工具的实现:
- `liblibai_controlnet` - 图生图工具
- `runcomfy_workflow_executor` - ComfyUI工作流执行

## API调用流程

### 文生图流程:
1. 提交生成任务 → 获取task_id
2. 轮询任务状态 → 等待completed
3. 返回图片URL列表

### 图生视频流程:
1. 上传参考图片(如果是Base64)
2. 提交视频生成任务 → 获取task_id
3. 轮询任务状态(可能需要较长时间)
4. 返回视频URL

## 特殊要求

1. **异步处理**: 生成任务应该异步执行,不阻塞API响应
2. **状态持久化**: 任务状态应该缓存,避免重复查询上游API
3. **资源清理**: 定期清理过期的任务缓存(超过24小时)
4. **限流保护**: 实现简单的限流机制,避免API滥用
5. **日志记录**: 记录所有API调用和错误,便于调试

## 测试要点

1. 文生图基本功能测试
2. 图生视频基本功能测试
3. 任务状态查询测试
4. 错误处理测试(无效参数、API失败等)
5. 超时处理测试

## 环境变量

```bash
JIMENG_API_KEY=your_api_key_here
JIMENG_COOKIE=your_cookie_here
JIMENG_BASE_URL=https://api.jimeng.ai  # API基础URL
```