图像生成API接入实战:代码、校验与排错

作者:蛮不讲李2026.11.18 11:28浏览量:0

简介:本文以占位符形式给出图像生成API的接入步骤:先核对服务商文档,再用环境变量保存密钥,完成文生图与多参考图请求,并封装成Agent工具。文末列出401、403、400、413和超时的排查方法,帮助读者跑通代码,并看清上线前还需补充的存储、缓存与安全措施。

适用读者

本文面向需要把图像生成能力接入自有应用的开发者和技术负责人。常见场景包括内容平台的配图服务、电商素材的批量生成,以及Agent工作流中的图像生成工具。阅读前需要了解Python基础、HTTP请求和JSON数据结构。

本文的代码使用占位符,不指向任何具体服务商。接口地址、字段名和参数取值都要以所用服务商的官方文档为准。

接入前确认的信息

动手前,请先在官方文档中确认下面六项内容。没有确认之前,不要直接运行示例代码。

项目 说明 未确认的风险
生成接口地址 完整URL,包括版本路径 请求发往错误地址,返回404
模型标识 请求体中model字段的取值 模型不存在,或生成结果与预期不符
鉴权方式 多数服务使用Bearer API Key;部分服务要求用Secret Key签名 返回401或403;签名方式不同时需要改写请求逻辑
请求字段与分辨率 字段名、取值范围,以及1K、2K、4K是否都支持 字段名错误会返回400
参考图限制 数量上限、单张大小上限、支持的格式 超限返回400或413
响应结构 图片地址在哪个字段,还是直接返回Base64,是否异步返回task_id 解析路径错误,取不到图片

准备环境

示例按Python 3.8及以上版本编写。建议为项目创建独立的虚拟环境:

  1. python -m venv .venv
  2. source .venv/bin/activate # Windows 使用 .venv\Scripts\activate
  3. pip install "requests>=2.31,<3" "pillow>=10.0,<12"

安装后运行下面的命令,记录实际版本。Pillow在不同版本间的缩放与保存细节可能略有差异,记录版本号有助于排查问题。

  1. python -c "import requests, PIL; print(requests.__version__, PIL.__version__)"

第一步:配置凭证

登录服务商控制台,在“密钥管理”或同类页面创建API Key。把接口地址、密钥和模型标识写入环境变量,不要写进代码,也不要提交到代码仓库。

macOS或Linux:

  1. export IMAGE_API_URL="替换为文档中的生成接口地址"
  2. export IMAGE_API_KEY="你的API Key"
  3. export IMAGE_MODEL_NAME="替换为文档中的模型标识"

Windows PowerShell:

  1. $env:IMAGE_API_URL="替换为文档中的生成接口地址"
  2. $env:IMAGE_API_KEY="你的API Key"
  3. $env:IMAGE_MODEL_NAME="替换为文档中的模型标识"

项目目录中若有.env文件,应把它加入.gitignore。日志中不要打印完整请求头,也不要把密钥拼进错误信息。密钥一旦泄露,应立即在控制台吊销,再创建新密钥。遇到401或403时,先检查密钥是否复制完整、是否过期、是否已被吊销。不要借用他人的密钥,也不要绕过鉴权。

第二步:最小文生图调用

