# API reference

> For the complete documentation index, see [llms.txt](https://inkstudioai.com/developers/llms.txt). Every page has a markdown version: add `.md` to its URL.

All endpoints of the Ink Studio AI REST API v1, with request fields and example responses.

## Basics

- Base URL: `https://inkstudioai.com/api/v1`
- Authentication: `Authorization: Bearer isk_...`. See [Authentication](https://inkstudioai.com/developers/authentication.md).
- Format: JSON requests and responses. Dates are ISO 8601 strings.
- Errors: `{ "error": "message", "code": "<code>" }`. See [Errors and limits](https://inkstudioai.com/developers/errors.md).
- CORS: No. The API does not send CORS headers, so a web page cannot call it from the browser. Use the API from a server, the CLI, or the MCP server, and keep the API key out of browser code.
- OpenAPI 3.1 spec: [https://inkstudioai.com/api/v1/openapi.json](https://inkstudioai.com/api/v1/openapi.json)
- OpenAPI 3.0.3 spec for API directories, without device login and checkout: [https://inkstudioai.com/api/v1/openapi.json?profile=directory](https://inkstudioai.com/api/v1/openapi.json?profile=directory)

## Endpoints

| Method | Path | Key | What it does |
| --- | --- | --- | --- |
| POST | `/generations` | Yes | Create a tattoo design. |
| GET | `/styles` | No | List the style ids. |
| GET | `/pricing` | No | List the plans and credit packs. |
| GET | `/me` | Yes | Get the account, plan, credits, and daily API use. |
| GET | `/designs` | Yes | List the saved designs of the account. |
| GET | `/gallery` | No | Search the public gallery. |
| POST | `/checkout` | Yes | Get a Stripe checkout link. |
| POST | `/auth/device` | No | Start a device login. |
| POST | `/auth/token` | No | Get the API key of an approved device login. |

## POST /generations

Creates a design from a prompt. See [Generate tattoo designs](https://inkstudioai.com/developers/generations.md) for the fields, the response, access rules, and streaming.

## GET /styles

```json
{ "styles": [{ "id": "fine-line", "label": "Fine line", "colorOptional": true }] }
```

`colorOptional: false` means the style is black ink only and `color` is ignored. Style ids: `minimal`, `fine-line`, `realism`, `surreal`, `text`, `neo-traditional`, `black-and-gray`, `watercolor`, `traditional`, `geometric`, `tribal`, `japanese`, `3d`.

## GET /pricing

```json
{
  "currency": "usd",
  "pricingUrl": "https://inkstudioai.com/pricing",
  "plans": [{ "sku": "7-day-access", "label": "7-Day Access", "durationDays": 7, "premiumCredits": 10, "priceUsd": 12.99 }],
  "creditPacks": [{ "sku": "credits-20", "label": "20 Credits", "credits": 20, "priceUsd": 9.99, "requiresPlan": true }]
}
```

A plan gives unlimited text-to-tattoo designs (up to 50 a day with the API) and premium credits for the image tools on the website. Credit packs add premium credits and need an active plan. Current catalog:

| Plan sku | Name | Access | Included | Price |
| --- | --- | --- | --- | --- |
| `7-day-access` | 7-Day Access | 7 days | 10 premium credits | $12.99 |
| `14-day-access` | 14-Day Access | 14 days | 20 premium credits | $16.99 |
| `30-day-access` | 30-Day Access | 30 days | 30 premium credits | $23.99 |

| Credit pack sku | Credits | Price |
| --- | --- | --- |
| `credits-20` | 20 premium credits | $9.99 |
| `credits-50` | 50 premium credits | $19.99 |
| `credits-120` | 120 premium credits | $39.99 |

## GET /me

```json
{
  "email": "ana@example.com",
  "name": "Ana",
  "plan": { "active": true, "expiresOn": "2026-11-01T10:00:00.000Z" },
  "freeGenerations": 0,
  "premiumCredits": { "plan": 8, "purchased": 20, "total": 28 },
  "designsGenerated": 14,
  "generation": { "canGenerate": true, "tier": "paid", "dailyLimit": 50, "usedToday": 3 },
  "links": { "account": "https://inkstudioai.com/account", "pricing": "https://inkstudioai.com/pricing" }
}
```

`generation.tier` is `"paid"`, `"free"`, or `null`. With `null`, the next generation answers `402`. `plan.expiresOn` is `null` without an active plan.

## GET /designs

Query: `page` (from 1) and `limit` (1 to 50, default 20). Returns the saved designs of the account, newest first.

```json
{
  "designs": [{ "id": "...", "imageUrl": "...", "prompt": "...", "style": "fine-line", "color": false, "createdAt": "..." }],
  "page": 1,
  "limit": 20,
  "total": 14,
  "hasMore": false
}
```

## GET /gallery

Query: `q` (search words, up to 200 characters), `page`, and `limit` (1 to 50, default 12). Without `q`, the newest designs come first.

```json
{
  "designs": [{ "id": "...", "imageUrl": "...", "prompt": "...", "style": "japanese", "url": "https://inkstudioai.com/tattoos/..." }],
  "page": 1,
  "limit": 12,
  "total": 120,
  "hasMore": true
}
```

## POST /checkout

Body: `{ "sku": "7-day-access", "couponCode": "OPTIONAL" }`. Use a plan or credit pack sku from `GET /pricing`.

Response `200`: `{ "url": "https://checkout.stripe.com/..." }`. Open the URL in a browser to pay. The purchase goes to the account of the key. An unknown sku answers `400` with `code: "validation"`. A credit pack without an active plan answers `403` with `code: "plan_required"`.

## POST /auth/device and POST /auth/token

The device login for command line tools. See [Authentication](https://inkstudioai.com/developers/authentication.md).