# Photo to Listing — Full API Documentation

> Upload product photos, get optimized marketplace listings instantly via AI.

Photo to Listing is an AI-powered service that analyzes product photos and generates ready-to-publish listings for 12+ online marketplaces. The REST API enables AI agents and LLMs to programmatically upload photos and receive structured listing data.

Base URL: `https://phototolisting.com`

---

## Authentication

All API requests require an API key passed via the `X-API-Key` header.

### Getting an API Key

1. Create an account at https://phototolisting.com
2. Go to https://phototolisting.com/account/api-keys
3. Click "Create new key" and give it a name
4. Copy the key immediately — it is shown only once

Keys use the `ptl_` prefix (e.g., `ptl_a1b2c3d4...`). You can have up to 10 active keys per account.

### Using the Key

```
X-API-Key: ptl_your_key_here
```

---

## Endpoints

### POST /api/v1/listings

Generate marketplace listings from product photos.

**Headers:**
```
X-API-Key: ptl_your_key_here
Content-Type: application/json
```

**Request Body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `photos` | `string[]` | Yes | Base64-encoded images (1–4 photos) |
| `platforms` | `string[]` | Yes | Target marketplace IDs (see list below) |
| `language` | `string` | No | `"fr"` (default) or `"en"` |
| `tone` | `string` | No | `"casual"`, `"professional"`, or `"friendly"` (default) |
| `quality` | `string` | No | `"standard"` (default) or `"high"` |
| `attributes` | `object` | No | Pre-fill known attributes: `brand`, `size`, `condition`, `color`, `material` |

**Example Request:**
```bash
curl -X POST https://phototolisting.com/api/v1/listings \
  -H "X-API-Key: ptl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "photos": ["data:image/jpeg;base64,/9j/4AAQ..."],
    "platforms": ["leboncoin", "vinted"],
    "language": "fr",
    "tone": "friendly"
  }'
```

**Example Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "listings": [
      {
        "platform": "leboncoin",
        "title": "Veste en cuir noir - Taille M",
        "description": "Superbe veste en cuir véritable...",
        "price": 45,
        "category": "Vêtements",
        "condition": "Bon état"
      },
      {
        "platform": "vinted",
        "title": "Veste cuir noir M",
        "description": "Veste en cuir véritable, taille M...",
        "price": 45,
        "category": "Vestes",
        "condition": "Bon état"
      }
    ],
    "attributes": {
      "name": "Veste en cuir noir",
      "brand": "Unknown",
      "size": "M",
      "condition": "good",
      "color": "Noir",
      "material": "Cuir"
    },
    "suggestedPrice": 45,
    "priceRationale": "Based on market analysis of similar leather jackets..."
  },
  "usage": {
    "freeUsed": 1,
    "freeLimit": 3,
    "creditsRemaining": 0,
    "isSubscribed": false,
    "canGenerate": true,
    "nextResetDate": "2026-03-01T00:00:00.000Z"
  }
}
```

### GET /api/v1/usage

Check your current quota and plan information.

**Headers:**
```
X-API-Key: ptl_your_key_here
```

**Example Request:**
```bash
curl https://phototolisting.com/api/v1/usage \
  -H "X-API-Key: ptl_your_key_here"
```

**Example Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "freeUsed": 2,
    "freeLimit": 3,
    "creditsRemaining": 0,
    "isSubscribed": false,
    "planType": "free",
    "canGenerate": true,
    "nextResetDate": "2026-03-01T00:00:00.000Z"
  }
}
```

---

## Supported Platforms

| ID | Marketplace | Country |
|----|------------|---------|
| `leboncoin` | Leboncoin | France |
| `vinted` | Vinted | Europe |
| `marketplace` | Facebook Marketplace | Global |
| `ebay` | eBay | Global |
| `etsy` | Etsy | Global |
| `vestiaire` | Vestiaire Collective | Europe |
| `selency` | Selency | France |
| `poshmark` | Poshmark | US |
| `mercari` | Mercari | US/Japan |
| `depop` | Depop | UK/US |
| `craigslist` | Craigslist | US |
| `offerup` | OfferUp | US |

---

## Rate Limits

| Plan | Limit |
|------|-------|
| Free | 10 requests/minute |
| Pro (subscribed) | 60 requests/minute |

Rate limit headers are included in every response:
- `X-RateLimit-Limit`: Maximum requests per window
- `X-RateLimit-Remaining`: Requests remaining in current window

When rate limited, a `429 Too Many Requests` response is returned with a `Retry-After` header.

---

## Quota System

Each API call to `POST /api/v1/listings` consumes 1 generation credit. The same quota is shared between the web UI and API.

| Plan | Generations |
|------|------------|
| Free | 3 per month (resets monthly) |
| Pro Monthly | Unlimited |
| Pro Annual | Unlimited |
| Credit Pack | 20 one-time generations |

When quota is exhausted, `POST /api/v1/listings` returns `402 Payment Required`.

---

## Error Codes

| Code | Meaning | Example |
|------|---------|---------|
| `400` | Bad Request | Missing photos, invalid platform ID, too many photos (max 4) |
| `401` | Unauthorized | Missing, invalid, or revoked API key |
| `402` | Payment Required | Quota exhausted — upgrade plan or buy credits |
| `429` | Too Many Requests | Rate limit exceeded — check `Retry-After` header |
| `500` | Server Error | AI generation failed — retry |

**Error Response Format:**
```json
{
  "statusCode": 400,
  "message": "Missing or invalid \"photos\" field. Must be a non-empty array of base64-encoded images."
}
```

---

## Optional Parameters

### `attributes` object

Pre-fill known product attributes to improve listing quality:

```json
{
  "attributes": {
    "brand": "Nike",
    "size": "42",
    "condition": "good",
    "color": "Black",
    "material": "Leather"
  }
}
```

### `tone` values

- `"casual"` — Relaxed, conversational tone
- `"professional"` — Formal, detailed descriptions
- `"friendly"` — Warm, approachable (default)

### `quality` values

- `"standard"` — Fast generation (default)
- `"high"` — More detailed analysis, better descriptions

### `language` values

- `"fr"` — French (default)
- `"en"` — English

---

## Quick Start

```bash
# 1. Check your quota
curl https://phototolisting.com/api/v1/usage \
  -H "X-API-Key: ptl_your_key_here"

# 2. Generate listings from a photo
curl -X POST https://phototolisting.com/api/v1/listings \
  -H "X-API-Key: ptl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "photos": ["data:image/jpeg;base64,/9j/4AAQ..."],
    "platforms": ["leboncoin", "vinted", "ebay"],
    "language": "fr",
    "tone": "friendly"
  }'
```

---

## Links

- Website: https://phototolisting.com
- Pricing: https://phototolisting.com/pricing
- API Key Management: https://phototolisting.com/account/api-keys
- OpenAPI Spec: https://phototolisting.com/.well-known/openapi.json
- Developer Page: https://phototolisting.com/developers