Assets API | YouThumbAI Documentation

The Assets API allows you to upload and manage images used across YouThumbAI. Assets are the foundation for face profiles and custom templates.

Asset Types

Type	Description	Stored in DB
`face`	Face reference images for persons	Yes
`template`	Style reference templates	Yes
`bucket`	Temporary file upload (no DB entry)	No

The bucket type uploads files to temporary storage without creating a database entry. Useful for transient images needed during generation workflows.

List Assets

Retrieves assets shared and published in your organization.

GET /api/assets

Query Parameters

Parameter	Type	Required	Default	Description
`type`	string	No	-	Filter by type: `face`, `template`, `bucket`
`page`	number	No	1	Page number
`limit`	number	No	20	Items per page (max 100)

# List all assets
curl https://youthumb.ai/api/assets \
  -H "x-api-key: your_api_key"

# List only face assets
curl "https://youthumb.ai/api/assets?type=face" \
  -H "x-api-key: your_api_key"

# Paginated
curl "https://youthumb.ai/api/assets?page=2&limit=10" \
  -H "x-api-key: your_api_key"

List Response

{
  "success": true,
  "data": {
    "assets": [
      {
        "id": "asset-uuid",
        "type": "face",
        "url": "https://...",
        "name": "photo.jpg",
        "description": "Front face photo",
        "mimeType": "image/jpeg",
        "size": 245000,
        "width": 1920,
        "height": 1080,
        "createdAt": "2024-01-15T10:30:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20
    }
  }
}

Upload Asset

Upload an image. Supports two modes: multipart/form-data and JSON (base64).

POST /api/assets

Mode 1: Multipart (FormData)

Field	Type	Required	Description
`file`	File	Yes	Image file (MIME must start with `image/`)
`type`	string	Yes	`face`, `template`, or `bucket`
`description`	string	No	Description

curl -X POST https://youthumb.ai/api/assets \
  -H "x-api-key: your_api_key" \
  -F "file=@face-photo.jpg" \
  -F "type=face" \
  -F "description=Front face photo"

Mode 2: Base64 (JSON)

Field	Type	Required	Default	Description
`base64`	string	Yes	-	Base64-encoded image (with or without `data:` prefix)
`type`	string	Yes	-	`face`, `template`, or `bucket`
`filename`	string	No	auto-generated	Filename
`mimeType`	string	No	`image/jpeg`	`image/jpeg`, `image/png`, `image/webp`, `image/gif`
`description`	string	No	-	Description (max 500 chars)

curl -X POST https://youthumb.ai/api/assets \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "base64": "data:image/jpeg;base64,/9j/4AAQ...",
    "type": "face",
    "filename": "my-face.jpg",
    "mimeType": "image/jpeg",
    "description": "Front face photo"
  }'

Upload Response

{
  "success": true,
  "data": {
    "id": "new-asset-uuid",
    "type": "face",
    "url": "https://...",
    "name": "my-face.jpg",
    "description": "Front face photo",
    "mimeType": "image/jpeg",
    "size": 245000,
    "width": 1920,
    "height": 1080,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

For bucket uploads, the response will have an empty id and null for width/height, since the file is stored temporarily without a database record.

Get Asset

Retrieve a specific asset by ID.

GET /api/assets/{id}

Parameter	Type	Description
`id`	string (UUID)	Asset ID

curl https://youthumb.ai/api/assets/asset-uuid \
  -H "x-api-key: your_api_key"

Get Response

{
  "success": true,
  "data": {
    "id": "asset-uuid",
    "type": "face",
    "url": "https://...",
    "name": "photo.jpg",
    "description": "Front face photo",
    "mimeType": "image/jpeg",
    "size": 245000,
    "width": 1920,
    "height": 1080,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Delete Asset

Delete an asset by ID.

DELETE /api/assets/{id}

Parameter	Type	Description
`id`	string (UUID)	Asset ID

curl -X DELETE https://youthumb.ai/api/assets/asset-uuid \
  -H "x-api-key: your_api_key"

Delete Response

{
  "success": true,
  "data": {
    "message": "Asset deleted"
  }
}

Complete Example: JavaScript

const API = 'https://youthumb.ai/api';
const headers = {
  'x-api-key': process.env.YOUTHUMB_API_KEY,
  'Content-Type': 'application/json',
};

// Upload a face image (base64)
async function uploadFaceImage(base64Data, filename) {
  const response = await fetch(`${API}/assets`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      base64: base64Data,
      type: 'face',
      filename,
      mimeType: 'image/jpeg',
    }),
  });
  return response.json();
}

// List all face assets
async function listFaceAssets() {
  const response = await fetch(`${API}/assets?type=face`, { headers });
  return response.json();
}

// Upload face then create person
async function setupPerson(name, faceImages) {
  // 1. Upload all face images
  const uploadResults = await Promise.all(
    faceImages.map((img) => uploadFaceImage(img.base64, img.filename))
  );

  const imageIds = uploadResults.map((r) => r.data.id);

  // 2. Create person with uploaded images
  const person = await fetch(`${API}/persons`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ name, imageIds }),
  });

  return person.json();
}

Assets are the prerequisite for the Persons API. Upload face images as assets first, then pass their IDs when creating or updating a person.