Add FastAPI image generation service

Provide containerized GPT and Grok image generation with environment-based configuration.
1 month ago · cf8b6c067d
commit cf8b6c067d
8 changed files with 492 additions and 0 deletions
--- a/.env.example
+++ b/.env.example
@ -0,0 +1,3 @@
 GROK_API_KEY=your_grok_api_key
 GPT_API_KEY=your_gpt_api_key
 IMAGE_API_BASE_URL=https://api.slomerex.xyz/v1
--- a/.gitignore
+++ b/.gitignore
@ -0,0 +1,40 @@
 # Environment and secrets
 .env
 .env.*
 !.env.example
 # Generated output
 output/
 # Python
 __pycache__/
 *.py[cod]
 *$py.class
 *.so
 .Python
 .pytest_cache/
 .mypy_cache/
 .ruff_cache/
 .coverage
 htmlcov/
 # Virtual environments
 .venv/
 venv/
 env/
 # Packaging
 build/
 dist/
 *.egg-info/
 # IDE and OS
 .vscode/
 .idea/
 *.iml
 .DS_Store
 Thumbs.db
 # Logs and local databases
 *.log
 *.sqlite3
--- a/13
+++ b/13
@ -0,0 +1,13 @@
 FROM python:3.12-slim
 WORKDIR /app
 COPY requirements.txt .
 RUN pip install --no-cache-dir -r requirements.txt
 COPY agent-image-t2i.py .
 RUN mkdir -p /app/output
 EXPOSE 8000
 CMD ["uvicorn", "agent-image-t2i:app", "--host", "0.0.0.0", "--port", "8000"]
--- a/SKILL.md
+++ b/SKILL.md
@ -0,0 +1,115 @@
 ---
 name: ai-image
 description: Generate images via AI text-to-image API (GPT Image / Grok). Use when the user asks to draw, paint, generate, or create an image from a text description.
 ---
 # AI 绘图工具
 通过 FastAPI 文生图服务生成图片，供 Agent 通过 HTTP/cURL 直接调用，无需自己实现模型请求逻辑。
 服务端使用 OpenAI Python SDK 请求 GPT Image / Grok Image 上游接口，生成的图片保存在服务端 `output/` 目录，并通过 HTTP 返回访问地址。
 - 服务端 API 不要求调用方提供上游 API Key；上游鉴权通过项目根目录 `.env` 配置
 - `.env` 不应提交到 Git，复制 `.env.example` 为 `.env` 后填写真实 Key
 - 使用 Docker Compose 时会自动读取 `.env` 并注入容器
 ## 可用脚本
 | 能力 | 服务端文件 | HTTP 端点 | 模型 |
 |------|------------|------------|------|
 | GPT / Grok 绘图 | `agent-image-t2i.py` | `POST /images/generations` | `gpt-image-2-1K` / `gpt-image-2-2K` / `gpt-image-2-4K` / `grok-imagine-image-lite` |
 | 健康检查 | `agent-image-t2i.py` | `GET /health` | — |
 | 图片访问 | `agent-image-t2i.py` | `GET /output/{filename}` | — |
 ## GPT 模型说明
 | 模型 | 输出尺寸 | 备注 |
 |------|----------|------|
 | `gpt-image-2-1K` | ~1254×1254（1:1）或 1536×1024（横版） | **推荐**，线路稳定 |
 | `gpt-image-2-2K` | 不固定 | 线路不稳定，可能 503 |
 | `gpt-image-2-4K` | 不固定 | 线路不稳定，可能 503 |
 > Grok 模型的 size 参数不可靠，API 返回尺寸不受控。
 ## 使用方式
 先启动 FastAPI 服务：
 ```bash
 uvicorn agent-image-t2i:app --host 0.0.0.0 --port 8000
 ```
 默认服务地址为 `http://localhost:8000`。
 健康检查：
 ```bash
 curl http://localhost:8000/health
 ```
 使用 Grok 绘图：
 ```bash
 curl -X POST http://localhost:8000/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a cute cat",
    "provider": "grok",
    "size": "1024x1024",
    "n": 1
  }'
 ```
 使用 GPT 绘图：
 ```bash
 curl -X POST http://localhost:8000/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a cute cat",
    "provider": "gpt",
    "model": "gpt-image-2-1K",
    "size": "1536x1024",
    "n": 1
  }'
 ```
 生成结果中的 `url` 为图片访问地址，例如 `http://localhost:8000/output/{filename}`。
 ## 调用建议
 - **优先用 Grok**：稳定出图，适合日常使用
 - **追求画质用 GPT 1K**：请求中设置 `"provider": "gpt"`
 - **GPT 2K/4K 线路可能不稳定**：不推荐作为默认模型
 - **Prompt 用英文**：效果通常比中文好
 - 使用 Docker Compose 时，项目的 `output/` 会映射到容器的 `/app/output`
 ## 请求参数
 请求体为 JSON，发送到 `POST /images/generations`：
 - `prompt`：必填，图片提示词
 - `provider`：可选，`grok` 或 `gpt`，默认 `grok`
 - `model`：可选，覆盖 provider 的默认模型
 - `size`：可选，默认 `1024x1024`
 - `n`：可选，生成数量，范围 `1 ~ 10`，默认 `1`
 ## 输出规范
 - 图片默认保存在服务端 `output/` 目录
 - 响应返回 `filename`、`url` 和文件大小 `bytes`
 - 图片通过 `GET /output/{filename}` 访问
 - 服务启动后，响应中的相对路径 `url` 需要拼接服务地址，例如 `http://localhost:8000/output/{filename}`
 ## Prompt 技巧
 - 使用英文 prompt 效果更好
 - 描述要具体：主体 + 环境 + 光线 + 风格 + 情绪
 - 横版图用 `--size 1536x1024`，正方形用 `--size 1024x1024`
 - 加上 `cinematic lighting, highly detailed, 4K` 等后缀提升质感
 ## 配置与注意事项
 - 单次上游请求超时为 120 秒
 - 上游请求遇到网络错误或 408/429/500/502/503/504 时，最多自动重试 3 次，并使用指数退避
 - FastAPI 自动文档地址：`http://localhost:8000/docs`
