# Unhuman Design

> AI-agent graphic design API. Pay-per-image via Lightning Network (L402). No API keys, no accounts.

## Quick Start

1. POST to /api/generate with your prompt
2. Receive a 402 response containing a Lightning invoice
3. Pay the invoice, then replay the request with the L402 credential
4. Receive your generated image URL

## Authentication: L402 (Lightning HTTP 402)

This API uses the L402 protocol. No API keys or accounts are needed — payment IS authentication.

### Flow

```
POST /api/generate
Content-Type: application/json
{"prompt": "a coffee shop logo, minimalist"}

← 402 Payment Required
{
  "macaroon": "eyJ...",
  "invoice": "lnbc2u1p...",
  "amountSats": 210,
  "expiresAt": 1740350400
}

# Pay the Lightning invoice, receive a preimage

POST /api/generate
Content-Type: application/json
Authorization: L402 <macaroon>:<preimage>
{"prompt": "a coffee shop logo, minimalist"}

← 200 OK
{"data": [{"url": "https://img.recraft.ai/..."}]}
```

## Endpoint

### POST /api/generate

Generate images with a single prompt.

**Price:** $0.042 USD per request (converted to satoshis at invoice time)

#### Request Body (JSON)

| Field    | Type   | Required | Default      | Description                              |
|----------|--------|----------|--------------|------------------------------------------|
| prompt   | string | yes      | —            | Image description (≤1000 bytes)          |
| model    | string | no       | default      | "default" or "max" (higher resolution)   |
| size     | string | no       | 1024x1024    | See allowed sizes per model below        |
| n        | int    | no       | 1            | Number of images (1–6)                   |

#### Models

- **default** — Fast, high-quality image generation. Good for most use cases.
- **max** — Higher resolution output for print-quality or large-format work.

#### Allowed Sizes — default model

| Aspect Ratio | Size        |
|--------------|-------------|
| 1:1          | 1024x1024   |
| 2:1          | 1536x768    |
| 1:2          | 768x1536    |
| 3:2          | 1280x832    |
| 2:3          | 832x1280    |
| 4:3          | 1216x896    |
| 3:4          | 896x1216    |
| 5:4          | 1152x896    |
| 4:5          | 896x1152    |
| 6:10         | 832x1344    |
| 14:10        | 1280x896    |
| 10:14        | 896x1280    |
| 16:9         | 1344x768    |
| 9:16         | 768x1344    |

#### Allowed Sizes — max model

| Aspect Ratio | Size        |
|--------------|-------------|
| 1:1          | 2048x2048   |
| 2:1          | 3072x1536   |
| 1:2          | 1536x3072   |
| 3:2          | 2560x1664   |
| 2:3          | 1664x2560   |
| 4:3          | 2432x1792   |
| 3:4          | 1792x2432   |
| 5:4          | 2304x1792   |
| 4:5          | 1792x2304   |
| 6:10         | 1664x2688   |
| 14:10        | 2560x1792   |
| 10:14        | 1792x2560   |
| 16:9         | 2688x1536   |
| 9:16         | 1536x2688   |

#### Success Response (200)

```json
{
  "data": [
    {"url": "https://img.recraft.ai/..."}
  ]
}
```

#### Error Response (4xx/5xx)

```json
{
  "error": {
    "code": "missing_prompt",
    "message": "A 'prompt' string is required."
  }
}
```

#### Error Codes

| Code              | HTTP | Meaning                              |
|-------------------|------|--------------------------------------|
| invalid_json      | 400  | Body is not valid JSON               |
| missing_prompt    | 400  | prompt field missing or empty        |
| prompt_too_long   | 400  | prompt exceeds 1000 bytes            |
| invalid_model     | 400  | model not "default" or "max"         |
| invalid_size      | 400  | size not valid for the chosen model  |
| invalid_n         | 400  | n not an integer 1–6                 |
| generation_failed | 502  | Upstream generation error            |

## Example: Python Agent

```python
import httpx

api = "https://unhuman.design/api/generate"
body = {"prompt": "neon gradient abstract wallpaper", "size": "1344x768"}

# Step 1: Get invoice
r = httpx.post(api, json=body)
assert r.status_code == 402
invoice_data = r.json()

# Step 2: Pay invoice (your Lightning wallet / LSP)
preimage = your_wallet.pay(invoice_data["invoice"])

# Step 3: Get image
r = httpx.post(
    api,
    json=body,
    headers={"Authorization": f"L402 {invoice_data['macaroon']}:{preimage}"}
)
print(r.json()["data"][0]["url"])
```

### Using the max model

```python
body = {"prompt": "a luxury perfume bottle, studio lighting", "model": "max", "size": "2048x2048"}
```

## Notes

- Image URLs are temporary. Download promptly.
- Invoices expire (see expiresAt timestamp). Generate a new one if expired.
- Each paid credential is single-use.
- The "default" and "max" models share the same aspect ratios but differ in output resolution.