APIMart 图片生成 API 怎么用？从请求到拿到图片 URL
简答：APIMart 图片生成 API 的基本流程是：准备 API Key，使用当前文档展示的 Base URL 和模型 ID，向 POST /v1/images/generations 提交 prompt，读取 data[0].task_id，再通过 GET /v1/tasks/{task_id} 轮询，完成后从 data.result.images 中提取图片 URL。本文示例使用页面当前展示的 https://api.apimart.ai/，但域名、模型和参数可能更新，发布或接入前应再次对照当前文档核验。
定义：APIMart 图片生成 API 是通过统一 HTTP 接口提交文生图或参考图编辑任务，并以任务 ID 查询生成结果的图像调用方式。
先试这一步：完成一次最小文生图调用
本文是面向开发者的第三方接入说明，不代表 APIMart 官方公告或官方下载页面。按截至 2026-10-31 检索到的模型页面，图片生成通常采用异步任务流程：提交 POST /v1/images/generations，读取 data[0].task_id，再查询 GET /v1/tasks/{task_id}。完成状态下，可从 data.result.images[0].url[0] 读取图片地址；失败时查看 data.error.message。当前模型页面示例展示了这套请求和响应结构。
| 项目 | 示例值或检查方法 | 注意事项 |
|---|---|---|
| Base URL | https://api.apimart.ai | 这是本次检索到的模型页面示例，实际以当前文档为准。 |
| 认证 | Authorization: Bearer $APIMART_API_KEY | Key 只放服务端环境变量，不写入前端或公开仓库。 |
| 生成端点 | POST /v1/images/generations | 请求体至少核对 model 与 prompt。 |
| 成功判定 | 收到 task_id，随后任务状态变为 completed | 不要把“提交成功”误认为“图片已经生成”。 |
如果只想验证链路，先用一张图片、一个简单 prompt、默认分辨率和默认质量，不要一开始同时加入参考图、透明背景和批量数量。这样更容易判断问题究竟来自 Key、模型、参数还是任务处理。
准备账户、额度、API Key 与模型 ID
- 按照当前 APIMart 控制台流程完成账户和可用额度准备；具体注册、充值、限额和计费条件不要根据旧文章推断，应以当前页面和文档为准。
- 在 API Keys 页面创建密钥，并保存到服务端环境变量，例如
APIMART_API_KEY。不要把真实 Key 粘贴到浏览器脚本、前端打包文件、截图或公共代码仓库。 - 选择一个当前可用的图像模型，并复制页面展示的精确模型 ID。比如检索到的 GPT Image 2.6 页面示例使用
gpt-image-2.6；Wan 2.7 页面示例使用wan2.7-image。模型名、版本和参数可能变化，不能只凭搜索词或旧代码填写。Wan 2.7 模型页面和GPT Image 2.6 模型页面均提供了对应示例。
选择模型时，先按任务类型判断：纯文字生成用文生图模型；需要保留产品外形、颜色或构图时，选择支持参考图的模型；需要透明背景时，同时核对 background 与 output_format 是否兼容。平台的文生图目录将模型按文字渲染、速度、参考图和风格等方向归类，但具体能力仍应以单个模型页的参数表为准。文生图模型分类页面提供了这些选择维度。
cURL、Python 与 JavaScript 最小示例
cURL：先提交任务
下面示例采用当前检索到的页面结构。请把模型 ID 和 prompt 替换为你的实际需求，不要把真实 Key 写进命令历史或日志。
export APIMART_API_KEY='YOUR_API_KEY'
curl -X POST 'https://api.apimart.ai/v1/images/generations' \
-H "Authorization: Bearer $APIMART_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model":"gpt-image-2.6","prompt":"浅色木桌上的陶瓷咖啡杯，柔和窗边光线，右侧留白","size":"1:1","resolution":"1k","quality":"auto","n":1,"output_format":"png","background":"auto"}'
预期先检查响应是否为 JSON，并确认 data[0].task_id 存在。不要只看 HTTP 200；网关或上游也可能返回结构化错误信息。
Python：提交并轮询
import os, time, requests
base = "https://api.apimart.ai"
headers = {"Authorization": f"Bearer {os.environ['APIMART_API_KEY']}"}
payload = {
"model": "gpt-image-2.6",
"prompt": "浅色木桌上的陶瓷咖啡杯，柔和窗边光线，右侧留白",
"size": "1:1",
"resolution": "1k",
"quality": "auto",
"n": 1,
"output_format": "png",
"background": "auto"
}
resp = requests.post(f"{base}/v1/images/generations", headers=headers, json=payload, timeout=60)
resp.raise_for_status()
task_id = resp.json()["data"][0]["task_id"]
for _ in range(200):
r = requests.get(f"{base}/v1/tasks/{task_id}", headers=headers, timeout=30)
r.raise_for_status()
task = r.json()["data"]
if task.get("status") == "completed":
print(task["result"]["images"][0]["url"][0])
break
if task.get("status") == "failed":
raise RuntimeError(task.get("error", {}).get("message", "generation failed"))
time.sleep(3)
else:
raise TimeoutError("任务尚未完成，请保存 task_id 后继续查询")
JavaScript：服务端调用原则
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.APIMART_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
model: "gpt-image-2.6",
prompt: "浅色木桌上的陶瓷咖啡杯，柔和窗边光线，右侧留白",
size: "1:1",
resolution: "1k",
quality: "auto",
n: 1,
output_format: "png",
background: "auto"
})
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const data = JSON.parse(text);
const taskId = data.data?.[0]?.task_id;
if (!taskId) throw new Error("响应中没有 task_id");
JavaScript 示例特意先读取文本再解析 JSON，便于识别网关返回的 HTML、纯文本或非标准错误。生产代码还应设置轮询上限、记录脱敏后的请求信息，并保存 task ID 便于后续查询。
图片编辑、参考图与核心参数怎么填
图片编辑通常在同一生成端点中加入 image_urls。当前 GPT Image 2.6 页面示例要求参考图使用可访问的 HTTP 或 HTTPS 图片地址；本地文件选择只用于页面预览，并不会自动替你生成公开 URL。该页面还列出最多 16 个参考图地址的工作台限制，但不同模型可能不同，不能跨模型套用。参考图字段说明可用于核对当前示例。
{"model":"gpt-image-2.6","prompt":"将参考图中的产品放到浅色石材台面上，保留产品形状、颜色和标签","size":"auto","resolution":"1k","quality":"auto","n":1,"output_format":"png","background":"auto","image_urls":["https://example.com/product.png"]}
| 参数 | 用途 | 核验重点 |
|---|---|---|
model | 选择模型 | 必须使用当前页面展示的精确 ID。 |
prompt | 描述主体、场景、构图和修改要求 | 编辑时区分“要改什么”和“要保留什么”。 |
size | 设置画面比例 | 可选值由模型决定，不能假设所有模型一致。 |
resolution | 选择分辨率档位 | 页面中的 1K、2K、4K 是请求配置，不应直接推断原生像素。 |
quality | 设置质量档位 | 先用默认值验证接口，再按需求调整。 |
output_format | 选择 png、jpeg 或 webp | 透明背景通常要搭配 PNG 或 WebP。 |
image_urls | 传入参考图片 | 使用模型要求的可访问地址、数量和格式。 |
异步任务没有图片时，按 401、404、429 和超时分流
- 401 或 403：先确认环境变量是否真的加载，检查是否重复写了
Bearer，再确认请求发往正确 Base URL。不要把 Key 打印到日志；只记录是否存在、长度和脱敏前缀。 - 404：分别检查域名、路径、模型 ID 和 task ID。生成端点与任务查询端点不是同一个路径；模型名称拼写错误也可能被网关表现为资源不存在。
- 429：先降低并发、减少同时提交的任务数量，并确认账户额度或限速信息。不要无间隔重试；可采用指数退避，并设置最大重试次数。具体限速值未在本次核验资料中确认，应以当前文档或响应头为准。
- 超时：区分“提交请求超时”和“任务生成时间较长”。如果已经拿到
task_id，优先保存 ID 后继续查询，不要立即重复提交，以免产生重复任务。HTTP 客户端应分别设置提交和查询超时。 - 任务失败：读取
data.error.message，根据错误修改模型、prompt、参考图 URL 或参数；不要只依据 HTTP 状态码判断失败原因。当前模型页面明确展示了 completed 与 failed 两类结果读取路径。任务结果字段说明
最小成功判定应同时满足三点：提交响应包含 task ID；查询响应状态为 completed；结果对象中存在可访问的图片 URL。任何一步不满足，都应保留原始状态码、脱敏响应和 task ID，再进行下一轮排查。
模型选择与费用核对：不要把旧价格写死
如果你只需要验证接口链路，先选择当前页面有完整请求示例的模型；如果需要参考图编辑，优先查看模型页是否明确列出 image_urls；如果需要透明背景，检查输出格式和背景字段的组合限制。平台文生图页面将模型按文字渲染、速度、批量参考图和风格等维度介绍，但具体价格、计费单位、限速和可用地区属于动态信息，本文不写死具体数值。模型分类页也提示不同模型可能按图片、Token 或其他模型规则计费，因此预算应以当前模型价格表和最终响应为准。
实际接入时建议建立一张内部核验表：模型 ID、请求端点、支持参数、计费单位、并发限制、失败是否计费、结果 URL 有效期和最近核验时间。查不到的字段标记为“未核实”，不要用其他模型或旧版本页面补全。
如果你正准备把图片生成能力接入自己的应用，可将上面的最小请求先放在服务端运行，再逐步增加参考图、质量、分辨率和并发控制，避免一次改动过多导致问题难以定位。
常见问题
APIMart 图片生成 API 使用哪个 Base URL？
本次核验到的 GPT Image 2.6 页面示例使用 https://api.apimart.ai/，并将其用于生成和任务查询示例。但域名、路由和版本可能更新，正式接入前应以当前 API 文档和模型页面为准。
为什么提交成功后没有直接返回图片？
当前检索到的图片模型示例采用异步任务格式。提交后先读取 data[0].task_id，再调用 GET /v1/tasks/{task_id} 查询；状态为 completed 后，才从 data.result.images 中提取图片 URL。
本地图片可以直接放进 image_urls 吗？
不能直接把本地路径当作公开图片地址。当前模型页面示例要求 image_urls 使用可访问的 HTTP 或 HTTPS URL；本地文件选择可能只用于页面预览，是否支持上传、Data URI 或 Base64 要按具体模型文档核对。
401、404 和 429 应该先查什么？
401 先查 Key、Bearer 格式和环境变量；404 查 Base URL、路径、模型 ID 与 task ID；429 查额度、并发和限速，再采用带上限的退避重试。不要把某一个网关返回码直接当成所有模型的统一规则。
APIMart 图片生成 API 的价格是多少？
价格和计费单位可能按模型、分辨率、质量、图片数量或 Token 变化。本次资料没有为通用图片 API 核实一个可适用于所有模型的固定价格，因此应以当前模型价格页和最终响应为准。
相关阅读
- 先核对 APIMart API Key、环境变量与 Base URL
- 继续了解 APIMart OpenAI 兼容接口的通用配置
- 遇到 401 时按 Key、Bearer 和端点排查
- 遇到 429 时检查限流、额度与重试
- 图片任务超时后保存 task_id 并继续诊断
参考资料
- GPT Image 2.6 API 图片工作台：请求示例、参数与异步任务字段（apimart.ai）
- Wan 2.7 Image API：模型 ID、图像模式与任务流程
- 文生图 API：模型分类、调用方式与费用核验提示（apimart.ai）