--- a/agent-image-t2i.py
+++ b/agent-image-t2i.py
@ -0,0 +1,114 @@
 #!/usr/bin/env python3
 """通过 FastAPI 提供 GPT Image 和 Grok Image 文生图服务。"""
 import base64
 import os
 import time
 from pathlib import Path
 from uuid import uuid4
 from dotenv import load_dotenv
 from fastapi import FastAPI, HTTPException
 from fastapi.staticfiles import StaticFiles
 from openai import APIConnectionError, APIStatusError, APITimeoutError, OpenAI
 from pydantic import BaseModel, Field
 load_dotenv()
 API_BASE_URL = os.getenv("IMAGE_API_BASE_URL", "https://api.slomerex.xyz/v1")
 OUTPUT_DIR = Path("output")
 MAX_RETRIES = 3
 RETRYABLE_STATUS_CODES = {408, 429, 500, 502, 503, 504}
 PROVIDERS = {
    "grok": {
        "api_key_env": "GROK_API_KEY",
        "model": "grok-imagine-image-lite",
    },
    "gpt": {
        "api_key_env": "GPT_API_KEY",
        "model": "gpt-image-2-1K",
    },
 }
 app = FastAPI(title="AI Image T2I API", version="1.0.0")
 OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
 app.mount("/output", StaticFiles(directory=OUTPUT_DIR), name="output")
 class ImageGenerationRequest(BaseModel):
    prompt: str = Field(min_length=1, description="图片提示词")
    provider: str = Field(default="grok", pattern="^(grok|gpt)$", description="模型提供方")
    model: str | None = Field(default=None, description="覆盖提供方默认模型")
    size: str = Field(default="1024x1024", description="图片尺寸")
    n: int = Field(default=1, ge=1, le=10, description="生成数量")
 class GeneratedImage(BaseModel):
    filename: str
    url: str
    bytes: int
 class ImageGenerationResponse(BaseModel):
    provider: str
    model: str
    images: list[GeneratedImage]
 def generate_with_retry(client: OpenAI, *, model: str, prompt: str, size: str, n: int):
    for attempt in range(1, MAX_RETRIES + 1):
        try:
            return client.images.generate(model=model, prompt=prompt, size=size, n=n)
        except APIStatusError as e:
            if e.status_code not in RETRYABLE_STATUS_CODES or attempt == MAX_RETRIES:
                raise HTTPException(status_code=502, detail=f"上游图片服务错误: HTTP {e.status_code}") from e
            time.sleep(2 ** (attempt - 1))
        except (APIConnectionError, APITimeoutError) as e:
            if attempt == MAX_RETRIES:
                raise HTTPException(status_code=504, detail="上游图片服务连接或请求超时") from e
            time.sleep(2 ** (attempt - 1))
