生成静态资产时选图片 API
如果最终资产是单帧图片，而分辨率、参考图数量或质量是主要控制项，就使用图片模型。这适合商品图、活动视觉、概念探索和图片转换，不需要额外建立视频处理链路。
把 imya 当成图片与视频生成、任务查询、实时积分计费和生成资产的 API 层。GPT Image 2、Seedream 5.0 Pro、Hailuo 2.3 和 Seedance 2.0 当前以开发者预览契约提供文档。
每个模型页都写清可调用接口、公开参数、实时计费返回和任务生命周期。
用户在设置里创建 API Key。
用 model 和 prompt 发起生成请求。
轮询任务接口，直到成功或失败。
把返回的图片或视频 URL 存到自己的产品里。
AI 模型 API 接入指南
先确定产品最终要返回图片还是视频，再选择工作流真正需要的控制项。图片 API 每个接受的任务返回一张静态结果；视频 API 则从文本或起始图片生成动态结果。先把这个选择定清楚，请求校验、费用展示、队列和结果处理会更易维护。Imya 的四个模型页使用同一套鉴权和异步任务模式，可以复用基础设施，同时为每个模型保持严格的请求类型。
如果最终资产是单帧图片，而分辨率、参考图数量或质量是主要控制项，就使用图片模型。这适合商品图、活动视觉、概念探索和图片转换，不需要额外建立视频处理链路。
如果输出必须包含动作，就使用视频模型。先确定任务从提示词还是输入图片开始，然后在提交前校验时长和分辨率。视频任务有独立的并发上限，应与图片任务分开排队。
每个模型的请求字段以对应的开发者文档为准，准确扣费以当次请求返回的 credits_reserved 为准。
需要提示词生图，或工作流需要最多 16 张参考图时，选择 GPT Image 2。它提供 1K、2K 和 4K 输出分辨率。每个接受的任务返回一张图片，即使提供多张参考图，结果处理也保持一致。
阅读 GPT Image 2 API 文档需要提示词生图并使用最多 10 张参考图时，选择 Seedream 5.0 Pro。公开请求支持 basic 和 high 两种质量。一个任务返回一张图片，客户端应把参考图视为输入，而不是预期的输出数量。
阅读 Seedream API（5.0 Pro）文档需要文生视频或图生视频，且时长为 6 秒或 10 秒时，选择 Hailuo 2.3。公开 API 提供 Standard 和 Fast 模式。创建异步任务前，应校验所选模式、时长和必需的输入图片。
阅读 Hailuo 2.3 API 文档需要文生视频或图生视频，且输出分辨率为 480p、720p 或 1080p 时，选择 Seedance 2.0。时长可以设置为 4 到 15 秒的整数。这两个参数都应在服务端校验，避免不支持的组合进入任务队列。
阅读 Seedance 2.0 API 文档所有公开模型路由都用于服务端调用。不要在浏览器代码中放置 API Key，并在自己的后端统一处理任务创建、轮询、计费记录和用户可见状态。
使用 Bearer Token 发送 Imya API Key。每一次逻辑生成 POST 都要携带唯一 Idempotency-Key。网络重试使用相同键和相同请求体时，API 会返回原任务，不会重复创建或扣费。
新任务被接受时，credits_reserved 中的准确积分会被原子扣除。展示或记录这个返回值，不要在客户端重新实现定价规则，这样套餐调整和模型价格才能与真实扣费保持一致。
把返回的 id 与内部作业记录一起持久化。建议至少每 5 秒请求一次 GET /v1/tasks/{id}，直到 status 为 succeeded 或 failed。更频繁的请求仍会占用 API Key 速率额度，但不会刷新上游状态。公开 status 只有 pending、processing、succeeded 和 failed。当前接入方式是轮询，暂不提供 webhook、SDK 和批量提交。
公开错误已经净化，应展示安全的错误码和消息，不要猜测或暴露基础设施细节。任务 30 分钟后仍未完成会判定失败。符合退款条件时，status 仍是 failed：结算中 error.code 为 refund_pending，之后由 credits_refunded 确认一次性退款，原到期日不会延长。
把真实用户流量导入模型路由前，先完成以下控制。
以下答案适用于四个模型文档的共同决策。
先接入能产出第一个用户流程所需媒体的路由。静态图片对比参考图数量、分辨率和质量；视频对比文生或图生、时长、分辨率和模式。第一套任务生命周期可靠后，再加第二个模型。
可以。为一次逻辑生成创建一个 Idempotency-Key，连接失败或超时后使用相同请求体复用它。API 会返回原任务，不会再扣费。如果请求体改变，应使用新键创建新请求。
服务端计算实时价格，并在接受新任务时原子扣分。响应以 credits_reserved 返回准确数量。符合退款条件的任务失败时，包括到达 30 分钟上限，结算中 error.code 可能是 refund_pending；credits_refunded 确认一次性退款，原到期时间不变。
免费账户的已存储图片结果可用 7 天，有效付费或 Lifetime 账户最长 30 天。需要长期保存的资产应在窗口关闭前下载或复制。删除后响应的 status 为 failed，error.code 为 media_deleted，界面可以明确告知结果已过期。
打开最接近第一个用例的模型文档，复制已验证的请求结构，完整实现“创建—轮询—返回结果”后再增加其他模型。