Images API

REST API endpoints for uploading and generating product images.

Uploading images

Image upload moved to the Media API. 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

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

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

{
  "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

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

Response

{
  "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.

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

Response

{
  "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

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