HTTP API
Image generation
Submit image tasks, poll results and read the image model catalog.
Submit a task
POST /api/v1/images/generationsRequest body
| Field | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Image model ID from the model catalog. |
prompt | string | Yes | What to draw. |
negativePrompt | string | No | What to avoid. |
ratio | string | No | Aspect ratio, default Auto. Examples: 1:1, 16:9, 9:16, 4:3, 3:4. |
quality | string | No | standard or high. |
resolutionTier | string | No | 1k or 2k; supported only by some models. |
steps | number | string | No | Reasoning steps, or the presets low, standard, high. |
referenceImages | array | No | Reference images, each { "base64": "..." }. |
Reference image rules:
- Base64 only (a
data:image/png;base64,prefix is accepted); URLs are not. - Maximum 10MB per image after decoding.
- The count limit is model-specific; read
referenceImageLimitfrom the model list. - If the chosen model does not support references, the server switches to a fallback model that does.
settings.modelin the response is the model that actually ran.
Example
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"
}'Response 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
}
}| Field | Description |
|---|---|
generation.id | Task ID used for polling. |
generation.cost | Credits charged for this task. |
generation.size | Output size that was chosen. |
generation.imageCount | Number of images; always 1. |
settings | Normalized parameters that actually applied. |
Poll a task
GET /api/v1/images/generations/{id}{
"ok": true,
"generation": {
"id": "gen_2f1c9a...",
"status": "success",
"error": null,
"durationMs": 18420,
"imageUrls": ["https://imagedelivery.net/.../public"]
}
}| Field | Description |
|---|---|
status | generating, success or failed. |
error | Failure reason; null on success. |
durationMs | Task duration in milliseconds. |
imageUrls | Image URLs on success; an empty array otherwise. |
A missing task, or one owned by another account, returns 404 GENERATION_NOT_FOUND.
Model catalog
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
}
]
}Treat the response as the source of truth: prices, tiers and limits change as models are updated. credits is the base price; options such as resolution, quality and steps can change the final charge.
Notes
ratioacceptsAutoplus the ratios a model supports; unsupported values are rejected with400 INVALID_IMAGE_REQUEST.- Prompt content is also checked by the model provider. A prompt rejected by the provider produces a failed task with an explanatory
error, not an HTTP error on submit. - Submit a new task to retry; there is no retry endpoint.