Upload API

The Upload API handles file uploads for product images, documents, and other media. It supports direct uploads and presigned URL workflows for large files.

Upload Structure

{
  "id": "upload_abc123",
  "filename": "product-hero.jpg",
  "mimeType": "image/jpeg",
  "size": 245760,
  "url": "https://cdn.hanzo.ai/uploads/product-hero.jpg",
  "thumbnails": {
    "small": "https://cdn.hanzo.ai/uploads/product-hero_200x200.jpg",
    "medium": "https://cdn.hanzo.ai/uploads/product-hero_600x600.jpg",
    "large": "https://cdn.hanzo.ai/uploads/product-hero_1200x1200.jpg"
  },
  "metadata": {
    "width": 2400,
    "height": 2400,
    "format": "jpeg"
  },
  "createdAt": "2024-01-15T10:00:00Z"
}

Endpoints

List Uploads

GET /upload

Query Parameters:

Parameter	Type	Description
`page`	number	Page number
`display`	number	Items per page
`sort`	string	Sort field
`mimeType`	string	Filter by MIME type prefix (e.g. `image/`)
`since`	string	Uploaded after ISO date

curl "https://api.hanzo.ai/upload?mimeType=image/&display=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "count": 156,
  "models": [
    {
      "id": "upload_abc123",
      "filename": "product-hero.jpg",
      "mimeType": "image/jpeg",
      "size": 245760,
      "url": "https://cdn.hanzo.ai/uploads/product-hero.jpg"
    }
  ]
}

Get Upload

GET /upload/:id

curl https://api.hanzo.ai/upload/upload_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Direct Upload

POST /upload

Upload a file directly using multipart form data:

curl -X POST https://api.hanzo.ai/upload \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "[email protected]" \
  -F "folder=products"

Response: 201 Created

{
  "id": "upload_abc123",
  "filename": "product-hero.jpg",
  "mimeType": "image/jpeg",
  "size": 245760,
  "url": "https://cdn.hanzo.ai/uploads/products/product-hero.jpg",
  "thumbnails": {
    "small": "https://cdn.hanzo.ai/uploads/products/product-hero_200x200.jpg",
    "medium": "https://cdn.hanzo.ai/uploads/products/product-hero_600x600.jpg",
    "large": "https://cdn.hanzo.ai/uploads/products/product-hero_1200x1200.jpg"
  }
}

Presigned URL Upload

For large files, request a presigned URL and upload directly to storage.

Step 1: Request presigned URL

POST /upload/presigned

curl -X POST https://api.hanzo.ai/upload/presigned \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "product-video.mp4",
    "mimeType": "video/mp4",
    "size": 52428800,
    "folder": "videos"
  }'

Response:

{
  "uploadId": "upload_pending_xyz",
  "presignedUrl": "https://storage.hanzo.ai/uploads/videos/product-video.mp4?X-Amz-...",
  "method": "PUT",
  "headers": {
    "Content-Type": "video/mp4"
  },
  "expiresAt": "2024-01-15T11:00:00Z"
}

Step 2: Upload to presigned URL

curl -X PUT "https://storage.hanzo.ai/uploads/videos/product-video.mp4?X-Amz-..." \
  -H "Content-Type: video/mp4" \
  --data-binary @product-video.mp4

Step 3: Confirm upload

POST /upload/presigned/confirm

curl -X POST https://api.hanzo.ai/upload/presigned/confirm \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "uploadId": "upload_pending_xyz"
  }'

Update Upload

PUT /upload/:id

Update metadata or folder assignment:

curl -X PUT https://api.hanzo.ai/upload/upload_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "premium-shirt-hero.jpg",
    "metadata": {
      "alt": "Premium T-Shirt front view"
    }
  }'

Delete Upload

DELETE /upload/:id

curl -X DELETE https://api.hanzo.ai/upload/upload_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response: 204 No Content

Deleting an upload permanently removes the file from storage. Ensure the file is not referenced by any active products before deletion.

Supported File Types

Category	MIME Types	Max Size
Images	`image/jpeg`, `image/png`, `image/webp`, `image/gif`, `image/svg+xml`	10 MB
Videos	`video/mp4`, `video/webm`	500 MB
Documents	`application/pdf`	50 MB
Archives	`application/zip`	100 MB

Image Processing

Uploaded images are automatically processed to generate thumbnails:

Size	Dimensions	Use Case
`small`	200x200	Cart thumbnails
`medium`	600x600	Product cards
`large`	1200x1200	Product detail pages

Original images are preserved at full resolution.

SDK Examples

JavaScript

import { Commerce } from '@hanzo/commerce'

const commerce = new Commerce({ apiKey: 'your_key' })

// Direct upload
const upload = await commerce.uploads.create({
  file: fileBuffer,
  filename: 'product-hero.jpg',
  folder: 'products'
})

// Presigned URL upload
const { presignedUrl, uploadId } = await commerce.uploads.getPresignedUrl({
  filename: 'video.mp4',
  mimeType: 'video/mp4',
  size: 52428800
})

await fetch(presignedUrl, {
  method: 'PUT',
  body: videoFile,
  headers: { 'Content-Type': 'video/mp4' }
})

await commerce.uploads.confirmPresigned(uploadId)

Go

upload, err := client.Uploads.Create(ctx, &sdk.UploadInput{
    File:     fileReader,
    Filename: "product-hero.jpg",
    Folder:   "products",
})

presigned, err := client.Uploads.GetPresignedURL(ctx, &sdk.PresignedInput{
    Filename: "video.mp4",
    MimeType: "video/mp4",
    Size:     52428800,
})

// Upload to presigned URL with standard HTTP client
// then confirm:
err = client.Uploads.ConfirmPresigned(ctx, presigned.UploadID)

On this page