APIMart 图像API接入

APIMart 提供 OpenAI Images 兼容形式的第三方图像接口，但任务是异步的：提交后先得到 task_id，再查询任务并下载结果。第三方页面使用的模型名称、价格和“官方通道”标签属于该平台陈述，不能只凭兼容接口推断上游来源。

本文按 2026 年 9 月 9 日公开页面复核。当天 APIMart 市场页为 GPT Image 2 标示 $0.0085，已不同于旧稿的 $0.006；价格、计费单位和路由仍应以调用前控制台为准。

前置条件和安全边界

开始前需要：

一个自行注册并完成必要验证的 APIMart 账户。
控制台创建的独立测试 API Key，设置可用额度和告警。
本机有 curl 与 jq，并准备一个不含个人信息或商业机密的提示词。
已阅读平台隐私、内容、退款及模型路由条款；敏感业务还需完成供应商审查。
明确输出用途和版权、肖像、商标限制，不上传无权处理的参考图。

本文主例只生成一张 16:9、2K 的水彩橘猫图片。先把密钥放入当前终端环境变量，不要写进脚本、文章、命令历史截图或 Git：

read -rsp "APIMart API key: " APIMART_API_KEY
export APIMART_API_KEY
printf '\nKey loaded for this shell.\n'

预期只看到确认文字，不应打印密钥本身。共享电脑用完后执行 unset APIMART_API_KEY。

提交一个最小生成任务

按当前文档，请求地址是 POST https://api.apimart.ai/v1/images/generations，gpt-image-2 路由支持用 size 选择比例、用 resolution 选择 1k、2k 或 4k。

curl --fail-with-body --silent --show-error \
  --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer ${APIMART_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2",
    "prompt": "A ginger cat sitting on a windowsill at sunset, watercolor illustration, no text, no logo",
    "n": 1,
    "size": "16:9",
    "resolution": "2k"
  }' | tee /tmp/apimart-submit.json

成功响应的 data[0].status 应为 submitted，并包含 data[0].task_id。先验证字段再提取：

jq -e '.code == 200 and .data[0].task_id' /tmp/apimart-submit.json
task_id=$(jq -r '.data[0].task_id' /tmp/apimart-submit.json)

若校验失败，不要继续用空 ID 轮询；先查看 HTTP 状态和响应中的错误类型。

轮询并保存生成结果

使用文档指定的 GET /v1/tasks/{task_id} 查询。不要每秒高频轮询；按平台限流说明设置合理间隔，并为脚本设置最大等待时间。

curl --fail-with-body --silent --show-error \
  --url "https://api.apimart.ai/v1/tasks/${task_id}" \
  --header "Authorization: Bearer ${APIMART_API_KEY}" \
  | tee /tmp/apimart-task.json

jq '{status: .data.status, progress: .data.progress, error: .data.error}' \
  /tmp/apimart-task.json

预期状态依次可能是 submitted、processing、completed；failed 时读取 error.message，不要无限重试。只有 completed 才从 result.images 读取平台返回的图片 URL。

下载时使用明确文件名，并先限制协议与失败状态：

image_url=$(jq -er '.data.result.images[0].url' /tmp/apimart-task.json)
curl --fail --location --proto '=https' "$image_url" \
  --output ./ginger-cat-source.png
file ./ginger-cat-source.png

文档可能为不同路由规定不同链接有效期，应该生成后立即保存，而不是统一假设 24 小时。file 的预期结果应是实际 PNG、JPEG 或 WebP 图片；若得到 HTML/JSON，停止并检查 URL 或任务状态。

图片入库前做四项核验

首先实际打开原图，检查主体、手指/肢体、文字、标志、边缘和不应出现的水印。生成成功不等于图片准确，也不能把 AI 图当作产品截图、发票、新闻现场或历史证据。

然后检查：

技术格式：解码正常、尺寸符合页面需求，透明通道和色彩空间可用。
内容安全：没有真人隐私、伪造证明、受保护商标误导或提示词中未要求的敏感元素。
来源记录：保存日期、平台路由名、参数、任务 ID 与人工复核结论，但不保存密钥。
网页性能：在不破坏细节的前提下转为项目支持的本地格式并控制体积，转换后再次视觉检查。

不要声称每张都能压到 80KB。合适体积取决于尺寸、纹理、透明度和网站预算；品牌物料或印刷也不能只因为标注 4K 就直接交付，应检查实际像素、字体和输出规范。

价格与模型来源怎样验证

APIMart 当前把 gpt-image-2 与 gpt-image-2-official 列为不同路由，文档能力和价格可能不同。选择前记录完整模型 ID、分辨率、预计费用、失败是否计费和退款规则。平台称某路由为“official”不等于用户已与上游厂商直接签约。

一次任务的真实成本应从任务响应或账单读取：

单张实际成本 = 本次扣费 ÷ 成功且通过质量检查的图片数

把失败、重试、人工筛选和存储带宽也计入批量成本。旧稿用 5 次成功、28 秒延迟推导稳定性，样本不足；生产测试至少要跨时段记录成功率、P50/P95 延迟、扣费、内容拒绝和可用图片率。

若上游来源对合同、数据驻留或品牌合规很重要，应要求平台提供书面授权链和数据处理条款，或直接使用上游官方 API。不要仅比较宣传页的“比官方低百分之多少”。

定点排错与完成清单

返回 401/403：确认环境变量存在、密钥未多空格且有该模型权限；不要把完整密钥发到工单或群聊。

返回 400：对照当前文档检查模型、比例、分辨率与 n，不要假设其他图像 API 的参数可直接通用。

任务一直 processing：查看平台状态页和预计时间，达到自定超时后记录任务 ID 并停止轮询，避免重复提交造成多次扣费。

completed 但没有 URL：保存原始响应，确认 result.images 的当前结构，再联系官方支持；不要凭旧代码猜字段。

下载文件打不开：用 file 和响应头确认是不是过期链接或错误页面，重新查询任务获取仍有效的官方结果地址。

完成标准：

密钥只在安全环境变量中，未进入仓库与日志。
提交响应经过字段校验，任务 ID 非空。
轮询有合理间隔、失败分支和最大等待时间。
图片已保存为兼容本地文件并实际打开核验。
账单扣费、路由名、任务 ID 和质量结果已记录。
发布内容没有伪装成真实截图、账单或证据。
结束后已清理临时响应中的敏感信息并 unset APIMART_API_KEY。

资料来源：

本文未接受平台付费，不保证价格、上游来源、可用性或输出权利。调用前请核对最新条款和控制台账单。