HTTP API
画像生成
画像タスクの送信、結果のポーリング、画像モデルカタログの取得を行います。
タスクを送信する
POST /api/v1/images/generationsリクエストボディ
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
model | string | はい | モデルカタログの画像モデル ID。 |
prompt | string | はい | 描画したい内容。 |
negativePrompt | string | いいえ | 避けたい要素。 |
ratio | string | いいえ | アスペクト比。既定値は Auto。例：1:1、16:9、9:16、4:3、3:4。 |
quality | string | いいえ | standard または high。 |
resolutionTier | string | いいえ | 1k または 2k。一部のモデルのみ対応しています。 |
steps | number | string | いいえ | 推論ステップ数、または low、standard、high のプリセット。 |
referenceImages | array | いいえ | 参照画像。各要素は { "base64": "..." } の形式です。 |
参照画像のルール：
- Base64 のみ（
data:image/png;base64,のプレフィックスは使用可）。URL は使用できません。 - デコード後の 1 画像あたりの上限は 10MB です。
- 枚数の上限はモデルごとに異なります。モデル一覧の
referenceImageLimitを参照してください。 - 選択したモデルが参照画像に対応していない場合、サーバーは対応している代替モデルに切り替えます。レスポンスの
settings.modelが実際に実行されたモデルです。
例
curl -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": "Minimalist poster of a mountain at dawn, warm gradient sky",
"ratio": "16:9",
"quality": "high"
}'レスポンス 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
}
}| フィールド | 説明 |
|---|---|
generation.id | ポーリングに使用するタスク ID。 |
generation.cost | このタスクで消費されたクレジット。 |
generation.size | 選択された出力サイズ。 |
generation.imageCount | 画像枚数。常に 1 です。 |
settings | 実際に適用された正規化済みのパラメータ。 |
タスクをポーリングする
GET /api/v1/images/generations/{id}{
"ok": true,
"generation": {
"id": "gen_2f1c9a...",
"status": "success",
"error": null,
"durationMs": 18420,
"imageUrls": ["https://imagedelivery.net/.../public"]
}
}| フィールド | 説明 |
|---|---|
status | generating、success、failed のいずれか。 |
error | 失敗理由。成功時は null。 |
durationMs | タスクの所要時間（ミリ秒）。 |
imageUrls | 成功時は画像 URL。それ以外は空配列。 |
存在しないタスク、または別のアカウントが所有するタスクは 404 GENERATION_NOT_FOUND を返します。
モデルカタログ
GET /api/v1/images/models{
"ok": true,
"models": [
{
"id": "gpt-image-2",
"label": "GPT Image 2",
"credits": 12,
"resolutionTiers": ["1k", "2k"],
"resolutionQuality": "high",
"defaultResolutionTier": "1k",
"supportsSteps": false,
"referenceImageLimit": 4
}
]
}レスポンスを正として扱ってください。価格、ティア、上限はモデルの更新に伴って変わります。credits は基本価格で、解像度・品質・ステップなどのオプションによって最終的な課金額が変わる場合があります。
補足
ratioはAutoとモデルが対応する比率を受け付けます。非対応の値は400 INVALID_IMAGE_REQUESTで拒否されます。- プロンプトの内容はモデル提供元でも検査されます。提供元に拒否されたプロンプトは、送信時の HTTP エラーではなく、説明を含む
errorを持つ失敗タスクになります。 - 再試行するには新しいタスクを送信してください。再試行用のエンドポイントはありません。