API Documentation

Complete reference for the APIFrame image generation API.

Introduction

The APIFrame API provides programmatic access to AI-powered image generation, description, upscaling, and blending capabilities. All API endpoints are RESTful and return JSON responses.

Base URL: Configured via your environment. The default is http://localhost:4100.

All endpoints under /v1/ require API key authentication via the X-API-Key header.

Authentication

To authenticate, include your API key in the X-API-Key request header. You can obtain an API key by signing up at /signup or from the console dashboard after logging in.

API keys follow the format ak_live_xxxxx. Keep your API key secret and never expose it in client-side code.

# Include in every request
curl -H "X-API-Key: ak_live_xxxxx" \
  https://api.example.com/v1/account

Endpoints

POST`/v1/imagine`

Generate an image from a text prompt. Returns a job object that can be polled for status. Costs 16 credits per request.

Request Body

Parameter	Type	Required	Description
`prompt`	string	Yes	The text prompt to generate an image from.
`aspectRatio`	string	No	Aspect ratio. One of: 1:1, 16:9, 9:16, 4:3, 3:4. Default: 1:1.
`version`	string	No	Model version. One of: 5.2, 6.0, 6.1. Default: 6.1.
`quality`	number	No	Quality level. One of: 0.25, 0.5, 1. Default: 1.
`style`	string	No	Style preset. One of: raw, cute, expressive, scenic.
`chaos`	number	No	Randomness factor, 0-100. Default: 0.
`stylize`	number	No	Stylization strength, 0-1000. Default: 100.
`webhookUrl`	string	No	URL to receive a webhook when the job completes.

Example Request

curl -X POST https://apiframe-api.161.153.32.214.sslip.io/v1/imagine \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "prompt": "a futuristic city at sunset",
    "aspectRatio": "16:9"
  }'

Example Response (202 Accepted)

{
  "success": true,
  "job": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "imagine",
    "status": "pending",
    "prompt": "A serene mountain landscape at sunset, photorealistic",
    "progress": 0,
    "imageUrl": null,
    "imageUrls": null,
    "error": null,
    "createdAt": "2026-05-14T10:30:00.000Z",
    "completedAt": null
  }
}

POST`/v1/describe`

Describe an image from a URL. The API will analyze the image and return text descriptions. Costs 4 credits.

Request Body

Parameter	Type	Required	Description
`imageUrl`	string (url)	Yes	URL of the image to describe.
`webhookUrl`	string (url)	No	URL to receive a webhook when the job completes.

Example Request

curl -X POST https://apiframe-api.161.153.32.214.sslip.io/v1/describe \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "imageUrl": "https://example.com/photo.jpg"
  }'

Example Response (202 Accepted)

{
  "success": true,
  "job": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "type": "describe",
    "status": "pending",
    "prompt": null,
    "progress": 0,
    "imageUrl": null,
    "imageUrls": null,
    "error": null,
    "createdAt": "2026-05-14T10:32:00.000Z",
    "completedAt": null
  }
}

POST`/v1/upscale`

Upscale a specific image from a completed imagine job. The parent job must be in the succeeded state. Costs 4 credits.

Request Body

Parameter	Type	Required	Description
`jobId`	string (uuid)	Yes	The ID of the completed imagine job to upscale from.
`index`	number	Yes	Which image to upscale. One of: 1, 2, 3, 4.
`webhookUrl`	string (url)	No	URL to receive a webhook when the job completes.

Example Request

curl -X POST https://apiframe-api.161.153.32.214.sslip.io/v1/upscale \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "index": 2
  }'

Example Response (202 Accepted)

{
  "success": true,
  "job": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "type": "upscale",
    "status": "pending",
    "prompt": null,
    "progress": 0,
    "imageUrl": null,
    "imageUrls": null,
    "error": null,
    "createdAt": "2026-05-14T10:35:00.000Z",
    "completedAt": null
  }
}

POST`/v1/blend`

Blend 2 to 5 images together into a new image. Costs 16 credits.

Request Body

Parameter	Type	Required	Description
`imageUrls`	string[]	Yes	Array of 2 to 5 image URLs to blend together.
`webhookUrl`	string (url)	No	URL to receive a webhook when the job completes.

Example Request

curl -X POST https://apiframe-api.161.153.32.214.sslip.io/v1/blend \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "imageUrls": [
      "https://example.com/image1.jpg",
      "https://example.com/image2.jpg",
      "https://example.com/image3.jpg"
    ]
  }'

