API Endpoints | Titlize Docs

This document provides a complete reference for all Titlize API endpoints.

Base URL#

All API endpoints are accessed from:

Plain Text

https://api.titlize.com

Generate Image#

Generate a new Open Graph image with text overlay.

Endpoint#

Plain Text

POST /generate

Content Type#

Requests must use multipart/form-data encoding.

Request Parameters#

Parameter	Type	Required	Description
`image`	File	Yes	Background image (JPEG, PNG, WebP). Max 10MB.
`title`	String	Yes	Main title text (1–200 characters)
`subtitle`	String	No	Optional subtitle text (1–200 characters)
`position`	String	No	Text position: `top`, `center`, `bottom` or custom `{"x":N,"y":N}`. Ignored when `template` is set.
`template`	String	No	Layout preset: `bottom-left` (default), `left`, `right`, `split`. Controls text placement, alignment, and gradient direction.
`colorMode`	String	No	Text color mode: `auto` (default), `white`, `black`, `custom`.
`colorHex`	String	No	Hex color (e.g., `#FF5733`). Required when `colorMode` is `custom`.
`gradient`	Boolean	No	Enable gradient overlay (default: `true`). Gradient color adapts to image tones.
`textShadow`	Boolean	No	Enable text shadow (default: `true`). Subtle shadow for readability.
`fontSize`	Number	No	Manual title font size (24–120). Leave unset for automatic sizing (recommended).
`font`	JSON	No	Font selection: `{"system":"inter"}`. See font list below. Default: `arial`.

Fonts:

arial (default), inter, montserrat, playfair-display, oswald, lora, raleway, roboto, source-sans-pro

Templates:

bottom-left — Text left-aligned at bottom, above X's overlay safe zone. Bottom-up gradient.
left — Text on the left 45% of image, vertically centered. Left-to-right gradient. Use when subject is on the right.
right — Text on the right 45%, right-aligned. Right-to-left gradient. Use when subject is on the left.
split — Title on the left 30%, subtitle on the right 30%. Dual-edge gradient. Use when subject is centered.

Precedence: When both template and position are provided, template takes precedence and position is ignored.

Example Request#

Bash

1 curl -X POST https://api.titlize.com/generate \
2   -H "Authorization: Bearer your_api_token" \
3   -F "image=@background.jpg" \
4   -F "title=10 Tips for Better Writing" \
5   -F "subtitle=A comprehensive guide" \
6   -F "template=bottom-left"

Response#

JSON

1 {
2   "success": true,
3   "data": {
4     "id": "gen_abc123def456",
5     "url": "https://storage.titlize.com/images/gen_abc123def456.png",
6     "thumbnailUrl": "https://storage.titlize.com/thumbnails/gen_abc123def456.png",
7     "width": 1200,
8     "height": 630,
9     "createdAt": "2024-01-15T10:30:00Z"
10   }
11 }

Error Responses#

400 Bad Request - Invalid parameters

JSON

1 {
2   "success": false,
3   "error": {
4     "code": "VALIDATION_ERROR",
5     "message": "Title is required",
6     "details": {
7       "field": "title",
8       "constraint": "required"
9     }
10   }
11 }

413 Payload Too Large - Image exceeds size limit

JSON

1 {
2   "success": false,
3   "error": {
4     "code": "FILE_TOO_LARGE",
5     "message": "Image must be less than 10MB"
6   }
7 }

List Images#

Retrieve a list of generated images.

Endpoint#

Plain Text

GET /images

Query Parameters#

Parameter	Type	Default	Description
`limit`	Number	20	Results per page (1-100)
`offset`	Number	0	Number of results to skip
`sort`	String	`createdAt`	Sort field: `createdAt`, `title`
`order`	String	`desc`	Sort order: `asc`, `desc`

Example Request#

Bash

1 curl -X GET "https://api.titlize.com/images?limit=10&offset=0" \
2   -H "Authorization: Bearer your_api_token"

Response#

JSON

1 {
2   "success": true,
3   "data": {
4     "images": [
5       {
6         "id": "gen_abc123def456",
7         "title": "10 Tips for Better Writing",
8         "url": "https://storage.titlize.com/images/gen_abc123def456.png",
9         "thumbnailUrl": "https://storage.titlize.com/thumbnails/gen_abc123def456.png",
10         "createdAt": "2024-01-15T10:30:00Z"
11       }
12     ],
13     "pagination": {
14       "total": 42,
15       "limit": 10,
16       "offset": 0,
17       "hasMore": true
18     }
19   }
20 }

Get Usage#

Retrieve current usage statistics.

Endpoint#

Plain Text

GET /usage

Example Request#

Bash

1 curl -X GET https://api.titlize.com/usage \
2   -H "Authorization: Bearer your_api_token"

