开源文生图模型接入实操:配置、提示词与出图验收
作者:JC2026.11.18 11:28浏览量:0简介:本文给出开源文生图模型的接入步骤,包括用环境变量管理密钥、可运行的请求代码、提示词与分辨率配置、出图验收方法和常见错误排查。读者可按模板自行实测耗时、失败率和文件体积,得出适用于自己环境的结论,不必依赖未经核实的数字。
一、适用范围与前置条件
原始资料没有给出模型名称、版本和官方文档链接,因此本文不指定具体模型。文中的参数名、尺寸和数量上限都是示例,选定模型后必须以该模型的官方文档为准。原文中的约10秒生成、最高4096×4096、单次约10张、约16张参考图、约32000字符提示词等数字,目前都只是待核验的宣称,本文不把它们当作结论使用。
开始接入前,准备以下条件:
- 提供方账号,并在控制台创建 API Key。建议只开通生成图片所需的权限。
- Python 3.9 或更高版本。
- 两个依赖库:
openai(用于调用兼容接口)和pillow(用于读取图片尺寸)。 - 从官方文档确认以下信息:接口地址、模型名、支持的尺寸列表、单次返回张数
n的上限、提示词最大长度、参考图数量上限、返回格式(base64 还是 URL)、限流规则和计费方式。
二、密钥与环境变量
API Key 不要写进代码、配置文件或日志,也不要提交到代码仓库。推荐通过环境变量读取:
export IMAGE_API_BASE_URL="https://你的提供方地址/v1"export IMAGE_API_KEY="你的密钥"export IMAGE_MODEL="文档中的模型名"pip install "openai==测试通过的版本" pillow
Windows PowerShell 中使用:
$env:IMAGE_API_KEY="你的密钥"
注意以下几点:
- 本地开发时,可以把变量写入
.env文件,并把该文件加入.gitignore。 - CI 或服务器环境,使用平台自带的密钥管理功能,不要明文保存在脚本里。
- 把测试通过的
openai版本号写入requirements.txt,避免依赖升级后行为变化。 - 日志中只记录请求编号和状态码,不记录完整请求头。
- 密钥一旦泄露,立即在控制台作废并重新生成。
三、请求配置
下表列出接入时需要配置的参数。数值为示例,需替换为模型文档中的值。
| 参数 | 含义 | 示例值 | 核对要点 |
|---|---|---|---|
| base_url | 接口地址 | https://.../v1 |
是否需要带 /v1 路径,以文档为准 |
| model | 模型名称 | 文档中的模型名 | 大小写和版本后缀必须完全一致 |
| n | 单次返回张数 | 1 | 先确认接口是否支持大于 1 的值 |
| size | 输出尺寸 | 1024x1024 |
必须在文档列出的尺寸中 |
| response_format | 返回格式 | b64_json |
不支持时改用 URL 方式并及时下载 |
| timeout | 单次请求超时(秒) | 60 | 高分辨率请求应适当调大 |
| retries | 对限流和超时的重试次数 | 3 | 对 400、401、404 类错误不重试 |
最小可运行代码如下,保存为 generate_image.py:
import base64import osimport timefrom pathlib import Pathfrom openai import OpenAI, APIError, RateLimitError, APITimeoutErrorfrom PIL import ImageBASE_URL = os.environ["IMAGE_API_BASE_URL"]API_KEY = os.environ["IMAGE_API_KEY"]MODEL = os.environ["IMAGE_MODEL"]ALLOWED_SIZES = {"1024x1024", "1536x1024", "1024x1536"} # 替换为模型文档列出的尺寸client = OpenAI(api_key=API_KEY, base_url=BASE_URL, timeout=60, max_retries=0)def call_with_retry(fn, retries=3):for attempt in range(retries + 1):try:return fn()except (RateLimitError, APITimeoutError) as e:if attempt == retries:raisewait = 2 ** attemptprint(f"第 {attempt + 1} 次失败({type(e).__name__}),{wait} 秒后重试")time.sleep(wait)def generate(prompt: str, size: str, n: int = 1, out_dir: str = "outputs") -> list[str]:if size not in ALLOWED_SIZES:raise ValueError(f"尺寸 {size} 不在允许列表中")Path(out_dir).mkdir(parents=True, exist_ok=True)start = time.perf_counter()try:resp = call_with_retry(lambda: client.images.generate(model=MODEL,prompt=prompt,size=size,n=n,response_format="b64_json",))except APIError as e:raise RuntimeError(f"请求失败:{e}") from eelapsed = time.perf_counter() - startpaths = []for i, item in enumerate(resp.data):if not item.b64_json:raise RuntimeError(f"第 {i} 张图片没有 b64_json 字段,请检查返回格式")path = Path(out_dir) / f"{int(time.time())}_{i}.png"path.write_bytes(base64.b64decode(item.b64_json))paths.append(str(path))print(f"耗时 {elapsed:.2f} 秒,返回 {len(paths)} 张,请求张数为 {n}")return pathsdef check_image(path: str, expected_size: str) -> bool:w, h = Image.open(path).sizereturn f"{w}x{h}" == expected_sizeif __name__ == "__main__":prompt = "一只橘色猫坐在窗台上,午后阳光,写实摄影风格,构图居中,背景虚化"files = generate(prompt, size="1024x1024", n=1)for f in files:print(f, "尺寸匹配" if check_image(f, "1024x1024") else "尺寸不匹配")
运行方式:
python generate_image.py
如果想先用命令行确认接口是否通,可以用 curl 发送同样的请求:
curl "$IMAGE_API_BASE_URL/images/generations" \-H "Authorization: Bearer $IMAGE_API_KEY" \-H "Content-Type: application/json" \-d "{\"model\": \"$IMAGE_MODEL\", \"prompt\": \"一只橘色猫坐在窗台上\", \"n\": 1, \"size\": \"1024x1024\"}"
返回结构的示例如下。字段名和嵌套层级因提供方而异,以实际返回为准,下面的 base64 内容已截断:
{"created": 1763000000,"data": [{"b64_json": "iVBORw0KGgoAAAANSUhEUg......(已截断)"}]}
四、提示词写法
一条可用的提示词通常包含以下几部分:
- 主体:画面中的核心对象,例如”一
相关文章推荐
发表评论
活动

登录后可评论,请前往 登录 或 注册