简介:本文以占位符形式给出图像生成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及以上版本编写。建议为项目创建独立的虚拟环境:
python -m venv .venvsource .venv/bin/activate # Windows 使用 .venv\Scripts\activatepip install "requests>=2.31,<3" "pillow>=10.0,<12"
安装后运行下面的命令,记录实际版本。Pillow在不同版本间的缩放与保存细节可能略有差异,记录版本号有助于排查问题。
python -c "import requests, PIL; print(requests.__version__, PIL.__version__)"
登录服务商控制台,在“密钥管理”或同类页面创建API Key。把接口地址、密钥和模型标识写入环境变量,不要写进代码,也不要提交到代码仓库。
macOS或Linux:
export IMAGE_API_URL="替换为文档中的生成接口地址"export IMAGE_API_KEY="你的API Key"export IMAGE_MODEL_NAME="替换为文档中的模型标识"
Windows PowerShell:
$env:IMAGE_API_URL="替换为文档中的生成接口地址"$env:IMAGE_API_KEY="你的API Key"$env:IMAGE_MODEL_NAME="替换为文档中的模型标识"
项目目录中若有.env文件,应把它加入.gitignore。日志中不要打印完整请求头,也不要把密钥拼进错误信息。密钥一旦泄露,应立即在控制台吊销,再创建新密钥。遇到401或403时,先检查密钥是否复制完整、是否过期、是否已被吊销。不要借用他人的密钥,也不要绕过鉴权。
下面的image_client.py包含鉴权、超时、错误分类和响应解析,是后续步骤的基础。
import osimport requestsAPI_URL = os.getenv("IMAGE_API_URL")API_KEY = os.getenv("IMAGE_API_KEY")MODEL_NAME = os.getenv("IMAGE_MODEL_NAME")DEFAULT_TIMEOUT = 60 # 起始值,需用真实请求测量后调整if not API_URL or not API_KEY or not MODEL_NAME:raise SystemExit("请先设置 IMAGE_API_URL、IMAGE_API_KEY 和 IMAGE_MODEL_NAME")RETRYABLE_STATUS = {429, 500, 502, 503, 504}class ImageAPIError(RuntimeError):"""统一的错误类型。code供程序判断,message供人阅读。"""def __init__(self, message, code="UNKNOWN", status_code=None,body=None, retryable=False):super().__init__(message)self.code = codeself.status_code = status_codeself.body = body # 仅用于本地调试,不要返回给模型或用户self.retryable = retryabledef post_generation(payload: dict, timeout: float = DEFAULT_TIMEOUT) -> dict:headers = {"Authorization": f"Bearer {API_KEY}","Content-Type": "application/json",}try:resp = requests.post(API_URL, headers=headers, json=payload, timeout=timeout)except requests.Timeout:raise ImageAPIError("请求超时,请检查网络或调大timeout",code="TIMEOUT", retryable=True) from Noneexcept requests.RequestException as e:raise ImageAPIError(f"网络请求失败: {type(e).__name__}",code="NETWORK", retryable=True) from Noneif resp.status_code != 200:code = {400: "BAD_REQUEST", 401: "AUTH_FAILED", 403: "FORBIDDEN",404: "NOT_FOUND", 413: "PAYLOAD_TOO_LARGE",429: "RATE_LIMITED"}.get(resp.status_code, "HTTP_ERROR")raise ImageAPIError(f"API返回 {resp.status_code}",code=code,status_code=resp.status_code,body=resp.text[:300],retryable=resp.status_code in RETRYABLE_STATUS,)try:return resp.json()except ValueError:raise ImageAPIError("响应不是合法JSON", code="BAD_RESPONSE") from Nonedef extract_image_url(data: dict) -> str:# 字段路径是占位结构,需按文档改成真实路径url = (data.get("data") or {}).get("image_url")if not isinstance(url, str) or not url.startswith("https://"):raise ImageAPIError("响应中的图片地址缺失或格式异常,请对照文档检查字段路径",code="BAD_RESPONSE")return urldef generate_image(prompt: str, resolution: str = "2K",timeout: float = DEFAULT_TIMEOUT) -> str:payload = {"model": MODEL_NAME,"prompt": prompt,"resolution": resolution,}data = post_generation(payload, timeout=timeout)return extract_image_url(data)if __name__ == "__main__":print(generate_image("一只戴着围巾的橘猫,清晨柔和的光线,摄影风格",resolution="1K"))
几点说明:
timeout=60只是起始值,不代表服务商给出的耗时。用真实请求测量多次,记录中位数和最大值,再设置超时。extract_image_url要求地址以https开头。如果服务商在内网使用http,需要在这里调整校验规则。base64.b64decode解码后写入文件,并检查文件头是否为图片格式。文件名由程序生成,不直接使用服务端返回的名称。多参考图的常见做法是把每张图片压缩后编码为Base64格式的data URL,放入请求体的参考图字段。字段名、MIME类型和data URL前缀都要与文档一致。Base64编码会让数据体积增加约三分之一,所以发送前要在本地完成格式检查、数量检查和缩放。
新建image_refs.py:
import base64import iofrom pathlib import Pathfrom PIL import Image, UnidentifiedImageErrorfrom image_client import MODEL_NAME, extract_image_url, post_generationALLOWED_SUFFIXES = {".jpg", ".jpeg", ".png"}MAX_REFS = 4 # 示例值,以服务商文档为准MAX_EDGE = 2048 # 最长边像素上限,超过则等比缩小MAX_ENCODED_BYTES = 4 * 1024 * 1024 # 单张编码后的字节上限,示例值JPEG_QUALITIES = (85, 75, 60) # 超限时逐级降低质量def _to_rgb(img: Image.Image) -> Image.Image:"""透明区域铺白底,避免PNG透明部分变成黑色。"""if img.mode in ("RGBA", "LA") or (img.mode == "P" and "transparency" in img.info):rgba = img.convert("RGBA")bg = Image.new("RGB", rgba.size, (255, 255, 255))bg.paste(rgba, mask=rgba.split()[3])return bgreturn img.convert("RGB")def encode_reference(path: str) -> str:p = Path(path)if p.suffix.lower() not in ALLOWED_SUFFIXES:raise ValueError(f"不支持的图片格式: {p.name}")try:with Image.open(p) as src:img = _to_rgb(src)except (UnidentifiedImageError, OSError) as e:raise ValueError(f"无法读取图片: {p.name}") from eimg.thumbnail((MAX_EDGE, MAX_EDGE))for quality in JPEG_QUALITIES:buf = io.BytesIO()img.save(buf, format="JPEG", quality=quality)if buf.tell() <= MAX_ENCODED_BYTES:b64 = base64.b64encode(buf.getvalue()).decode("ascii")return f"data:image/jpeg;base64,{b64}"raise ValueError(f"压缩后仍超过大小上限: {p.name},请减小原图或更换图片")def generate_with_references(prompt: str, ref_paths: list,resolution: str = "2K", timeout: float = 120) -> str:if not ref_paths:raise ValueError("至少需要一张参考图")if len(ref_paths) > MAX_REFS:raise ValueError(f"参考图数量超过上限 {MAX_REFS} 张")payload = {"model": MODEL_NAME,"prompt": prompt,"resolution": resolution,"reference_images": [encode_reference(p) for p in ref_paths], # 字段名以文档为准}data = post_generation(payload, timeout=timeout)return extract_image_url(data)
调用方式如下:
url = generate_with_references("把参考图中的人物放进海边场景",["refs/a.jpg", "refs/b.png"],resolution="1K",)
几点说明:
接口返回成功,不代表图片一定可用。下载后仍需检查状态码、Content-Type、大小和文件完整性。新建result_check.py:
import ioimport requestsfrom PIL import Image, UnidentifiedImageErrorfrom image_client import ImageAPIErrorMAX_DOWNLOAD_BYTES = 30 * 1024 * 1024 # 下载上限,示例值ALLOWED_CONTENT_TYPES = {"image/png", "image/jpeg", "image/webp"}RETRYABLE_STATUS = {429, 500, 502, 503, 504}def fetch_and_verify(url: str, timeout: float = 30) -> bytes:# 下载时不携带API Key。图片地址通常是带签名的临时链接,不应把密钥发给其他域名。try:resp = requests.get(url, timeout=timeout, stream=True)except requests.Timeout:raise ImageAPIError("下载图片超时", code="TIMEOUT", retryable=True) from Noneexcept requests.RequestException as e:raise ImageAPIError(f"下载图片失败: {type(e).__name__}",code="NETWORK", retryable=True) from Nonetry:if resp.status_code != 200:raise ImageAPIError(f"下载返回 {resp.status_code}",code="DOWNLOAD_FAILED",status_code=resp.status_code,retryable=resp.status_code in RETRYABLE_STATUS)ctype = resp.headers.get("Content-Type", "").split(";")[0].strip().lower()if ctype not in ALLOWED_CONTENT_TYPES:raise ImageAPIError(f"返回内容类型不是允许的图片类型: {ctype or '空'}",code="BAD_IMAGE")declared = resp.headers.get("Content-Length", "")if declared.isdigit() and int(declared) > MAX_DOWNLOAD_BYTES:raise ImageAPIError("图片超过下载大小上限", code="BAD_IMAGE")content = bytearray()for chunk in resp.iter_content(64 * 1024):content.extend(chunk)if len(content) > MAX_DOWNLOAD_BYTES:raise ImageAPIError("图片超过下载大小上限", code="BAD_IMAGE")finally:resp.close()try:with Image.open(io.BytesIO(content)) as img:img.verify() # 检查文件结构是否完整except (UnidentifiedImageError, OSError, SyntaxError) as e:raise ImageAPIError("图片数据损坏或格式无法识别", code="BAD_IMAGE") from ereturn bytes(content)
校验项包括:
application/octet-stream,遇到这种情况应先查看文档,再决定是否放宽规则。img.verify()能发现截断或损坏的文件。如果业务对分辨率有要求,可在verify()之后再打开图片,读取img.size与预期比较。
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”, “分辨率不在允许范围内”)
refs = reference_names or []if not all(isinstance(n, str) for n in refs):return _