Image Upload API

This is an optional upload service provided by Social Print Studio to make integration easier. It gives you a simple way to upload images and receive publicly accessible URLs — which is exactly what the Order Handoff API requires when submitting orders.

The returned publicUrl can be passed directly into the projectData.photos array when calling the Order Handoff API.

When to use this:

If your application doesn’t have its own backend or image hosting, or if you’d rather not manage file storage yourself, use this endpoint to upload customer photos directly to our S3 bucket.

When to skip this:

If your app already hosts images at publicly accessible URLs (e.g. via your own S3 bucket, Cloudinary, Firebase Storage, etc.), just pass those URLs directly to the Order Handoff API. You don’t need this service.

Endpoint

text

POST https://printkit.dev/api/upload
Authorization: Bearer <your-api-key>  (optional)

Upload files to S3 via presigned URLs. Supports images and other file types (PDFs, documents, etc.). Max file size is 50 MB per file. Optionally include an API key for attribution. If an invalid key is provided, the API returns 401.

Usage

The upload process is two steps: get a presigned upload URL, then send the file directly to S3 using that URL.

Step 1: Get Upload URL

curl -X POST https://printkit.dev/api/upload \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "filename": "photo.jpg",
    "source": "my-app-name",
    "email": "[email protected]",
    "fileSize": 1234567,
    "contentType": "image/jpeg",
    "folder": "my-app-name"
  }'

# Response:
# { "uploadUrl": "https://s3.amazonaws.com/...", "publicUrl": "https://..." }