@app.get("/health")
 def health_check():
    return {"status": "ok"}
@app.post("/images/generations", response_model=ImageGenerationResponse)
 def generate_images(request: ImageGenerationRequest):
    config = PROVIDERS[request.provider]
    api_key = os.getenv(config["api_key_env"])
    if not api_key:
        raise HTTPException(status_code=500, detail=f"未配置环境变量 {config['api_key_env']}")
    model = request.model or config["model"]
    client = OpenAI(base_url=API_BASE_URL, api_key=api_key, timeout=120.0, max_retries=0)
    response = generate_with_retry(
        client,
        model=model,
        prompt=request.prompt,
        size=request.size,
        n=request.n,
    )
    images = []
    for item in response.data:
        if not item.b64_json:
            raise HTTPException(status_code=502, detail="上游图片服务未返回 Base64 图片数据")
        try:
            raw = base64.b64decode(item.b64_json)
        except ValueError as e:
            raise HTTPException(status_code=502, detail="上游图片数据格式无效") from e
        filename = f"{model}-{uuid4().hex}.png"
        (OUTPUT_DIR / filename).write_bytes(raw)
        images.append(GeneratedImage(filename=filename, url=f"/output/{filename}", bytes=len(raw)))
    return ImageGenerationResponse(provider=request.provider, model=model, images=images)
 if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)
--- a/docker-compose.yml
+++ b/docker-compose.yml
@ -0,0 +1,12 @@
 services:
  ai-image-t2i:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8000:8000"
    env_file:
      - .env
    volumes:
      - ./output:/app/output
    restart: unless-stopped