下面的image_client.py包含鉴权、超时、错误分类和响应解析,是后续步骤的基础。

  1. import os
  2. import requests
  3. API_URL = os.getenv("IMAGE_API_URL")
  4. API_KEY = os.getenv("IMAGE_API_KEY")
  5. MODEL_NAME = os.getenv("IMAGE_MODEL_NAME")
  6. DEFAULT_TIMEOUT = 60 # 起始值,需用真实请求测量后调整
  7. if not API_URL or not API_KEY or not MODEL_NAME:
  8. raise SystemExit("请先设置 IMAGE_API_URL、IMAGE_API_KEY 和 IMAGE_MODEL_NAME")
  9. RETRYABLE_STATUS = {429, 500, 502, 503, 504}
  10. class ImageAPIError(RuntimeError):
  11. """统一的错误类型。code供程序判断,message供人阅读。"""
  12. def __init__(self, message, code="UNKNOWN", status_code=None,
  13. body=None, retryable=False):
  14. super().__init__(message)
  15. self.code = code
  16. self.status_code = status_code
  17. self.body = body # 仅用于本地调试,不要返回给模型或用户
  18. self.retryable = retryable
  19. def post_generation(payload: dict, timeout: float = DEFAULT_TIMEOUT) -> dict:
  20. headers = {
  21. "Authorization": f"Bearer {API_KEY}",
  22. "Content-Type": "application/json",
  23. }
  24. try:
  25. resp = requests.post(API_URL, headers=headers, json=payload, timeout=timeout)
  26. except requests.Timeout:
  27. raise ImageAPIError("请求超时,请检查网络或调大timeout",
  28. code="TIMEOUT", retryable=True) from None
  29. except requests.RequestException as e:
  30. raise ImageAPIError(f"网络请求失败: {type(e).__name__}",
  31. code="NETWORK", retryable=True) from None
  32. if resp.status_code != 200:
  33. code = {400: "BAD_REQUEST", 401: "AUTH_FAILED", 403: "FORBIDDEN",
  34. 404: "NOT_FOUND", 413: "PAYLOAD_TOO_LARGE",
  35. 429: "RATE_LIMITED"}.get(resp.status_code, "HTTP_ERROR")
  36. raise ImageAPIError(
  37. f"API返回 {resp.status_code}",
  38. code=code,
  39. status_code=resp.status_code,
  40. body=resp.text[:300],
  41. retryable=resp.status_code in RETRYABLE_STATUS,
  42. )
  43. try:
  44. return resp.json()
  45. except ValueError:
  46. raise ImageAPIError("响应不是合法JSON", code="BAD_RESPONSE") from None
  47. def extract_image_url(data: dict) -> str:
  48. # 字段路径是占位结构,需按文档改成真实路径
  49. url = (data.get("data") or {}).get("image_url")
  50. if not isinstance(url, str) or not url.startswith("https://"):
  51. raise ImageAPIError("响应中的图片地址缺失或格式异常,请对照文档检查字段路径",
  52. code="BAD_RESPONSE")
  53. return url
  54. def generate_image(prompt: str, resolution: str = "2K",
  55. timeout: float = DEFAULT_TIMEOUT) -> str:
  56. payload = {
  57. "model": MODEL_NAME,
  58. "prompt": prompt,
  59. "resolution": resolution,
  60. }
  61. data = post_generation(payload, timeout=timeout)
  62. return extract_image_url(data)
  63. if __name__ == "__main__":
  64. print(generate_image("一只戴着围巾的橘猫,清晨柔和的光线,摄影风格",
  65. resolution="1K"))

几点说明:

  • timeout=60只是起始值,不代表服务商给出的耗时。用真实请求测量多次,记录中位数和最大值,再设置超时。
  • extract_image_url要求地址以https开头。如果服务商在内网使用http,需要在这里调整校验规则。
  • 若响应直接返回Base64,用base64.b64decode解码后写入文件,并检查文件头是否为图片格式。文件名由程序生成,不直接使用服务端返回的名称。
  • 若响应返回task_id,需要按文档中的查询接口轮询。建议间隔2到5秒,设置总时长上限,失败状态直接报错,不要无限等待。
  • 首次调试使用1K分辨率,单次成本和耗时较低,便于先确认链路通畅。
  • 生成接口通常计费。重试前先确认文档是否支持幂等键,否则重试可能产生重复扣费。

第三步:多参考图调用

多参考图的常见做法是把每张图片压缩后编码为Base64格式的data URL,放入请求体的参考图字段。字段名、MIME类型和data URL前缀都要与文档一致。Base64编码会让数据体积增加约三分之一,所以发送前要在本地完成格式检查、数量检查和缩放。

