纲要

本文围绕将第三方文生图API封装为可复用Skills的技术过程展开，核心涉及以下关键技术点与流程：

• Skills 封装机制与设计原则
• 文生图（Text-to-Image）API 的接口对接与参数设计
• 异步任务轮询策略与间隔优化（从 5 秒调整至 15 秒）
• 密钥管理与配置分离
• 图片存储路径的动态指定（默认目录与 temp 文件夹）
• 自然语言驱动的配置变更方式
• 项目目录结构与模块划分
• 开源发布与项目集成的通用建议

技术背景与问题分析

在基于大语言模型（LLM）构建的自动化工作流中，Skills 是一种将特定能力（如图像生成、文档处理等）封装为标准接口的模块化方案。其核心价值在于：通过自然语言触发任务，由底层脚本完成实际的API调用、数据轮询与结果处理，最终将输出反馈至用户。

此前，某个现有的文生图 Skill 存在一处设计缺陷：在调用异步生成接口后，其内置的轮询机制以 5 秒 为固定间隔频繁查询任务状态。这一过短的轮询间隔被目标API服务端识别为异常高频请求，从而导致客户端IP被临时屏蔽（IP Ban），造成任务无法顺利完成。

从工程优化角度出发，轮询间隔的设置需在用户体验与服务端压力之间取得平衡。对于图像生成这类典型异步任务，单次推理耗时通常在数秒至数十秒不等。将轮询间隔设定为 15 秒或 30 秒是更为稳健的策略，既能及时获取任务结果，又能显著降低触发服务端限流策略的风险。

API 对接与 Skills 设计

核心API端点

本次封装的文生图功能依赖两个核心HTTP API接口，均基于非官方GPT API地址的第三方中转服务（如APImart或同类提供商）：

接口类型	功能描述	关键参数
任务提交接口	提交生成提示词（prompt），返回任务标识符（task ID）	prompt、api_key
任务查询接口	根据任务ID轮询生成结果，返回图片URL或二进制数据	task_id、api_key

Skills 配置与密钥管理

相较于原项目中整合了 gemini、GLM 等多种模型服务的复杂配置，本次封装的专用 Skill 仅需一个核心校验字段——API密钥（api_key）。该密钥用于所有API请求的身份验证。

配置管理的设计原则是：通过自然语言描述修改，而非直接编辑代码文件。当密钥发生变更时，用户只需向AI助手描述“更新API密钥为xxx”，系统将自动定位配置文件并完成修改。这一设计降低了非技术用户的操作门槛，同时避免了手动编辑代码可能引入的语法错误。

图片存储路径规则

对于生成图片的保存位置，设计了以下优先级逻辑：

1. 若用户在请求中指定了目标目录，则保存至该目录；
2. 若未指定，则保存至当前工作目录下的默认 temp 文件夹；
3. 若 temp 文件夹不存在，则自动创建。

这一设计确保了图片输出的确定性，同时兼顾了临时文件管理的规范性。

项目结构与代码实现

目录树

生成的 Skill 项目遵循标准的模块化结构，具体如下：

├── init.py                  # Skill 入口文件，定义命令行触发逻辑
├── image_generator.py       # 核心生成模块，封装 API 调用与轮询
├── config.yaml              # 配置文件（含 api_key 等敏感信息）
├── temp/                    # 默认图片输出目录
│   └── <generated_images>   # 生成的图片文件
└── README.md                # 使用说明文档

核心模块说明

入口文件（init.py）

负责解析用户通过自然语言或命令行传递的参数（如提示词、保存路径），并将控制权转交给核心生成模块。该文件是 Skill 的对外接口，不应包含具体业务逻辑。

核心生成模块（image_generator.py）

包含以下关键函数：

• submit_task(prompt: str, api_key: str) -> str：调用任务提交接口，返回任务ID。
• poll_task_result(task_id: str, api_key: str, interval: int = 15, max_attempts: int = 60) -> str：按指定间隔轮询任务状态，返回生成图片的URL或本地路径。
• download_and_save_image(url: str, save_dir: str = "temp") -> str：下载图片并保存至指定目录，返回本地文件路径。

配置文件（config.yaml）

采用YAML格式存储非代码配置项。例如：

api_key: "your-api-key-here"
api_base_url: "https://api.example.com/v1"
polling_interval: 15  # 轮询间隔（秒）
default_save_dir: "temp"

完整可运行代码示例

以下是一个基于 Python 实现的文生图 Skill 核心逻辑。该代码封装了任务提交、轮询与图片保存的完整流程，可直接作为独立模块运行。

import time
import os
import requests
import yaml
from pathlib import Path

