简介:本教程面向开发者与技术团队,讲解如何接入支持文生图、参考图生成和图像编辑的图像生成服务。内容覆盖环境准备、接口调用、参考图组织、参数设置、结果校验和常见故障排查,并给出可复用的通用代码示例。读完后,读者可以独立完成一次完整的图像生成调用,并建立稳定、可维护的调用流程。
本教程要帮助读者完成一套可运行的图像生成调用流程。完成后,读者应能够:
教程不依赖某一家厂商的专有接口。文中的字段名、参数名和鉴权方式都是通用写法,实际接入时以所选服务的官方文档为准。
本教程适合以下读者:
常见的适用场景包括:
在编写代码之前,需要确认以下条件。缺少任何一项,后续步骤都可能无法顺利执行。
建议为应用单独创建调用凭证,并限制其只能访问图像生成相关接口。这样即使凭证泄露,影响范围也可控。
读者需要了解以下通用概念:
先确定服务提供的调用方式。常见的接入方式有三种:
本文示例采用同步 HTTP 接口。如果服务方提供异步模式,需要在第六步增加任务状态查询逻辑。
为什么要先确认:接入方式决定了超时设置、重试策略和结果处理方式。如果一开始按同步模式写代码,之后再改为异步,通常需要重写大部分调用逻辑。
调用凭证属于敏感信息,应当通过环境变量或密钥管理服务注入,不要写入源代码或提交到代码仓库。
export IMAGE_API_ENDPOINT="https://<服务端点>/v1/images"export IMAGE_API_KEY="<你的调用凭证>"
注意事项:
把网络请求、鉴权头和错误处理集中到一个函数或类中。这样后续的文生图、参考图和编辑功能都可以复用同一套逻辑。
import osimport requestsAPI_ENDPOINT = os.environ["IMAGE_API_ENDPOINT"]API_KEY = os.environ["IMAGE_API_KEY"]def post_json(payload, timeout=60):headers = {"Authorization": f"Bearer {API_KEY}","Content-Type": "application/json",}resp = requests.post(API_ENDPOINT, json=payload, headers=headers, timeout=timeout)resp.raise_for_status()return resp.json()
说明:
timeout 必须设置。图像生成耗时较长,但无限等待会占用线程和连接,最终拖垮服务。raise_for_status() 会在非 2xx 状态码时抛出异常,避免把错误响应当成正常结果处理。Bearer 是常见的鉴权格式,实际格式以服务文档为准。文生图只需要提供提示词和输出尺寸等基础参数。提示词的质量对结果影响最大,建议按以下结构编写:
def text_to_image(prompt, size="1024x1024"):payload = {"prompt": prompt,"size": size,}return post_json(payload)
注意事项:
size 等字段名称是示例写法,需要替换为服务文档中的实际字段;参考图用于让生成结果继承已有图片的特征。常见用途包括统一品牌视觉风格、保持人物或商品外观一致,或在已有构图上做变体。
部分模型支持同时输入多张参考图。可接受的数量上限、图片格式和大小限制以服务文档为准,实现时应先读取配置,再做校验。
import base64from pathlib import PathMAX_REFERENCE_IMAGES = 4 # 以服务文档中的上限为准def encode_image(path):data = Path(path).read_bytes()return base64.b64encode(data).decode("utf-8")def text_to_image_with_refs(prompt, reference_paths, size="1024x1024"):if len(reference_paths) > MAX_REFERENCE_IMAGES:raise ValueError(f"参考图数量不能超过 {MAX_REFERENCE_IMAGES} 张")payload = {"prompt": prompt,"size": size,"reference_images": [encode_image(p) for p in reference_paths],}return post_json(payload)
为什么要在本地先校验:如果把超出数量或格式不符的图片直接发给服务,往往只能得到一个不够直观的错误信息。本地校验能更快定位问题,也能减少无效调用产生的费用。
提示词写法建议:当提示词与参考图冲突时,结果可能偏向其中一方。建议明确说明需要保留参考图的哪些特征,例如”保留第一张图的人物姿态,背景改为海边”。
图像编辑需要同时提供原图和修改指令。与文生图相比,编辑的关键在于说明”改什么”和”不改什么”。
def edit_image(source_path, instruction, size=None):payload = {"mode": "edit", # 编辑模式标识,以文档为准"image": encode_image(source_path),"instruction": instruction,}if size:payload["size"] = sizereturn post_json(payload)
编辑指令的写法:
依赖关系:编辑请求依赖第一步确认的接入方式。若服务使用单独的编辑端点或任务类型,需要替换上面的 mode 字段和请求地址。
图像生成接口通常返回图片的 Base64 数据或可下载的地址。两种情况都需要写对应的处理逻辑。
import base64from pathlib import Pathdef save_result(response, output_path):# 字段名为示例,需要替换为文档中的实际字段if "image_base64" in response:data = base64.b64decode(response["image_base64"])Path(output_path).write_bytes(data)elif "image_url" in response:import requestsimg = requests.get(response["image_url"], timeout=60)img.raise_for_status()Path(output_path).write_bytes(img.content)else:raise RuntimeError("响应中没有可识别的图片字段")return output_path
注意事项:
调用过程中涉及的主要配置项如下。具体取值范围以服务文档为准。
| 配置项 | 含义 | 取值逻辑 | 风险提示 |
|---|---|---|---|
| 端点地址 | 接口访问入口 | 按环境区分开发、测试、生产 | 误用生产地址会影响线上数据 |
| 凭证 | 调用身份 | 每个应用或环境独立配置 | 泄露会导致额度被盗用 |
| 超时时间 | 单次请求最长等待时间 | 生成耗时较长,建议留有余量 | 过短会误判失败,过长会占用资源 |
| 输出尺寸 | 生成图片的分辨率 | 按用途选择,不必一味追求最高 | 尺寸越大,耗时和成本越高 |
| 参考图数量 | 单次请求可附带的参考图张数 | 不超过服务声明的上限 | 超限会被服务端拒绝 |
| 重试次数 | 失败后的自动重试次数 | 通常 2 到 3 次 | 对计费接口,重试可能重复扣费 |
重试策略:对于 429(请求过多)和 5xx 等临时性错误,可以使用指数退避重试,例如第一次等待 2 秒,第二次等待 4 秒。对于 400(请求参数错误)和 401(鉴权失败),重试没有意义,应直接报错并记录。
import timedef with_retry(func, max_retries=3, base_delay=2):for attempt in range(max_retries + 1):try:return func()except requests.HTTPError as e:status = e.response.status_coderetryable = status == 429 or status >= 500if not retryable or attempt == max_retries:raisetime.sleep(base_delay * (2 ** attempt))
下面的流程把前面的步骤串联起来,演示一个完整的调用过程:先生成一张基础图,再以该图为参考生成系列变体,最后对其中一张做局部编辑。
prompts = "一只橘猫坐在木质窗台上,午后暖光,水彩插画风格"# 1. 文生图,生成基础图base = with_retry(lambda: text_to_image(prompts))save_result(base, "output/base.png")# 2. 以基础图为参考,生成同风格变体variant = with_retry(lambda: text_to_image_with_refs("同一只橘猫在雨天的街角,保持水彩风格",["output/base.png"],))save_result(variant, "output/variant.png")# 3. 编辑变体图,修改背景edited = with_retry(lambda: edit_image("output/variant.png","将背景的雨水改为晴天的蓝色天空,保持猫的姿态不变",))save_result(edited, "output/edited.png")
流程示意:
提示词 → 文生图 → 基础图 → 参考图生成 → 变体图 → 图像编辑 → 最终图↓ ↑保存记录 ──────────────────────────────────→ 保存记录
每个中间结果都保存到本地,既方便人工检查,也便于某一步失败后从断点继续,而不必从头调用。
接入完成后,应从以下几个方面验证结果:
建议建立小型测试集:准备十到二十组固定的提示词和参考图,每次接入或升级