Response#

JSON

1 {
2   "success": true,
3   "data": {
4     "period": {
5       "start": "2024-01-01T00:00:00Z",
6       "end": "2024-01-31T23:59:59Z"
7     },
8     "usage": {
9       "generated": 156,
10       "limit": 500,
11       "remaining": 344,
12       "percentUsed": 31.2
13     },
14     "tier": "pro"
15   }
16 }

Create Token#

Create a new API token.

Endpoint#

Plain Text

POST /tokens

Request Body#

JSON

1 {
2   "name": "Production Website"
3 }

Response#

JSON

1 {
2   "success": true,
3   "data": {
4     "id": "tok_xyz789",
5     "name": "Production Website",
6     "token": "it_live_abc123...",
7     "createdAt": "2024-01-15T10:30:00Z"
8   }
9 }

Note: The full token is only returned once at creation time.

List Tokens#

List all API tokens for the authenticated user.

Endpoint#

Plain Text

GET /tokens

Response#

JSON

1 {
2   "success": true,
3   "data": {
4     "tokens": [
5       {
6         "id": "tok_xyz789",
7         "name": "Production Website",
8         "lastUsedAt": "2024-01-15T14:22:00Z",
9         "createdAt": "2024-01-01T10:00:00Z"
10       }
11     ]
12   }
13 }

Delete Token#

Revoke an API token.

Endpoint#

Plain Text

DELETE /tokens/:id

Response#

JSON

1 {
2   "success": true,
3   "message": "Token deleted successfully"
4 }

HTTP Status Codes#

Code	Description
`200`	Success
`201`	Created
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing token
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn't exist
`413`	Payload Too Large - File size exceeded
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Next Steps#

Set up the WordPress Integration
Review Authentication best practices

1	curl -X POST https://api.titlize.com/generate \
2	-H "Authorization: Bearer your_api_token" \
3	-F "image=@background.jpg" \
4	-F "title=10 Tips for Better Writing" \
5	-F "subtitle=A comprehensive guide" \
6	-F "template=bottom-left"

1	{
2	"success": true,
3	"data": {
4	"id": "gen_abc123def456",
5	"url": "https://storage.titlize.com/images/gen_abc123def456.png",
6	"thumbnailUrl": "https://storage.titlize.com/thumbnails/gen_abc123def456.png",
7	"width": 1200,
8	"height": 630,
9	"createdAt": "2024-01-15T10:30:00Z"
10	}
11	}

1	{
2	"success": false,
3	"error": {
4	"code": "VALIDATION_ERROR",
5	"message": "Title is required",
6	"details": {
7	"field": "title",
8	"constraint": "required"
9	}
10	}
11	}

1	{
2	"success": false,
3	"error": {
4	"code": "FILE_TOO_LARGE",
5	"message": "Image must be less than 10MB"
6	}
7	}

1	curl -X GET "https://api.titlize.com/images?limit=10&offset=0" \
2	-H "Authorization: Bearer your_api_token"

1	{
2	"success": true,
3	"data": {
4	"images": [
5	{
6	"id": "gen_abc123def456",
7	"title": "10 Tips for Better Writing",
8	"url": "https://storage.titlize.com/images/gen_abc123def456.png",
9	"thumbnailUrl": "https://storage.titlize.com/thumbnails/gen_abc123def456.png",
10	"createdAt": "2024-01-15T10:30:00Z"
11	}
12	],
13	"pagination": {
14	"total": 42,
15	"limit": 10,
16	"offset": 0,
17	"hasMore": true
18	}
19	}
20	}

1	curl -X GET https://api.titlize.com/usage \
2	-H "Authorization: Bearer your_api_token"

1	{
2	"success": true,
3	"data": {
4	"period": {
5	"start": "2024-01-01T00:00:00Z",
6	"end": "2024-01-31T23:59:59Z"
7	},
8	"usage": {
9	"generated": 156,
10	"limit": 500,
11	"remaining": 344,
12	"percentUsed": 31.2
13	},
14	"tier": "pro"
15	}
16	}

1	{
2	"success": true,
3	"data": {
4	"id": "tok_xyz789",
5	"name": "Production Website",
6	"token": "it_live_abc123...",
7	"createdAt": "2024-01-15T10:30:00Z"
8	}
9	}

1	{
2	"success": true,
3	"data": {
4	"tokens": [
5	{
6	"id": "tok_xyz789",
7	"name": "Production Website",
8	"lastUsedAt": "2024-01-15T14:22:00Z",
9	"createdAt": "2024-01-01T10:00:00Z"
10	}
11	]
12	}
13	}

1	{
2	"success": true,
3	"message": "Token deleted successfully"
4	}