Example Response (202 Accepted)

{
  "success": true,
  "job": {
    "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "type": "blend",
    "status": "pending",
    "prompt": null,
    "progress": 0,
    "imageUrl": null,
    "imageUrls": null,
    "error": null,
    "createdAt": "2026-05-14T10:37:00.000Z",
    "completedAt": null
  }
}

POST`/v1/variation`

Create a variation of a specific image from a completed imagine job. The parent job must be in the succeeded state. Costs 16 credits.

Request Body

Parameter	Type	Required	Description
`jobId`	string (uuid)	Yes	The ID of the completed imagine job to create a variation from.
`index`	number	Yes	Which image to create a variation of. One of: 1, 2, 3, 4.
`webhookUrl`	string (url)	No	URL to receive a webhook when the job completes.

Example Request

curl -X POST https://apiframe-api.161.153.32.214.sslip.io/v1/variation \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "index": 3
  }'

Example Response (202 Accepted)

{
  "success": true,
  "job": {
    "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "type": "variation",
    "status": "pending",
    "prompt": null,
    "progress": 0,
    "imageUrl": null,
    "imageUrls": null,
    "error": null,
    "createdAt": "2026-05-14T10:38:00.000Z",
    "completedAt": null
  }
}

GET`/v1/jobs/:id`

Get the status and result of a specific job. Use this to poll for job completion.

Path Parameters

Parameter	Type	Required	Description
`id`	string (uuid)	Yes	The job ID returned when the job was created.

Example Request

curl https://apiframe-api.161.153.32.214.sslip.io/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: YOUR_API_KEY"

Example Response (200 OK)

{
  "success": true,
  "job": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "imagine",
    "status": "succeeded",
    "prompt": "A serene mountain landscape at sunset, photorealistic",
    "progress": 100,
    "imageUrl": "https://cdn.example.com/images/result.png",
    "imageUrls": [
      "https://cdn.example.com/images/result-1.png",
      "https://cdn.example.com/images/result-2.png",
      "https://cdn.example.com/images/result-3.png",
      "https://cdn.example.com/images/result-4.png"
    ],
    "error": null,
    "createdAt": "2026-05-14T10:30:00.000Z",
    "completedAt": "2026-05-14T10:30:45.000Z"
  }
}

Job Status Values

Status	Description
`pending`	Job has been created and is waiting to be processed.
`queued`	Job is in the processing queue.
`processing`	Job is actively being processed.
`succeeded`	Job completed successfully. Results are available.
`failed`	Job encountered an error. Check the error field.
`timed_out`	Job exceeded the maximum processing time.
`cancelled`	Job was cancelled by the user.

GET`/v1/jobs`

List all jobs for the authenticated user. Results are paginated.

Query Parameters

Parameter	Type	Required	Description
`limit`	number	No	Number of jobs to return. Default: 20, max: 100.
`offset`	number	No	Number of jobs to skip. Default: 0.

Example Request

curl "https://apiframe-api.161.153.32.214.sslip.io/v1/jobs?limit=10&offset=0" \
  -H "X-API-Key: YOUR_API_KEY"

Example Response (200 OK)

{
  "success": true,
  "jobs": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "type": "imagine",
      "status": "succeeded",
      "prompt": "A serene mountain landscape at sunset",
      "progress": 100,
      "imageUrl": "https://cdn.example.com/images/result.png",
      "imageUrls": [...],
      "error": null,
      "createdAt": "2026-05-14T10:30:00.000Z",
      "completedAt": "2026-05-14T10:30:45.000Z"
    }
  ]
}

POST`/v1/jobs/:id/cancel`

Cancel a job that is currently in progress. Returns 400 if the job is already in a terminal state (succeeded, failed, timed_out, or cancelled).

Path Parameters

Parameter	Type	Required	Description
`id`	string (uuid)	Yes	The job ID to cancel.

Example Request

curl -X POST https://apiframe-api.161.153.32.214.sslip.io/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/cancel \
  -H "X-API-Key: YOUR_API_KEY"

Example Response (200 OK)

{
  "success": true,
  "job": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "imagine",
    "status": "cancelled",
    "prompt": "A serene mountain landscape at sunset",
    "progress": 30,
    "imageUrl": null,
    "imageUrls": null,
    "error": null,
    "createdAt": "2026-05-14T10:30:00.000Z",
    "completedAt": "2026-05-14T10:31:10.000Z"
  }
}

GET`/v1/account`

