# img.pro

> Image hosting API. Upload or import an image, get a global CDN URL. One request to start, no account required.

## Quick Start

Upload a file:

```bash
curl -X POST https://api.img.pro/v1/upload -F "file=@photo.jpg"
```

Import from a URL:

```bash
curl -X POST https://api.img.pro/v1/import \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/photo.jpg"}'
```

Response:

```json
{
  "id": "abc123",
  "url": "https://img.pro/abc123",
  "src": "https://src.img.pro/t/abc123.jpeg",
  "width": 1920,
  "height": 1080,
  "expires_at": 1706659200,
  "upgrade": {
    "type": "register",
    "url": "https://img.pro/api/quick-start",
    "message": "Get an API key for permanent storage, larger files, and organized uploads",
    "label": "Create API Key"
  }
}
```

- `src` — CDN URL for `<img>` tags and hotlinking
- `url` — viewer page with OG tags for social sharing
- Anonymous uploads expire in 30 days, max 20 MB, rate limited to 20/hour per IP

## Get an API Key (one request)

```bash
curl -X POST https://api.img.pro/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com"}'
```

Response:

```json
{
  "key": "img_live_abc123...",
  "key_id": "key_7x9k2m",
  "status": "active",
  "verified": false,
  "limits": { "uploads": 100, "storage_mb": 5120, "retention_days": 30 },
  "message": "Key active. Check your email to verify and unlock permanent storage."
}
```

Save the key — it's shown once. Use it in requests:

```bash
curl -X POST https://api.img.pro/v1/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@photo.jpg" \
  -F "tags=hero,homepage" \
  -F "namespace=my-project"
```

With a key: uploads are organized by namespace and tags, and tied to your account. Verify your email (one-click link) to unlock permanent storage.

## CDN Transforms

Append `?size=` to resize. Change the extension to convert format. All transforms are cached at the edge.

- `src.img.pro/t/abc123.jpeg?size=s` — 320px (thumbnails)
- `src.img.pro/t/abc123.jpeg?size=m` — 640px (cards, mobile)
- `src.img.pro/t/abc123.jpeg?size=l` — 1080px (full display)
- `src.img.pro/t/abc123.webp?size=m` — WebP format
- `src.img.pro/t/abc123.png` — PNG format, original size

Sizes constrain the short edge, preserving aspect ratio. Never upscales.

## Plans

| Plan | Uploads/mo | Storage | Retention | Price |
|------|-----------|---------|-----------|-------|
| Anonymous | 20/hr per IP | Shared | 30 days | Free |
| Free (verified) | 100/mo | 5 GB | Permanent | Free |
| Pro | 1,000/mo | 50 GB | Permanent | $10/mo |
| Scale | 10,000/mo | 500 GB | Permanent | $49/mo |
| Max | 100,000/mo | 5 TB | Permanent | $299/mo |

## Error Handling

Every error includes an `action` object telling you what to do:

- `action.type: "upgrade"` — quota reached, show `action.url` to user (signed, one-click)
- `action.type: "verify"` — email not verified, show `action.url` to user
- `action.type: "wait"` — rate limited, retry after `action.seconds`

## Full Reference

- Complete API reference: https://img.pro/llms-full.txt
- Interactive docs: https://img.pro/api
- AI agents guide: https://img.pro/api/ai-agents
- OpenAPI spec: https://img.pro/openapi.yaml