logo

开源文生图模型接入实操:配置、提示词与出图验收

作者:JC2026.11.18 11:28浏览量:0

简介:本文给出开源文生图模型的接入步骤,包括用环境变量管理密钥、可运行的请求代码、提示词与分辨率配置、出图验收方法和常见错误排查。读者可按模板自行实测耗时、失败率和文件体积,得出适用于自己环境的结论,不必依赖未经核实的数字。

一、适用范围与前置条件

原始资料没有给出模型名称、版本和官方文档链接,因此本文不指定具体模型。文中的参数名、尺寸和数量上限都是示例,选定模型后必须以该模型的官方文档为准。原文中的约10秒生成、最高4096×4096、单次约10张、约16张参考图、约32000字符提示词等数字,目前都只是待核验的宣称,本文不把它们当作结论使用。

开始接入前,准备以下条件:

  1. 提供方账号,并在控制台创建 API Key。建议只开通生成图片所需的权限。
  2. Python 3.9 或更高版本。
  3. 两个依赖库:openai(用于调用兼容接口)和 pillow(用于读取图片尺寸)。
  4. 从官方文档确认以下信息:接口地址、模型名、支持的尺寸列表、单次返回张数 n 的上限、提示词最大长度、参考图数量上限、返回格式(base64 还是 URL)、限流规则和计费方式。

二、密钥与环境变量

API Key 不要写进代码、配置文件或日志,也不要提交到代码仓库。推荐通过环境变量读取:

  1. export IMAGE_API_BASE_URL="https://你的提供方地址/v1"
  2. export IMAGE_API_KEY="你的密钥"
  3. export IMAGE_MODEL="文档中的模型名"
  4. pip install "openai==测试通过的版本" pillow

Windows PowerShell 中使用:

  1. $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:

  1. import base64
  2. import os
  3. import time
  4. from pathlib import Path
  5. from openai import OpenAI, APIError, RateLimitError, APITimeoutError
  6. from PIL import Image
  7. BASE_URL = os.environ["IMAGE_API_BASE_URL"]
  8. API_KEY = os.environ["IMAGE_API_KEY"]
  9. MODEL = os.environ["IMAGE_MODEL"]
  10. ALLOWED_SIZES = {"1024x1024", "1536x1024", "1024x1536"} # 替换为模型文档列出的尺寸
  11. client = OpenAI(api_key=API_KEY, base_url=BASE_URL, timeout=60, max_retries=0)
  12. def call_with_retry(fn, retries=3):
  13. for attempt in range(retries + 1):
  14. try:
  15. return fn()
  16. except (RateLimitError, APITimeoutError) as e:
  17. if attempt == retries:
  18. raise
  19. wait = 2 ** attempt
  20. print(f"第 {attempt + 1} 次失败({type(e).__name__}),{wait} 秒后重试")
  21. time.sleep(wait)
  22. def generate(prompt: str, size: str, n: int = 1, out_dir: str = "outputs") -> list[str]:
  23. if size not in ALLOWED_SIZES:
  24. raise ValueError(f"尺寸 {size} 不在允许列表中")
  25. Path(out_dir).mkdir(parents=True, exist_ok=True)
  26. start = time.perf_counter()
  27. try:
  28. resp = call_with_retry(lambda: client.images.generate(
  29. model=MODEL,
  30. prompt=prompt,
  31. size=size,
  32. n=n,
  33. response_format="b64_json",
  34. ))
  35. except APIError as e:
  36. raise RuntimeError(f"请求失败:{e}") from e
  37. elapsed = time.perf_counter() - start
  38. paths = []
  39. for i, item in enumerate(resp.data):
  40. if not item.b64_json:
  41. raise RuntimeError(f"第 {i} 张图片没有 b64_json 字段,请检查返回格式")
  42. path = Path(out_dir) / f"{int(time.time())}_{i}.png"
  43. path.write_bytes(base64.b64decode(item.b64_json))
  44. paths.append(str(path))
  45. print(f"耗时 {elapsed:.2f} 秒,返回 {len(paths)} 张,请求张数为 {n}")
  46. return paths
  47. def check_image(path: str, expected_size: str) -> bool:
  48. w, h = Image.open(path).size
  49. return f"{w}x{h}" == expected_size
  50. if __name__ == "__main__":
  51. prompt = "一只橘色猫坐在窗台上,午后阳光,写实摄影风格,构图居中,背景虚化"
  52. files = generate(prompt, size="1024x1024", n=1)
  53. for f in files:
  54. print(f, "尺寸匹配" if check_image(f, "1024x1024") else "尺寸不匹配")

运行方式:

  1. python generate_image.py

如果想先用命令行确认接口是否通,可以用 curl 发送同样的请求:

  1. curl "$IMAGE_API_BASE_URL/images/generations" \
  2. -H "Authorization: Bearer $IMAGE_API_KEY" \
  3. -H "Content-Type: application/json" \
  4. -d "{\"model\": \"$IMAGE_MODEL\", \"prompt\": \"一只橘色猫坐在窗台上\", \"n\": 1, \"size\": \"1024x1024\"}"

返回结构的示例如下。字段名和嵌套层级因提供方而异,以实际返回为准,下面的 base64 内容已截断:

  1. {
  2. "created": 1763000000,
  3. "data": [
  4. {"b64_json": "iVBORw0KGgoAAAANSUhEUg......(已截断)"}
  5. ]
  6. }

四、提示词写法

一条可用的提示词通常包含以下几部分:

  1. 主体:画面中的核心对象,例如”一

发表评论

活动