新建image_refs.py:

  1. import base64
  2. import io
  3. from pathlib import Path
  4. from PIL import Image, UnidentifiedImageError
  5. from image_client import MODEL_NAME, extract_image_url, post_generation
  6. ALLOWED_SUFFIXES = {".jpg", ".jpeg", ".png"}
  7. MAX_REFS = 4 # 示例值,以服务商文档为准
  8. MAX_EDGE = 2048 # 最长边像素上限,超过则等比缩小
  9. MAX_ENCODED_BYTES = 4 * 1024 * 1024 # 单张编码后的字节上限,示例值
  10. JPEG_QUALITIES = (85, 75, 60) # 超限时逐级降低质量
  11. def _to_rgb(img: Image.Image) -> Image.Image:
  12. """透明区域铺白底,避免PNG透明部分变成黑色。"""
  13. if img.mode in ("RGBA", "LA") or (img.mode == "P" and "transparency" in img.info):
  14. rgba = img.convert("RGBA")
  15. bg = Image.new("RGB", rgba.size, (255, 255, 255))
  16. bg.paste(rgba, mask=rgba.split()[3])
  17. return bg
  18. return img.convert("RGB")
  19. def encode_reference(path: str) -> str:
  20. p = Path(path)
  21. if p.suffix.lower() not in ALLOWED_SUFFIXES:
  22. raise ValueError(f"不支持的图片格式: {p.name}")
  23. try:
  24. with Image.open(p) as src:
  25. img = _to_rgb(src)
  26. except (UnidentifiedImageError, OSError) as e:
  27. raise ValueError(f"无法读取图片: {p.name}") from e
  28. img.thumbnail((MAX_EDGE, MAX_EDGE))
  29. for quality in JPEG_QUALITIES:
  30. buf = io.BytesIO()
  31. img.save(buf, format="JPEG", quality=quality)
  32. if buf.tell() <= MAX_ENCODED_BYTES:
  33. b64 = base64.b64encode(buf.getvalue()).decode("ascii")
  34. return f"data:image/jpeg;base64,{b64}"
  35. raise ValueError(f"压缩后仍超过大小上限: {p.name},请减小原图或更换图片")
  36. def generate_with_references(prompt: str, ref_paths: list,
  37. resolution: str = "2K", timeout: float = 120) -> str:
  38. if not ref_paths:
  39. raise ValueError("至少需要一张参考图")
  40. if len(ref_paths) > MAX_REFS:
  41. raise ValueError(f"参考图数量超过上限 {MAX_REFS} 张")
  42. payload = {
  43. "model": MODEL_NAME,
  44. "prompt": prompt,
  45. "resolution": resolution,
  46. "reference_images": [encode_reference(p) for p in ref_paths], # 字段名以文档为准
  47. }
  48. data = post_generation(payload, timeout=timeout)
  49. return extract_image_url(data)

调用方式如下:

  1. url = generate_with_references(
  2. "把参考图中的人物放进海边场景",
  3. ["refs/a.jpg", "refs/b.png"],
  4. resolution="1K",
  5. )

几点说明:

  • 本地检查不通过时直接抛出明确的错误信息,不做静默处理,也不把错误的请求发给服务端。
  • 参考图的最长边、字节上限和压缩质量都是示例值,需要按文档要求调整。
  • 参考图超限时,服务端通常返回400或413。先检查压缩后的大小,再决定是否重试,不要盲目重复发送同一请求。
  • 有些服务商要求传入图片URL,而不是Base64。这种情况下需要先把图片上传到对象存储,再把生成的链接放入请求体。
  • 透明PNG在转换时会铺白底。如果业务需要保留透明区域,应先确认服务商是否支持带透明通道的输入。

第四步:结果校验

接口返回成功,不代表图片一定可用。下载后仍需检查状态码、Content-Type、大小和文件完整性。新建result_check.py:

  1. import io
  2. import requests
  3. from PIL import Image, UnidentifiedImageError
  4. from image_client import ImageAPIError
  5. MAX_DOWNLOAD_BYTES = 30 * 1024 * 1024 # 下载上限,示例值
  6. ALLOWED_CONTENT_TYPES = {"image/png", "image/jpeg", "image/webp"}
  7. RETRYABLE_STATUS = {429, 500, 502, 503, 504}
  8. def fetch_and_verify(url: str, timeout: float = 30) -> bytes:
  9. # 下载时不携带API Key。图片地址通常是带签名的临时链接,不应把密钥发给其他域名。
  10. try:
  11. resp = requests.get(url, timeout=timeout, stream=True)
  12. except requests.Timeout:
  13. raise ImageAPIError("下载图片超时", code="TIMEOUT", retryable=True) from None
  14. except requests.RequestException as e:
  15. raise ImageAPIError(f"下载图片失败: {type(e).__name__}",
  16. code="NETWORK", retryable=True) from None
  17. try:
  18. if resp.status_code != 200:
  19. raise ImageAPIError(f"下载返回 {resp.status_code}",
  20. code="DOWNLOAD_FAILED",
  21. status_code=resp.status_code,
  22. retryable=resp.status_code in RETRYABLE_STATUS)
  23. ctype = resp.headers.get("Content-Type", "").split(";")[0].strip().lower()
  24. if ctype not in ALLOWED_CONTENT_TYPES:
  25. raise ImageAPIError(f"返回内容类型不是允许的图片类型: {ctype or '空'}",
  26. code="BAD_IMAGE")
  27. declared = resp.headers.get("Content-Length", "")
  28. if declared.isdigit() and int(declared) > MAX_DOWNLOAD_BYTES:
  29. raise ImageAPIError("图片超过下载大小上限", code="BAD_IMAGE")
  30. content = bytearray()
  31. for chunk in resp.iter_content(64 * 1024):
  32. content.extend(chunk)
  33. if len(content) > MAX_DOWNLOAD_BYTES:
  34. raise ImageAPIError("图片超过下载大小上限", code="BAD_IMAGE")
  35. finally:
  36. resp.close()
  37. try:
  38. with Image.open(io.BytesIO(content)) as img:
  39. img.verify() # 检查文件结构是否完整
  40. except (UnidentifiedImageError, OSError, SyntaxError) as e:
  41. raise ImageAPIError("图片数据损坏或格式无法识别", code="BAD_IMAGE") from e
  42. return bytes(content)

