API の共通仕様

ベース URLCopy Anchor Link

https://imagifly.net/api/v1

すべてのエンドポイントは HTTPS 上の JSON です。動画の送信では multipart/form-data も受け付けます。

認証Copy Anchor Link

API コンソールを開いてサインインし、Create をクリックします。キーは 1 度しか表示されないので、すぐにコピーしてください。

キーは imf_... のような形式です。1 つのアカウントで有効なキーは 1 つだけで、新しいキーを作成すると以前のキーは失効します。キーはソースコードではなく環境変数に保存してください。

export IMAGIFLY_API_KEY="imf_your_key_here"

次の 2 つのヘッダーのいずれかで送信します。

Authorization: Bearer imf_your_key_here

x-api-key: imf_your_key_here

有効なキーのないリクエストは 401 UNAUTHORIZED を返します。キーは 1 つのアカウントに属し、コンソールで失効させると即座に反映されます。

OAuth フロー、ブラウザセッション、署名付き URL はありません。認証情報はキーのみです。

最初のリクエストCopy Anchor Link

まずモデルカタログで、現在のモデル 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
  }
}

クレジットはタスクが受け付けられた時点で差し引かれます。

完了までポーリングするCopy Anchor Link

POST /generations  →  202 + generation.id (status: generating)
GET  /generations/{id}  →  status: generating | success | failed

curl -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 に理由が示され、クレジットは自動的に返還されます。成功したタスクは返還されません。

結果を利用するCopy Anchor Link

imageUrls（動画タスクの場合は videoUrls）が生成ファイルを指します。ダウンロードして、プロダクトでメディアを保存している場所に保存してください。これらの URL は永続ストレージではなく、一時的な配信用リンクとして扱ってください。

レスポンスの形式Copy Anchor Link

成功時：

{ "ok": true, "...": "endpoint-specific fields" }

失敗時：

{ "ok": false, "error": "INVALID_IMAGE_REQUEST", "message": "Unknown image model: foo." }

コードの全一覧はエラーを参照してください。

クレジットCopy Anchor Link

すべてのモデルには基本クレジット価格があり、モデル一覧で credits として返されます。最終価格はモデルのオプション（サイズ、解像度ティア、長さ、品質、バリアント）によって変わる場合があり、実際の課金額は受け付け時のレスポンスで generation.cost として返されます。

• 1 リクエストにつき画像 1 枚です。imageCount は常に 1 です。
• アカウントの残高でまかなえないリクエストは、処理が始まる前に 402 で拒否されます。
• アカウントのプランによって同時に実行できる生成数が制限されます。上限を超えると 429 CONCURRENCY_LIMIT が返ります。

所有権Copy Anchor Link

タスクは API キーを所有するアカウントに紐づきます。別のアカウントのタスクを参照すると、存在しないタスクと同じ 404 GENERATION_NOT_FOUND が返ります。

モデルCopy Anchor Link

モデル一覧は常に最新です。プラットフォームがモデルを有効化・提供終了すると、エントリが追加されたり削除されたりします。価格はハードコードせず、一覧から読み取ってください。