## Uploading images

Image upload moved to the [Media API](/docs/api-reference/media). Use `POST /api/v1/media` to upload files (`multipart/form-data`, up to 10 files of 25 MB each under the `file` field) or to ingest remote image URLs as JSON. It returns catalogued media records with CDN URLs you can use anywhere a product, collection, or post expects an image.

---

## Generate Image

```
POST /api/v1/images/generate
```

Generates an image using AI from a text prompt. The image is uploaded to the store's CDN and returns the URL. Timeout: 30 seconds.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `prompt` | `string` | Yes | Text prompt (1-1000 characters) |
| `type` | `string` | No | Image type: `product`, `collection`, or `hero` (default: `product`) |
| `name` | `string` | No | Filename prefix (default: `generated`) |

The `type` parameter affects the generated image's aspect ratio and style:

| Type | Use Case |
|------|----------|
| `product` | Square product photos, clean backgrounds |
| `collection` | Wide banner images for collection headers |
| `hero` | Full-width hero images for landing pages |

```bash
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A minimalist ceramic coffee mug on a marble surface, soft natural lighting",
    "type": "product",
    "name": "coffee-mug"
  }' \
  https://your-store.yns.store/api/v1/images/generate
```

### Response

```json
{
  "url": "https://your-store.blob.vercel-storage.com/images/coffee-mug-abc123.png",
  "pathname": "images/coffee-mug-abc123.png"
}
```

---

## List Generations

```
GET /api/v1/images/generations
```

Lists the store's image and video generations, newest first, across all products.

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | `number` | 40 | Generations per page (1-100) |
| `offset` | `number` | 0 | Generations to skip |
| `source` | `string` | – | Filter by origin: `studio` (the in-app Image Studio) or `api` (this endpoint) |
| `type` | `string` | – | Filter by media type: `image` or `video` |

```bash
curl \
  -H "Authorization: Bearer your_api_key" \
  "https://your-store.yns.store/api/v1/images/generations?source=api&type=image&limit=20"
```

### Response

```json
{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-00000000000b",
      "status": "completed",
      "type": "image",
      "generatedImageUrl": "https://your-store.blob.vercel-storage.com/images/coffee-mug-abc123.png",
      "aspectRatio": "1:1",
      "source": "api",
      "productId": null,
      "createdAt": "2024-05-03T12:00:00.000Z"
    }
  ],
  "meta": {
    "count": 1,
    "limit": 20,
    "offset": 0
  }
}
```

---

## Get Generation

```
GET /api/v1/images/generations/:id
```

Poll the status and result of a generation started with `POST /api/v1/images/generate`. Store-scoped – a store can only read its own generations.

```bash
curl \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/images/generations/0191abc0-1234-7def-8000-00000000000b
```

### Response

```json
{
  "id": "0191abc0-1234-7def-8000-00000000000b",
  "status": "completed",
  "type": "image",
  "url": "https://your-store.blob.vercel-storage.com/images/coffee-mug-abc123.png",
  "error": null,
  "aspectRatio": "1:1",
  "source": "api",
  "productId": null,
  "createdAt": "2024-05-03T12:00:00.000Z"
}
```

### Status Values

| Status | Meaning |
|--------|---------|
| `pending` | Queued, not started yet |
| `processing` | Generation in progress |
| `completed` | Finished – `url` holds the result |
| `failed` | Failed – `error` explains why |

A `404` is returned when no generation with that id belongs to the store.