调用AI 3D模型生成API时，返回空结果往往不是模型没有生成能力，而是请求在参数或格式环节被服务端拦了下来。空结果的表现形式不止一种：有的接口返回HTTP 200但响应体是空字符串，有的返回code为0但data里的模型文件链接为空，还有的异步任务一直处于排队状态。排查这类问题，不能只盯着生成引擎，要先确认请求是否完整送达、参数是否被真正解析。下面从请求链路、参数校验、格式检查和异步轮询几个角度展开。
一、先定义空结果：响应链路中的断点
空结果并不总是服务端主动返回空数据。客户端看到的“空”，可能是网络层超时、反向代理截断、SDK封装吞掉异常，或者响应解析时字段路径写错。排查第一步是绕过封装，用最原始的HTTP请求打印状态码、响应头和原始文本。下面这个Python片段可以快速判断请求是否到达服务端。
import requests
url = "https://api.ipipp.com/v1/3d/generate"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
payload = {
"prompt": "a wooden chair",
"format": "glb"
}
resp = requests.post(url, json=payload, headers=headers, timeout=30)
print("status:", resp.status_code)
print("headers:", dict(resp.headers))
print("body:", resp.text[:500])
如果上面打印出来的状态码是400或422，而代码里只判断了resp.json().get("data")，就可能把错误响应误解成空结果。服务端返回错误时通常带有message字段，说明是哪个参数不合法。即使状态码是200，响应体也可能是{"code": 0, "data": null}这种逻辑空值，需要继续检查业务状态字段。建议在请求封装层增加非2xx和业务code的日志，把原始响应完整保留下来，方便定位是否真正拿到模型URL。
另一个容易忽略的断点是代理和网关。如果请求走了nginx或API网关，超时时间设置过短、请求体过大被413拒绝、或者响应体超过缓冲被截断，都会表现为空结果。排查时可以用curl加-v参数观察完整响应头，尤其是Content-Length和Transfer-Encoding。若响应的Content-Length为0但服务端日志显示已生成，大概率是网关缓冲策略导致，需要调整客户端读取方式或增加重试。
二、请求参数校验：类型、边界和枚举值
AI 3D模型API的参数通常包括prompt、model、resolution、format、texture、polygon_count等。很多空结果来自参数类型错误：比如resolution传了字符串"1024"而不是整数1024，服务端在JSON Schema校验阶段直接拒绝；或者format写成"obj"，但接口只支持"glb"和"usdz"，导致业务层返回空列表。更隐蔽的是可选参数传了null，某些服务端会把它当作“不处理”，但另一些会抛出解析异常。
下面是一个请求前校验函数，覆盖常见字段。它会在发送请求前抛出明确的错误信息，避免无效调用。
def validate_payload(payload: dict) -> None:
required = {"prompt", "format"}
missing = required - payload.keys()
if missing:
raise ValueError(f"缺少必填字段: {missing}")
prompt = payload["prompt"]
if not isinstance(prompt, str) or not prompt.strip():
raise ValueError("prompt 必须是非空字符串")
if len(prompt) > 1000:
raise ValueError("prompt 长度超过限制")
fmt = payload["format"]
allowed_formats = {"glb", "usdz", "obj", "stl"}
if fmt not in allowed_formats:
raise ValueError(f"format 不支持: {fmt}")
if "resolution" in payload:
resolution = payload["resolution"]
if not isinstance(resolution, int) or resolution < 256 or resolution > 4096:
raise ValueError("resolution 必须是 256-4096 的整数")
if "texture" in payload:
texture = payload["texture"]
if not isinstance(texture, bool):
raise ValueError("texture 必须是布尔值")
参数校验不能只依赖前端表单，服务端API对类型和枚举通常比页面更严格。例如resolution在部分接口中同时支持整数和字符串，但文档没有明说时，最好按官方示例传整数。另一个高频问题是参数名大小写：prompt和Prompt可能被服务端区分，前者正常，后者被忽略后导致生成条件缺失。建议封装请求时使用精确字段名，并在测试环境对每个参数做一次最小可用请求，确认服务端能接受。
对于文件类型的参数，比如参考图上传，校验重点是文件大小和实际内容。服务端可能限制20MB，但客户端只检查扩展名，用户把一张无效图片改名成png上传，服务端读取时返回空。可以用Python标准库imghdr或Pillow读取文件头，确认是真实图片后再发送。如果API同时接受文本和文件混合参数，需要特别小心multipart/form-data的字段顺序，有些网关对顺序敏感。
三、格式检查：JSON结构、请求头和文件上传
格式错误是返回空结果的另一大来源。JSON请求体如果包含NaN、Infinity或未定义值，在部分语言的JSON库中会直接序列化失败，或者服务端解析后把整个对象丢弃。Python标准库json.dumps默认会输出NaN和Infinity，但这不符合严格JSON规范。发送前应该用allow_nan=False做一次检查，遇到非法数值立即抛出异常。同时要避免在JSON字符串中使用单引号，虽然有些接口容忍，但严格解析器会报错。
import json
payload = {"prompt": "a chair", "quality": float("nan")}
try:
body = json.dumps(payload, allow_nan=False)
except ValueError as exc:
print("JSON包含非法数值:", exc)
请求头同样重要。如果Content-Type没有设置成application/json，而是默认的text/plain，服务端可能直接返回415或把请求体当纯文本忽略。使用requests库时，用json=payload会自动设置类型，但用data=json.dumps(payload)则需要手动添加头。另一个常见错误是Authorization头部拼接时多出空格或换行，导致鉴权失败后返回空数据。建议用统一请求头模板，并在日志中隐去敏感信息后打印完整头部。
如果接口需要上传图片或模型参考文件，格式检查要提前到文件读取阶段。单纯看扩展名并不可靠，应该读取文件前几个字节判断magic number，png文件头是\x89PNG，jpg是\xFF\xD8，webp是RIFF....WEBP。文件大小超出限制时，服务端可能直接断开连接，客户端却收到空响应。可以在发送前用os.stat获取大小，并设置合理的分块上传或压缩策略。对于Base64编码的参数，需要确认编解码后大小是否在限制内，而不是只看编码字符串长度。
四、异步任务与响应解析：别把未完成当空结果
很多AI 3D生成接口采用异步模式，提交请求后返回task_id，需要通过查询接口轮询结果。空结果常常发生在轮询逻辑上：任务状态是processing，但代码只读取data.result，字段不存在就返回空；或者任务已经failed，但错误信息在另一个字段里，客户端没有处理。正确做法是先判断status，只有succeeded状态才读取模型文件URL，失败状态要记录error_message。
import time
def poll_until_done(task_id: str, get_status, timeout=300):
start = time.time()
while time.time() - start < timeout:
resp = get_status(task_id)
if resp.status_code != 200:
raise RuntimeError(f"查询任务失败: HTTP {resp.status_code}")
data = resp.json()
status = data.get("status")
if status == "succeeded":
return data.get("result", {})
if status == "failed":
raise RuntimeError(f"任务失败: {data.get('error_message')}")
time.sleep(5)
raise TimeoutError("任务超时")
响应解析本身也需要格式检查。有些接口返回的JSON带有BOM头，Python的resp.json()通常能处理，但其他语言手动解析时会因为首字符不可见报错。可以先用resp.text.lstrip('\ufeff')去掉BOM。另外，服务端可能在响应外层包一层分页结构，模型链接在data.items[0].url，客户端却读data.url，自然为空。建议对响应做一次结构校验，使用assert或Pydantic验证关键路径存在，而不是直接访问。
轮询频率也很关键。间隔太短会触发限流，服务端返回429时客户端如果没有重试逻辑，就会把空响应当作最终结果。间隔太长又浪费调试时间。一般建议前10次间隔5秒，之后逐渐增加到15秒，同时设置总超时时间，例如生成复杂模型可能需要10分钟。若超过超时仍未完成，保留任务ID，通过查询接口继续跟踪，而不是重复提交新任务。
AI 3D模型API请求参数校验格式检查修改时间：2026-09-29 08:44:23