API Reference

The section below outlines the parameters, status codes, and callbacks supported by our developer generation API.

Get Templates

Fetch all published studio design templates to find template IDs for generating images.

GET/api/v1/users/studio/gallery

Query Parameters

Parameter	Type	Description
page	number	The page number for pagination. (Default: 1)
limit	number	The number of items to return per page. (Default: 20)
search	string	Filters templates by title or prompt matching the query.
ratio	string	Filters by aspect ratio (e.g. `1:1`, `9:16`, `16:9`, etc.).
gender	string	Filters by model gender (`MALE`, `FEMALE`, `UNISEX`, `KIDS`).
toolName	string	Filters by target generation tool (e.g., `IMAGE_TO_IMAGE`, `TEXT_TO_IMAGE`).

Response (200 OK)

{
  "data": [
    {
      "id": "8b5258e7-ff4e-48a5-9275-c54d31e9c20f",
      "title": "Casual Denim Jacket",
      "prompt": "model wearing a denim jacket, clean bright studio background",
      "mediaUrl": "https://cdn.aeimgai.com/templates/denim.jpg",
      "aspectRatio": "1:1",
      "resolution": "STANDARD"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalCount": 1,
    "totalPages": 1,
    "hasNextPage": false
  }
}

Generate Image Endpoint

POST/api/v1/external/generate-image

Security Warning: Never Invoke from Frontend Client-Side

This endpoint requires authentication via your secret x-api-key header. Always execute this API call from a **server-side runtime** (e.g., backend server, serverless worker, or Next.js API route / Server Function). Do not trigger this endpoint directly from browser-based React components or client code to prevent token theft and credits exhaustion.

Request Body Parameters

Field	Type	Description
type	"custom" \| "templated"	Required. Set to "custom" to use a custom prompt, or "templated" to use an existing template ID.
templatedId	string (UUID)	Required if type is "templated". The template prompt ID to generate from.
prompt	string	Required if type is "custom". The prompt describing the styling to apply to your fashion model.
imageUrls	string[]	Optional. Array of public URL strings of clothing or reference images to reference.
resolution	string	Optional. Model quality: `FAST`, `STANDARD`, `HIGH_QUALITY`, or `ULTRA_HD`. (Default: "STANDARD")
aspectRatio	string	Optional. Aspect ratio options: `1:1`, `9:16`, `16:9`, `4:5`, `3:2`, `AUTO`. (Default: "1:1")
numImages	number	Optional. Number of image variations to output (1-20). (Default: 1)
webhookUrl	string	Optional. A custom endpoint to override your developer key-level webhook URL.
notes	object	Optional. A custom metadata object (key-value pairs) that will be stored and returned back in the webhook payload.

Response (200 OK)

{
"request_id": "8b5258e7-ff4e-48a5-9275-c54d31e9c20f",
"status": "QUEUE"
}

Webhook Callbacks

Because AI image generation takes several seconds, the API is asynchronous. When your generation is complete, aeImgAI will send a POST request containing the results to your configured webhook URL.

Webhook Event Types

Every webhook request payload contains an event parameter indicating the type of notification being received:

Event Type	Description
TEST	Triggered when generating or updating an API key. Used to verify the integrity/responsiveness of your webhook endpoint. Expects a successful response status code (e.g. `2xx`).
GENERATION.[TYPE].COMPLETED	Triggered when an asynchronous generation job successfully finishes and the output is stored. The `[TYPE]` placeholder represents the generation type: `IMAGE` or `VIDEO` (e.g., `GENERATION.IMAGE.COMPLETED`).
GENERATION.[TYPE].FAILED	Triggered when the generation job encounters an error. The `[TYPE]` placeholder represents the generation type: `IMAGE` or `VIDEO` (e.g., `GENERATION.IMAGE.FAILED`).

Verification/Test Payload

{
  "event": "TEST",
  "timestamp": "2026-06-12T11:17:28.000Z",
  "message": "This is a test event sent during webhook verification."
}

Success Payload

{
  "event": "GENERATION.IMAGE.COMPLETED",
  "request_id": "8b5258e7-ff4e-48a5-9275-c54d31e9c20f",
  "status": "COMPLETED",
  "images": [
    { "url": "https://cdn.aeimgai.com/output/img_123.png" }
  ],
  "notes": {
    "userId": "user_123456",
    "internalRef": "ref_98765"
  },
  "meta": {
    "prompt": "a beautiful dress on a runway model",
    "resolution": "STANDARD",
    "aspectRatio": "1:1"
  }
}

Failure Payload

{
  "event": "GENERATION.IMAGE.FAILED",
  "request_id": "8b5258e7-ff4e-48a5-9275-c54d31e9c20f",
  "status": "FAILED",
  "failed_reason": "Fal AI provider timed out during generation",
  "notes": {
    "userId": "user_123456",
    "internalRef": "ref_98765"
  },
  "meta": {
    "prompt": "a beautiful dress on a runway model",
    "resolution": "STANDARD",
    "aspectRatio": "1:1"
  }
}

Status Codes

Status Code	Meaning	Description
200 OK	Success	The generation was successfully queued. Response contains the request ID.
400 Bad Request	Validation Error	Required fields are missing, or constraints (like image limits) were violated.
401 Unauthorized	Invalid API Key	The header "x-api-key" is either missing, incorrect, or the key has been revoked.
402 Payment Required	Insufficient Credits	Your account does not have enough credits to generate the requested number of images.
500 Internal Server Error	Server Error	An error occurred in our system or the third-party AI provider.