Tool_Agent/task_specs/jimeng_ai_task.md

即梦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

{
  "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

{
  "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. 超时处理测试

环境变量

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