const response = await fetch(
  'https://printkit.dev/api/upload',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`,  // optional — enables attribution
    },
    body: JSON.stringify({
      filename: 'photo.jpg',        // required
      source: 'my-app-name',        // required
      email: '[email protected]',     // your email, highly recommended
      fileSize: 1234567,            // optional - enables 50MB validation
      contentType: 'image/jpeg',    // optional - auto-detected from filename
      folder: 'my-app-name'         // optional
    })
  }
);

const { uploadUrl, publicUrl } = await response.json();

import httpx

response = httpx.post(
    "https://printkit.dev/api/upload",
    headers={
        "Authorization": f"Bearer {API_KEY}",  # optional — enables attribution
    },
    json={
        "filename": "photo.jpg",
        "source": "my-app-name",
        "email": "[email protected]",        # your email, highly recommended
        "fileSize": 1234567,                     # optional - enables 50MB validation
        "contentType": "image/jpeg",             # optional - auto-detected from filename
        "folder": "my-app-name",                 # optional - defaults to 'lambda-uploads'
    },
)

data = response.json()
upload_url = data["uploadUrl"]
public_url = data["publicUrl"]

Step 2: Upload File to S3

curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg

# File is now live at the publicUrl from Step 1

await fetch(uploadUrl, {
  method: 'PUT',
  headers: {
    'Content-Type': 'image/jpeg'
  },
  body: file  // raw File object from a file input
});

// File is now live at publicUrl

import httpx

with open("photo.jpg", "rb") as f:
    upload_response = httpx.put(
        upload_url,  # from Step 1
        headers={"Content-Type": "image/jpeg"},
        content=f.read(),
    )

# File is now live at public_url from Step 1

Important

The x-amz-acl parameter is baked into the presigned URL — do not send it as a header, or the request will fail.

Complete Helper Function

A drop-in helper that handles both steps and returns the final public URL:

# Step 1: Get a presigned upload URL
UPLOAD_RESPONSE=$(curl -s -X POST https://printkit.dev/api/upload \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "filename": "photo.jpg",
    "source": "my-app",
    "email": "[email protected]",
    "fileSize": 1234567,
    "contentType": "image/jpeg"
  }')

# Extract URLs from response (requires jq)
UPLOAD_URL=$(echo $UPLOAD_RESPONSE | jq -r '.uploadUrl')
PUBLIC_URL=$(echo $UPLOAD_RESPONSE | jq -r '.publicUrl')

# Step 2: Upload the file directly to S3
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg

# Step 3: Use the public URL in your order submission
curl -X POST https://printkit.dev/api/add-to-cart \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "{
    \"sku\": \"metal-print-4x4\",
    \"source\": \"my-app\",
    \"email\": \"[email protected]\",
    \"projectData\": {
      \"photos\": [\"$PUBLIC_URL\"]
    }
  }"

async function uploadToS3(file, { apiKey, source, email, folder = 'my-app-name' }) {
  const headers = { 'Content-Type': 'application/json' };
  if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`;

  const response = await fetch(
    'https://printkit.dev/api/upload',
    {
      method: 'POST',
      headers,
      body: JSON.stringify({
        filename: file.name,
        source,
        email,
        fileSize: file.size,
        contentType: file.type,
        folder
      })
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Failed to get upload URL');
  }

  const { uploadUrl, publicUrl } = await response.json();

  const uploadResponse = await fetch(uploadUrl, {
    method: 'PUT',
    headers: { 'Content-Type': file.type },
    body: file
  });

  if (!uploadResponse.ok) {
    throw new Error(`S3 upload failed: ${uploadResponse.status}`);
  }

  return publicUrl;
}

// Usage
const publicUrl = await uploadToS3(fileFromInput, {
  apiKey: API_KEY,
  source: 'my-app',
  email: '[email protected]',
});

// Then use it in your order submission:
const orderResponse = await fetch(
  'https://printkit.dev/api/add-to-cart',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`,  // optional — enables attribution
    },
    body: JSON.stringify({
      sku: 'metal-print-4x4',
      source: 'my-app',
      email: '[email protected]',
      projectData: {
        photos: [publicUrl],
      },
    }),
  }
);

const { redirectUrl } = await orderResponse.json();
window.location.href = redirectUrl;

import httpx
from pathlib import Path


def upload_to_s3(
    filepath: str,
    source: str,
    email: str | None = None,
    api_key: str | None = None,
    folder: str = "my-app-name",
) -> str:
    """Upload a file and return its public URL."""
    path = Path(filepath)
    headers = {}
    if api_key:
        headers["Authorization"] = f"Bearer {api_key}"

    payload = {
        "filename": path.name,
        "source": source,
        "fileSize": path.stat().st_size,
        "contentType": "image/jpeg",
        "folder": folder,
    }
    if email:
        payload["email"] = email

    response = httpx.post(
        "https://printkit.dev/api/upload",
        headers=headers,
        json=payload,
    )
    response.raise_for_status()
    data = response.json()

    # Step 2: Upload file to S3
    upload_response = httpx.put(
        data["uploadUrl"],
        headers={"Content-Type": "image/jpeg"},
        content=path.read_bytes(),
    )
    upload_response.raise_for_status()

    return data["publicUrl"]


# Usage
public_url = upload_to_s3("photo.jpg", source="my-app", email="[email protected]", api_key=API_KEY)

# Then use it in your order submission:
order_response = httpx.post(
    "https://printkit.dev/api/add-to-cart",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "sku": "metal-print-4x4",
        "source": "my-app",
        "email": "[email protected]",
        "projectData": {
            "photos": [public_url],
        },
    },
)

redirect_url = order_response.json()["redirectUrl"]

Request Parameters

Required

Parameter	Type	Description
`filename`	string	The original filename. Used for the S3 key and content type detection.
`source`	string	An identifier for your application (e.g. `"my-app"`). Used for tracking and debugging.

Optional

Parameter	Type	Description
`email`	string	A contact email address. Highly recommended — allows us to reach out to you if there are any issues with your uploads.
`fileSize`	number	File size in bytes. Recommended — enables 50 MB validation before upload.
`contentType`	string	MIME type (e.g. `image/jpeg`, `application/pdf`). Auto-detected from filename if not provided.
`folder`	string	S3 subfolder path. Defaults to `lambda-uploads`.

Recommended File Formats

Use JPG or PNG for photos. Some book products accept PDF files — check the specific product’s JSON file in the product catalog to confirm.

Format	Use case
JPG	Photos and images (preferred for most products)
PNG	Images with transparency, graphics, or lossless quality requirements
PDF	Select book and print products — check per-product JSON

Notes

File size limit: 50 MB per file (only enforced if fileSize is provided in the request)
Upload URL expires in 15 minutes — complete the S3 upload promptly after receiving it
Files are stored at: s3://print-kit/lambda-uploads/{folder}/{timestamp}-{random}-{filename}
Public URL format: https://print-kit.s3.us-east-1.amazonaws.com/...
Non-POST requests return 404 (endpoint details are hidden for security)

Next step:

Once you have publicly accessible image URLs from this service (or your own hosting), you’re ready to submit an order. See the Order Handoff API.