Get account information including name, email, current plan, and credit balance.

Example Request

curl https://apiframe-api.161.153.32.214.sslip.io/v1/account \
  -H "X-API-Key: YOUR_API_KEY"

Example Response (200 OK)

{
  "success": true,
  "account": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "plan": "standard",
    "credits": {
      "remaining": 450,
      "total": 500
    }
  }
}

Error Handling

All errors follow a standard format. The response will include a success: false flag and an error object with a machine-readable code and a human-readable message.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'prompt' field is required."
  }
}

Error Codes

HTTP Status	Code	Description
`400`	`VALIDATION_ERROR`	The request body is invalid or missing required fields.
`401`	`UNAUTHORIZED`	Missing or invalid API key.
`402`	`INSUFFICIENT_CREDITS`	Not enough credits to perform this operation.
`404`	`NOT_FOUND`	The requested resource was not found.
`429`	`RATE_LIMITED`	Too many requests. Slow down and retry after the indicated time.
`500`	`PROVIDER_ERROR`	An internal error occurred with the image generation provider.

Rate Limiting

Rate limits are applied per API key, per minute. The limits vary by plan.

Plan	Requests / Minute
Free	`10`
Hobby	`30`
Standard	`60`
Growth	`120`
Scale	`300`

Rate limit information is included in the response headers of every API call:

Header	Description
`X-RateLimit-Limit`	The maximum number of requests allowed per minute.
`X-RateLimit-Remaining`	The number of requests remaining in the current window.
`X-RateLimit-Reset`	Unix timestamp (seconds) when the rate limit window resets.

When rate limited, you will receive a 429 status code with a Retry-After header indicating how many seconds to wait before retrying.

Credits

Different operations consume different amounts of credits. The Free plan includes 50 credits to get you started (enough for 3 Midjourney generations).

Operation	Credits	USD equivalent
`Imagine`	16	$0.16
`Blend`	16	$0.16
`Variation`	16	$0.16
`Describe`	4	$0.04
`Upscale`	4	$0.04

You can check your remaining credits at any time using the GET /v1/account endpoint. If you run out of credits, requests will return a 402 INSUFFICIENT_CREDITS error.

Upgrade your plan from the console dashboard to get more credits and higher rate limits.

Compatibility Aliases

For compatibility with the original apiframe.ai API, the following path aliases are supported. They behave identically to their /v1/ counterparts and require the same authentication.

Alias	Equivalent
`POST /imagine`	`POST /v1/imagine`
`POST /describe`	`POST /v1/describe`
`POST /upscale`	`POST /v1/upscale`
`POST /blend`	`POST /v1/blend`
`POST /variation`	`POST /v1/variation`
`GET /fetch/:id`	`GET /v1/jobs/:id`
`POST /api/v1/imagine`	`POST /v1/imagine`
`POST /api/v1/describe`	`POST /v1/describe`
`POST /api/v1/upscale`	`POST /v1/upscale`
`POST /api/v1/blend`	`POST /v1/blend`
`POST /api/v1/variation`	`POST /v1/variation`
`GET /api/v1/fetch/:id`	`GET /v1/jobs/:id`

Note: The /fetch/:id alias returns the same data as GET /v1/jobs/:id but uses the data key instead of job in the response object.

Back to Home

API Documentation

Introduction

Authentication

Endpoints

POST/v1/imagine

Request Body

Example Request

Example Response (202 Accepted)

POST/v1/describe

Request Body

Example Request

Example Response (202 Accepted)

POST/v1/upscale

Request Body

Example Request

Example Response (202 Accepted)

POST/v1/blend

Request Body

Example Request

Example Response (202 Accepted)

POST/v1/variation

Request Body

Example Request

Example Response (202 Accepted)

GET/v1/jobs/:id

Path Parameters

Example Request

Example Response (200 OK)

Job Status Values

GET/v1/jobs

Query Parameters

Example Request

Example Response (200 OK)

POST/v1/jobs/:id/cancel

Path Parameters

Example Request

Example Response (200 OK)

GET/v1/account

Example Request

Example Response (200 OK)

Error Handling

Error Codes

Rate Limiting

Credits

Compatibility Aliases

POST`/v1/imagine`

POST`/v1/describe`

POST`/v1/upscale`

POST`/v1/blend`

POST`/v1/variation`

GET`/v1/jobs/:id`

GET`/v1/jobs`

POST`/v1/jobs/:id/cancel`

GET`/v1/account`