Images

AI image generation

Fetch list of generated images

get

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Query parameters

limitinteger · max: 50Optional

Maximum number of images to return (max 50, default 20)

Responses

200

A list of generated images

application/json

idstringRequired

urlstringRequired

get

/v1/images

HTTPcURLJavaScriptPython

GET /v1/images HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

A list of generated images

[
  {
    "id": "text",
    "url": "text"
  }
]

Create an image

post

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Body

application/json

modelstringRequired

The model to use for image generation. Use the /v1/meta/image_models endpoint to get the full list. OpenAI models use the size setting. Replicate/Google models use the aspect_ratio setting.

Example: gpt-image-1

promptstring · max: 1000Required

The prompt to use for image generation

Responses

200

Successfully generated image

application/json

idstringOptional

urlstringOptional

post

/v1/images

HTTPcURLJavaScriptPython

POST /v1/images HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 111

{
  "model": "gpt-image-1",
  "prompt": "text",
  "settings": {
    "size": "1536x1024",
    "aspect_ratio": "16:9",
    "resolution": "1K"
  }
}

200

Successfully generated image

{
  "id": "text",
  "url": "text"
}

Start bulk image generation

post

Generate featured images for multiple articles at once. Returns a request ID to poll for status. Requires Power plan or higher.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Body

application/json

article_idsstring · uuid[] · min: 1 · max: 50Required

Array of article IDs to generate images for

modelstringOptional

Image generation model to use

Default: gpt-image-1

use_brand_colorsbooleanOptional

Whether to incorporate brand colors into images

Default: false

prompt_templatestringOptional

Optional custom prompt template

Responses

202

Bulk image generation started

application/json

post

/v1/images/bulk

HTTPcURLJavaScriptPython

POST /v1/images/bulk HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 128

{
  "article_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "model": "gpt-image-1",
  "use_brand_colors": false,
  "prompt_template": "text"
}

202

Bulk image generation started

{
  "request_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_articles": 1,
  "status": "queued"
}

Get bulk image generation status

get

Poll for the status of a bulk image generation request.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

requestIdstring · uuidRequired

The bulk request ID

Responses

200

Bulk image status

application/json

request_idstringOptional

statusstring · enumOptionalPossible values:

total_articlesnumberOptional

completed_articlesnumberOptional

failed_articlesnumberOptional

modelstringOptional

get

/v1/images/bulk/{requestId}

HTTPcURLJavaScriptPython

GET /v1/images/bulk/{requestId} HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

Bulk image status

{
  "request_id": "text",
  "status": "waiting",
  "total_articles": 1,
  "completed_articles": 1,
  "failed_articles": 1,
  "model": "text",
  "articles": {
    "ANY_ADDITIONAL_PROPERTY": {
      "status": "text",
      "image_url": "text",
      "error": "text"
    }
  }
}

Cancel bulk image generation

delete

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

requestIdstring · uuidRequired

Responses

200

Cancelled successfully

application/json

successbooleanOptional

delete

/v1/images/bulk/{requestId}

HTTPcURLJavaScriptPython

DELETE /v1/images/bulk/{requestId} HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

Cancelled successfully

{
  "success": true
}