API conventions

Base URLCopy Anchor Link

https://imagifly.net/api/v1

All endpoints are JSON over HTTPS. Video submission also accepts multipart/form-data.

AuthenticationCopy Anchor Link

Open the API console, sign in, and click Create. The key is shown once, so copy it immediately.

Keys look like imf_.... Each account can have one active key; creating a new key revokes the previous one. Store the key in an environment variable rather than in source code:

export IMAGIFLY_API_KEY="imf_your_key_here"

Send it in one of two headers:

Authorization: Bearer imf_your_key_here

x-api-key: imf_your_key_here

Requests without a valid key return 401 UNAUTHORIZED. A key belongs to one account; revoking it in the console takes effect immediately.

There is no OAuth flow, no browser session and no signed URL. The key is the only credential.

Your first requestCopy Anchor Link

Check the model catalog for current IDs, prices and limits:

curl -s https://imagifly.net/api/v1/images/models \
  -H "Authorization: Bearer $IMAGIFLY_API_KEY"

Then submit an image generation:

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"
  }'

A successful submit returns 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
  }
}

Credits are deducted when the task is accepted.

Poll until it finishesCopy 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"]
  }
}

Poll every 2–5 seconds until the status is terminal. Images usually finish in 10–60 seconds; videos can take several minutes. There is no webhook, callback or push channel. When status is failed, error explains why and the credits are returned automatically; successful tasks are not refunded.

Use the outputCopy Anchor Link

imageUrls (or videoUrls for video tasks) point at the generated files. Download and store them wherever your product keeps media; treat the URLs as temporary delivery links rather than permanent storage.

Response envelopeCopy Anchor Link

Success:

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

Failure:

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

See Errors for the full list of codes.

CreditsCopy Anchor Link

Every model has a base credit price, returned as credits in the model list. The final price can depend on the model's options — size, resolution tier, duration, quality or variant — and the exact charge is returned as generation.cost in the accepted response.

• One image per request: imageCount is always 1.
• A request that cannot be covered by the account balance is rejected with 402 before any work starts.
• An account's plan limits how many generations can run at once; exceeding it returns 429 CONCURRENCY_LIMIT.

OwnershipCopy Anchor Link

Tasks are scoped to the account that owns the API key. Reading another account's task returns 404 GENERATION_NOT_FOUND, the same response as a task that does not exist.

ModelsCopy Anchor Link

Model lists are live: entries can appear or disappear as the platform enables or retires models, and prices are read from the list rather than hard-coded.