Images API

REST API endpoints for uploading and generating product images and videos.

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

Kicks off an asynchronous image generation from a text prompt through the AI Gateway. Returns immediately with a generation id and pending status; poll GET /api/v1/images/generations/:id for the result. Metered against the store's credit balance and surfaces in Image Studio. Timeout: 30 seconds to start the generation – the render itself finishes in the background.

Request Body

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",
    "format": "square",
    "model": "quality"
  }' \
  https://your-store.yns.store/api/v1/images/generate

Response

{
  "id": "0191abc0-1234-7def-8000-00000000000b",
  "status": "pending"
}

Errors

Generate Video

POST /api/v1/videos/generate

Kicks off an asynchronous video generation through the same Image Studio pipeline: prompt-to-video by default, or image-to-video when sourceImageUrl is given. Returns immediately with a generation id and pending status; poll GET /api/v1/images/generations/:id for the result – images and videos share the same generations queue. Billed per rendered second against the store's credit balance. Timeout: 30 seconds to start the generation.

Request Body

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "slow orbit around a lavender soap bar",
    "format": "square",
    "duration": 6,
    "model": "balanced"
  }' \
  https://your-store.yns.store/api/v1/videos/generate

Response

{
  "id": "0191abc0-1234-7def-8000-00000000000c",
  "status": "pending"
}

Errors

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 or POST /api/v1/videos/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.