--- a/docs.md
+++ b/docs.md
@ -0,0 +1,191 @@
 # 图像模型 API 文档
 本文档整理 GPT Image 和 Grok Image 模型的 API 信息、调用示例、支持参数及速率限制。
 ## 通用信息
 - API 基础地址：`https://api.slomerex.xyz/v1`
 - 认证方式：`Authorization: Bearer <TOKEN>`
 - Anthropic 格式的端点也接受 `x-api-key` 请求头。
 - 可在「令牌」页面生成 API Key，并按模型、分组、IP、速率等维度进行授权。
 - 示例中的 `<YOUR_API_KEY>` 请替换为令牌设置中的 API Key。
 ## 模型列表
 | 模型 | 提供方 | 计费方式 |
 |---|---|---|
 | `gpt-image-2-1K` | OpenAI | 按次计费 |
 | `gpt-image-2-2K` | OpenAI | 按次计费 |
 | `gpt-image-2-4K` | OpenAI | 按次计费 |
 | `grok-imagine-image-lite` | xAI | 按次计费 |
 ---
 ## gpt-image-2-1K
 ### 调用示例
 ```python
 from openai import OpenAI
 client = OpenAI(
    base_url="https://api.slomerex.xyz/v1",
    api_key="<YOUR_API_KEY>",
 )
 completion = client.chat.completions.create(
    model="gpt-image-2-1K",
    messages=[
        {"role": "user", "content": "Explain quantum entanglement in one paragraph."}
    ],
 )
 print(completion.choices[0].message.content)
 ```
 ### 支持的参数
 | 参数 | 类型 | 默认值 / 范围 | 说明 |
 |---|---|---|---|
 | `prompt` | `string` | 必填 | 想要生成图像的文字描述 |
 | `size` | `enum` | `1024x1024` | 输出图像尺寸 |
 | `quality` | `enum` | `standard` | 生成质量预设 |
 | `style` | `enum` | `vivid` | 画风 |
 | `n` | `integer` | `1`，范围 `1 ~ 10` | 生成的图像数量 |
 | `response_format` | `enum` | `url` | 图像结果的返回方式 |
 ### 速率限制
 | 分组 | RPM | TPM | RPD |
 |---|---:|---:|---:|
 | Gpt Image | 50 | — | 800 |
 ---
 ## gpt-image-2-2K
 ### 调用示例
 ```python
 from openai import OpenAI
 client = OpenAI(
    base_url="https://api.slomerex.xyz/v1",
    api_key="<YOUR_API_KEY>",
 )
 completion = client.chat.completions.create(
    model="gpt-image-2-2K",
    messages=[
        {"role": "user", "content": "Explain quantum entanglement in one paragraph."}
    ],
 )
 print(completion.choices[0].message.content)
 ```
 ### 支持的参数
 | 参数 | 类型 | 默认值 / 范围 | 说明 |
 |---|---|---|---|
 | `prompt` | `string` | 必填 | 想要生成图像的文字描述 |
 | `size` | `enum` | `1024x1024` | 输出图像尺寸 |
 | `quality` | `enum` | `standard` | 生成质量预设 |
 | `style` | `enum` | `vivid` | 画风 |
 | `n` | `integer` | `1`，范围 `1 ~ 10` | 生成的图像数量 |
 | `response_format` | `enum` | `url` | 图像结果的返回方式 |
 ### 速率限制
 | 分组 | RPM | TPM | RPD |
 |---|---:|---:|---:|
 | Gpt Image | 70 | — | 1.2K |
 ---
 ## gpt-image-2-4K
 ### 调用示例
 ```bash
 curl https://api.slomerex.xyz/v1/chat/completions \
  -H "Authorization: Bearer $NEW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-4K",
    "messages": [
      {
        "role": "user",
        "content": "Explain quantum entanglement in one paragraph."
      }
    ],
    "temperature": 0.7
  }'
 ```
 ### 支持的参数
 | 参数 | 类型 | 默认值 / 范围 | 说明 |
 |---|---|---|---|
 | `prompt` | `string` | 必填 | 想要生成图像的文字描述 |
 | `size` | `enum` | `1024x1024` | 输出图像尺寸 |
 | `quality` | `enum` | `standard` | 生成质量预设 |
 | `style` | `enum` | `vivid` | 画风 |
 | `n` | `integer` | `1`，范围 `1 ~ 10` | 生成的图像数量 |
 | `response_format` | `enum` | `url` | 图像结果的返回方式 |
 ### 速率限制
 | 分组 | RPM | TPM | RPD |
 |---|---:|---:|---:|
 | Gpt Image | 60 | — | 900 |
 ---
 ## grok-imagine-image-lite
 ### 调用示例
 ```python
 from openai import OpenAI
 client = OpenAI(
    base_url="https://api.slomerex.xyz/v1",
    api_key="<YOUR_API_KEY>",
 )
 completion = client.chat.completions.create(
    model="grok-imagine-image-lite",
    messages=[
        {"role": "user", "content": "Explain quantum entanglement in one paragraph."}
    ],
 )
 print(completion.choices[0].message.content)
 ```
 ### 支持的参数
 | 参数 | 类型 | 默认值 / 范围 | 说明 |
 |---|---|---|---|
 | `prompt` | `string` | 必填 | 想要生成图像的文字描述 |
 | `size` | `enum` | `1024x1024` | 输出图像尺寸 |
 | `quality` | `enum` | `standard` | 生成质量预设 |
 | `style` | `enum` | `vivid` | 画风 |
 | `n` | `integer` | `1`，范围 `1 ~ 10` | 生成的图像数量 |
 | `response_format` | `enum` | `url` | 图像结果的返回方式 |
 ### 速率限制
 | 分组 | RPM | TPM | RPD |
 |---|---:|---:|---:|
 | Grok | 40 | — | 700 |
 ---
 ## 速率限制说明
 - **RPM**：每分钟请求数（Requests Per Minute）
 - **TPM**：每分钟 token 数（Tokens Per Minute）
 - **RPD**：每日请求数（Requests Per Day）
 - 限制按令牌分组生效。
--- a/requirements.txt
+++ b/requirements.txt
@ -0,0 +1,4 @@
 fastapi
 openai
 python-dotenv
 uvicorn[standard]