校验项包括:

  • HTTP状态码是否为200。
  • Content-Type是否为允许的图片类型。部分CDN会返回application/octet-stream,遇到这种情况应先查看文档,再决定是否放宽规则。
  • 文件大小是否超过上限,包括声明的长度和实际读取的长度。
  • 文件结构是否完整。img.verify()能发现截断或损坏的文件。
  • 保存到本地或对象存储时,扩展名应根据文件内容决定,不要直接使用URL的后缀。

如果业务对分辨率有要求,可在verify()之后再打开图片,读取img.size与预期比较。

agent-">第五步:Agent工具封装

Agent调用工具时,需要清晰的入参定义、可预测的返回值和受控的文件访问范围。下面的agent_tool.py把前面的函数包装成一个工具,并加入重试逻辑。

```python
import os
import time
from pathlib import Path

from image_client import ImageAPIError, generate_image
from image_refs import MAX_REFS, generate_with_references
from result_check import fetch_and_verify

ALLOWED_RESOLUTIONS = {“1K”, “2K”, “4K”} # 以文档确认的枚举为准
MAX_PROMPT_CHARS = 500
REF_DIR = Path(os.getenv(“IMAGE_REF_DIR”, “./refs”)).resolve()

TOOL_SCHEMA = {
“name”: “generate_image”,
“description”: “根据文字描述生成图片,可选附带参考图。返回图片地址。”,
“parameters”: {
“type”: “object”,
“properties”: {
“prompt”: {“type”: “string”, “maxLength”: MAX_PROMPT_CHARS,
“description”: “图片描述”},
“resolution”: {“type”: “string”, “enum”: sorted(ALLOWED_RESOLUTIONS),
“default”: “2K”},
“reference_names”: {“type”: “array”, “maxItems”: MAX_REFS,
“items”: {“type”: “string”},
“description”: “IMAGE_REF_DIR目录内的文件名”},
},
“required”: [“prompt”],
“additionalProperties”: False,
},
}

def call_with_retry(fn, args, attempts: int = 3, base_delay: float = 2.0, **kwargs):
“””只对标记为retryable的错误重试,采用指数退避。”””
for attempt in range(1, attempts + 1):
try:
return fn(
args, kwargs)
except ImageAPIError as e:
if not e.retryable or attempt == attempts:
raise
time.sleep(base_delay * 2
(attempt - 1))

def _safe_ref_path(name: str) -> Path:
p = (REF_DIR / name).resolve()
if REF_DIR not in p.parents:
raise ValueError(“参考图必须位于允许目录内”)
return p

def _error(code: str, message: str) -> dict:
return {“ok”: False, “error”: {“code”: code, “message”: message}}

def agent_generate_image(prompt: str, resolution: str = “2K”,
reference_names=None) -> dict:
if not isinstance(prompt, str) or not prompt.strip():
return _error(“INVALID_PROMPT”, “prompt不能为空”)
if len(prompt) > MAX_PROMPT_CHARS:
return _error(“INVALID_PROMPT”, f”prompt超过{MAX_PROMPT_CHARS}字”)
if resolution not in ALLOWED_RESOLUTIONS:
return _error(“INVALID_RESOLUTION”, “分辨率不在允许范围内”)

  1. refs = reference_names or []
  2. if not all(isinstance(n, str) for n in refs):
  3. return _