class ImageGenerator:
    """
    文生图 Skills 核心类
    适用版本：Python 3.8+
    依赖库：requests, pyyaml
    """
    
    def __init__(self, config_path="config.yaml"):
        with open(config_path, "r") as f:
            self.config = yaml.safe_load(f)
        self.api_key = self.config["api_key"]
        self.base_url = self.config["api_base_url"]
        self.polling_interval = self.config.get("polling_interval", 15)
        self.default_save_dir = self.config.get("default_save_dir", "temp")
    
    def submit_task(self, prompt: str) -> str:
        """
        提交文生图任务，返回任务 ID
        """
        url = f"{self.base_url}/generate"
        headers = {"Authorization": f"Bearer {self.api_key}"}
        payload = {"prompt": prompt, "num_images": 1}
        
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()
        data = response.json()
        
        # 假设返回格式为 {"task_id": "xxx"}
        return data["task_id"]
    
    def poll_task_result(self, task_id: str, max_attempts: int = 60) -> str:
        """
        轮询任务结果，返回图片 URL
        """
        url = f"{self.base_url}/result/{task_id}"
        headers = {"Authorization": f"Bearer {self.api_key}"}
        
        for attempt in range(max_attempts):
            response = requests.get(url, headers=headers)
            response.raise_for_status()
            data = response.json()
            
            # 假设状态字段为 "status"，值为 "completed" 时任务完成
            if data.get("status") == "completed":
                return data["image_url"]
            elif data.get("status") in ["failed", "error"]:
                raise RuntimeError(f"任务失败: {data.get('message', '未知错误')}")
            
            time.sleep(self.polling_interval)
        
        raise TimeoutError(f"轮询超时，任务 ID: {task_id}")
    
    def save_image(self, image_url: str, save_dir: str = None) -> str:
        """
        下载并保存图片到指定目录
        """
        if save_dir is None:
            save_dir = self.default_save_dir
        
        Path(save_dir).mkdir(parents=True, exist_ok=True)
        
        response = requests.get(image_url)
        response.raise_for_status()
        
        # 从 URL 提取文件名，或生成时间戳命名
        filename = f"generated_{int(time.time())}.png"
        filepath = os.path.join(save_dir, filename)
        
        with open(filepath, "wb") as f:
            f.write(response.content)
        
        return filepath
    
    def generate(self, prompt: str, save_dir: str = None) -> str:
        """
        完整生成流程：提交 -> 轮询 -> 保存
        """
        print(f"📤 提交任务，提示词: {prompt}")
        task_id = self.submit_task(prompt)
        
        print(f"⏳ 轮询中（间隔 {self.polling_interval} 秒）...")
        image_url = self.poll_task_result(task_id)
        
        print("💾 下载并保存图片...")
        local_path = self.save_image(image_url, save_dir)
        
        return local_path


# 命令行入口示例
if __name__ == "__main__":
    generator = ImageGenerator()
    
    # 从命令行参数或硬编码提示词获取
    prompt = "赛博朋克风格的城市夜景，霓虹灯闪烁"
    save_to = "temp"
    
    try:
        saved_path = generator.generate(prompt, save_to)
        print(f"✅ 图片已保存至: {saved_path}")
    except Exception as e:
        print(f"❌ 生成失败: {e}")

自然语言驱动的配置变更

在AI辅助开发环境中，用户无需直接编辑 config.yaml 或 image_generator.py。当需要修改API密钥、轮询间隔或默认保存路径时，只需向AI助手发送自然语言指令，例如：

• “将API密钥更新为 sk-xxxxxxxx”
• “将轮询间隔改为 20 秒”
• “将默认图片保存路径改为 ./outputs”

AI助手将基于语义理解，自动定位配置项并完成修改。这一机制大幅降低了对命令行或代码编辑的依赖，使得非技术背景的内容创作者也能灵活调整 Skill 的行为。

开源发布与项目集成

完成封装的文生图 Skill 本质上是一个独立的 Python 项目，具备完整的目录结构、配置入口和核心逻辑。它可以直接：

• 开源至 GitHub 或 Gitee（码云），供社区使用和二次开发；
• 作为子模块集成到更大的自动化项目中（如批量生成公众号配图、批量创作社交媒体素材等）；
• 通过多 Skills 捆绑发布，形成功能更丰富的工具集（例如同时包含文生图、文生文、图生文等能力）。

在内容创作场景（如公众号运营）中，该 Skill 可作为AI写作工作流的配图环节。用户在完成文案后，只需通过自然语言触发（如“请使用我的文生图 Skill，为本文生成一张赛博朋克风格的封面图”），系统即自动完成图片生成、保存与引用路径返回，最终输出包含图文内容的完整 Markdown 文档。

API 速览

本项目中涉及的核心API接口如下，所有接口均需携带 API Key 进行身份认证。

任务提交接口

• 方法签名：POST {base_url}/generate
• 请求头：Authorization: Bearer {api_key}，Content-Type: application/json
• 请求体：

  {
    "prompt": "string, 必填，图像描述文本",
    "num_images": "int, 可选，默认1，生成图片数量"
  }
  

• 返回示例：

  {
    "task_id": "task_abc123",
    "status": "pending"
  }
  

任务查询接口

