一个基于FastAPI的云原生AI图像生成服务，完全适配绘简统一生成接口规范。支持文本生成图像和参考图像生成图像两种模式，使用Yunwu.ai的gemini-2.5-flash-image模型。

• 服务名称: 绘简-云雾AI图像生成服务
• 技术栈: FastAPI + Uvicorn + Yunwu.ai API
• 支持模式: 文生图、图生图
• 接口规范: 完全兼容绘简统一生成接口
• 部署方式: Docker容器化部署

• Python 3.8+
• Docker (可选，用于容器化部署)

git clone <repository-url>
cd 001-1

# 编辑环境配置文件
cp .env.example .env
vim .env

在.env文件中配置您的API密钥：

API_KEY=your_yunwu_api_key_here
BASE_URL=https://yunwu.ai
MODEL=gemini-2.5-flash-image

方式一：使用Docker容器（推荐）

# 构建镜像
docker build -t huijian-yunwu-service:latest -f Dockerfile .

# 运行容器
docker run -d -p 8000:8000 --env-file .env huijian-yunwu-service:latest

方式二：本地Python环境

# 安装依赖
pip install -r requirements.txt

# 启动服务
uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload

方式三：使用预置脚本

# 交互式启动
bash assets/start.sh

# 直接启动（需要已配置.env文件）
bash assets/start.sh --start

访问健康检查接口：

curl http://localhost:8000/health

访问API文档：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

图像生成主接口，支持文生图和图生图模式。

请求体 (application/json):

{
    "prompt": "一只可爱的猫咪在花园里玩耍",
    "reference_images_b64": ["base64_encoded_image_data"],
    "aspect_ratio": "1:1"
}

参数说明:

• prompt (必需): 图片描述，最大4000字符
• reference_images_b64 (可选): Base64编码的参考图片数组，用于图生图模式
• aspect_ratio (可选): 图片宽高比，支持：auto、1:1、16:9、9:16、4:3、3:4、3:2、2:3、5:4、4:5、21:9

响应示例 (成功):

{
    "success": true,
    "task_id": "uuid-string",
    "message": "图片生成成功",
    "generated_images": ["base64_image_data_1", "base64_image_data_2"],
    "ai_text_response": "AI响应文本"
}

响应示例 (失败):

{
    "success": false,
    "task_id": "uuid-string",
    "message": "错误信息",
    "generated_images": [],
    "ai_text_response": "错误描述"
}

服务健康检查接口。

响应:

{
    "status": "healthy",
    "service": "huijian-yunwu-image-service",
    "api_configured": true,
    "model": "gemini-2.5-flash-image",
    "base_url": "https://yunwu.ai"
}

API_KEY=your_yunwu_api_key_here
BASE_URL=https://yunwu.ai
MODEL=gemini-2.5-flash-image

# 服务基础配置
HOST=0.0.0.0
PORT=8000
LOG_LEVEL=info
DEBUG=false

# 性能配置
MAX_WORKERS=4
REQUEST_TIMEOUT=180
MAX_RETRIES=2

# 功能配置
ENABLE_CORS=true
ENABLE_HEALTH_CHECK=true
ENABLE_RATE_LIMIT=false

# 安全配置
ALLOWED_ORIGINS=*

支持旧版本环境变量名：

YUNWU_API_KEY=your_api_key
YUNWU_BASE_URL=https://yunwu.ai
YUNWU_MODEL=gemini-2.5-flash-image

# 构建开发环境镜像
docker build -t huijian-yunwu-dev:latest -f Dockerfile .

# 构建生产环境镜像（精简版）
docker build -t huijian-yunwu-prod:latest -f Dockerfile.build-env .

# 开发环境（包含完整开发工具）
docker run -it --rm -p 8000:8000 -v $(pwd):/workspace huijian-yunwu-dev:latest

# 生产环境（仅运行服务）
docker run -d --name huijian-service -p 8000:8000 --env-file .env huijian-yunwu-prod:latest

# 构建并推送
docker build -t docker.cnb.cool/qlike02/001-1:latest -f Dockerfile .
docker push docker.cnb.cool/qlike02/001-1:latest

├── src/
│   └── main.py          # 主服务程序
├── assets/
│   ├── start.sh         # 启动脚本
│   ├── stop.sh          # 停止脚本
│   ├── status.sh        # 状态检查脚本
│   └── welcome.sh       # 欢迎脚本
├── requirements.txt     # Python依赖
├── .env                # 环境配置文件
├── Dockerfile          # Docker镜像文件
├── Dockerfile.build-env # 构建环境镜像
└── README_zh.md       # 项目说明文档

bash assets/start.sh
# 选项：
#   --edit    编辑配置文件
#   --start   直接启动服务
#   --check   检查配置
#   --help    显示帮助信息

bash assets/status.sh

bash assets/stop.sh

• Python开发: Python 3.12, pip, uv, poetry
• 构建工具: build, twine, cmake, clang
• 开发工具: git, curl, wget, vim, htop
• VS Code扩展: Python全套扩展、代码格式化、调试工具

症状: 服务启动但无法生成图像 解决方案: 检查.env文件中的API_KEY配置是否正确

症状: 服务启动失败 解决方案: 修改.env文件中的PORT配置或停止占用端口的进程

症状: Python包安装错误 解决方案: 使用uv工具加速安装：uv pip install -r requirements.txt

症状: Docker镜像构建错误 解决方案: 检查网络连接，确保Docker daemon正常运行

启用调试模式获取详细日志：

DEBUG=true
LOG_LEVEL=debug

• API文档: 访问 /docs 查看交互式API文档
• 健康检查: 访问 /health 检查服务状态
• 日志查看: 查看容器日志 docker logs <container_id>

本项目采用MIT许可证。

欢迎提交Issue和Pull Request来改进这个项目。

---

注意: 使用前请确保您已获取有效的Yunwu.ai API密钥，并遵守相关服务条款。