API 通用约定
创建 Key、发出第一个请求，并了解所有接口共同遵循的规则。
Base URL
https://imagifly.net/api/v1所有接口都通过 HTTPS 传输 JSON。视频提交还额外接受 multipart/form-data。
鉴权
打开 API 控制台，登录后点击 创建。Key 只显示一次，请立即复制保存。
Key 形如 imf_...。每个账号最多一个有效 Key；创建新 Key 会使旧 Key 立即失效。请把 Key 放在环境变量里，而不是写进源码：
export IMAGIFLY_API_KEY="imf_your_key_here"用两个请求头之一传入 Key：
Authorization: Bearer imf_your_key_herex-api-key: imf_your_key_here没有有效 Key 的请求会返回 401 UNAUTHORIZED。Key 属于某一个账号；在控制台撤销后立即生效。
Key 只放在服务端
API Key 代表你的账号并消耗积分。不要把它打进浏览器产物或移动应用；请从后端调用 API。
没有 OAuth 流程，没有浏览器会话，也没有签名 URL。Key 是唯一的凭证。
第一个请求
先查模型目录，获取当前的模型 ID、价格和限制：
curl -s https://imagifly.net/api/v1/images/models \
-H "Authorization: Bearer $IMAGIFLY_API_KEY"然后提交一次图片生成：
curl -s -X POST https://imagifly.net/api/v1/images/generations \
-H "Authorization: Bearer $IMAGIFLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "A quiet tea shop on a rainy Shanghai street, warm window light",
"ratio": "16:9"
}'提交成功会返回 202 Accepted：
{
"ok": true,
"generation": {
"id": "gen_2f1c9a...",
"status": "generating",
"cost": 12,
"size": "1536x864",
"imageCount": 1
},
"settings": {
"model": "gpt-image-2",
"ratio": "16:9",
"resolutionTier": null,
"steps": null
}
}积分会在任务被接受时扣除。
轮询直到完成
POST /generations → 202 + generation.id (status: generating)
GET /generations/{id} → status: generating | success | failedcurl -s https://imagifly.net/api/v1/images/generations/gen_2f1c9a... \
-H "Authorization: Bearer $IMAGIFLY_API_KEY"{
"ok": true,
"generation": {
"id": "gen_2f1c9a...",
"status": "success",
"error": null,
"durationMs": 18420,
"imageUrls": ["https://imagedelivery.net/.../public"]
}
}每 2–5 秒轮询一次，直到状态进入终态。图片通常 10–60 秒完成，视频可能需要几分钟。没有 Webhook、回调或推送通道。status 为 failed 时，error 会说明原因，积分自动退回；成功的任务不退款。
使用结果
imageUrls（视频任务是 videoUrls）指向生成的文件。下载后存到你产品自己的媒体存储里；把这些 URL 当作临时分发链接，而不是永久存储。
响应结构
成功：
{ "ok": true, "...": "endpoint-specific fields" }失败：
{ "ok": false, "error": "INVALID_IMAGE_REQUEST", "message": "Unknown image model: foo." }完整的错误码列表见 错误。
积分
每个模型都有一个基础积分价格，在模型列表中以 credits 返回。最终价格可能取决于模型的选项——尺寸、分辨率档位、时长、质量或变体——实际扣费在受理响应中以 generation.cost 返回。
- 每个请求一张图片：
imageCount恒为1。 - 账号余额无法覆盖的请求会在任何工作开始前以
402拒绝。 - 账号套餐限制了同时运行的生成任务数；超出时返回
429 CONCURRENCY_LIMIT。
归属
任务按持有该 API Key 的账号隔离。读取其他账号的任务会返回 404 GENERATION_NOT_FOUND，与任务不存在时的响应完全一致。
模型
| 接口 | 鉴权 | 用途 |
|---|---|---|
GET /api/v1/images/models | 需要 | 图片模型及其价格和限制。 |
GET /api/v1/videos/models | 不需要 | 平台当前可用的视频模型。 |
模型列表是实时的：平台启用或下线模型时，条目会随之出现或消失；价格请从列表读取，不要写死。