• 方法签名：GET {base_url}/result/{task_id}
• 请求头：Authorization: Bearer {api_key}
• 返回示例（进行中）：

  {
    "status": "processing",
    "progress": 50
  }
  

• 返回示例（已完成）：

  {
    "status": "completed",
    "image_url": "https://cdn.example.com/images/xxx.png"
  }
  

• 返回示例（失败）：

  {
    "status": "failed",
    "message": "内容审核未通过"
  }
  

Demo 示例

以下提供一个可直接运行的 HTML + Python 混合示例（前端通过后端API触发生成），展示完整交互流程。

运行说明

1. 将上述完整 Python 代码保存为 image_generator.py，并创建 config.yaml 填入有效 API Key。
2. 安装依赖：pip install requests pyyaml flask（如需Web界面）。
3. 启动 Flask 服务端（代码见下方），访问 http://localhost:5000。
4. 在输入框中填写提示词，点击提交，页面将轮询显示生成进度并最终展示图片。

服务端代码（app.py）

from flask import Flask, request, jsonify, render_template_string
from image_generator import ImageGenerator
import threading
import time

app = Flask(__name__)
generator = ImageGenerator()
task_status = {}

HTML_TEMPLATE = ```
<!DOCTYPE html>
<html>
<head><title>文生图 Demo</title></head>
<body>
    <h2>文生图 Skills 演示</h2>
    <input id="prompt" type="text" placeholder="输入图片描述" style="width:300px">
    <button onclick="generate()">生成</button>
    <div id="result"></div>
    <script>
        function generate() {
            const prompt = document.getElementById('prompt').value;
            fetch('/generate', {
                method: 'POST',
                headers: {'Content-Type': 'application/json'},
                body: JSON.stringify({prompt})
            })
            .then(res => res.json())
            .then(data => {
                if (data.task_id) {
                    pollResult(data.task_id);
                }
            });
        }
        function pollResult(taskId) {
            const interval = setInterval(() => {
                fetch(`/result/${taskId}`)
                .then(res => res.json())
                .then(data => {
                    if (data.status === 'completed') {
                        clearInterval(interval);
                        document.getElementById('result').innerHTML = `<img src="${data.image_url}" style="max-width:400px">`;
                    } else if (data.status === 'failed') {
                        clearInterval(interval);
                        document.getElementById('result').innerText = '生成失败: ' + data.message;
                    }
                });
            }, 3000);
        }
    </script>
</body>
</html>

@app.route('/')
def index():
    return render_template_string(HTML_TEMPLATE)

@app.route('/generate', methods=['POST'])
def generate():
    prompt = request.json.get('prompt')
    task_id = generator.submit_task(prompt)
    task_status[task_id] = {'status': 'processing'}
    # 异步执行轮询
    thread = threading.Thread(target=background_poll, args=(task_id,))
    thread.start()
    return jsonify({'task_id': task_id})

@app.route('/result/<task_id>')
def result(task_id):
    return jsonify(task_status.get(task_id, {'status': 'unknown'}))

def background_poll(task_id):
    try:
        image_url = generator.poll_task_result(task_id)
        task_status[task_id] = {'status': 'completed', 'image_url': image_url}
    except Exception as e:
        task_status[task_id] = {'status': 'failed', 'message': str(e)}

if __name__ == '__main__':
    app.run(debug=True)

技术点总结

• 前端通过 Ajax 异步提交生成任务并轮询结果。
• 后端使用独立线程执行耗时的轮询操作，避免阻塞 Web 服务。
• 任务状态通过内存字典临时存储（生产环境应替换为 Redis 等持久化方案）。
• 完整演示了从自然语言输入到图片生成、展示的全链路流程。

参考文档

官方文档

本次实践基于通用文生图 API 规范设计，未使用官方 OpenAI 接口，而是采用 APImart 等第三方中转服务。具体 API 文档请参阅所使用服务商提供的开发者指南。

若使用 APImart，其文档地址通常为：https://apimart.com/docs（请以实际服务商提供的文档为准）。

参考链接

• OpenAI Image Generation API Reference — 官方文生图接口标准
• Requests 库官方文档 — Python HTTP 请求库
• PyYAML 官方文档 — YAML 配置文件解析
• Flask 官方文档 — Web 服务快速搭建

总结

本文完整梳理了将文生图API封装为可复用Skills的全过程，核心要点包括：将轮询间隔从5秒优化至15秒以规避IP屏蔽；采用api_key单一密钥认证，简化配置；通过自然语言驱动配置变更，降低操作门槛；图片默认保存至temp目录并支持自定义路径。代码实现采用Python 3.8+，依赖requests和pyyaml库，核心模块包含任务提交、轮询及图片保存三类功能。

该Skill可独立开源或集成至大型自动化项目中，尤其适用于公众号配图、批量视觉内容生成等场景。最终输出的是一套可验证、可运行的技术方案，兼顾了工程稳定性与用户体验。