Persons API | YouThumbAI Documentation

The Persons API allows you to manage face profiles that can be used for AI face swap in thumbnail generation. A "Person" represents a face profile with multiple reference images.

Concept

A Person in YouThumbAI is:

A named profile associated with your organization
Contains one or more face reference images
Used by the AI to generate consistent face swaps
Can be referenced by ID or name when creating thumbnails

For best results, upload 3-5 clear face images from different angles. See the Face Profile Optimization guide for detailed tips.

List Persons

Retrieves all persons in your organization.

GET /api/persons

curl https://youthumb.ai/api/persons \
  -H "x-api-key: your_api_key"

{
  "success": true,
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "John Creator",
      "description": "Main channel host",
      "imageCount": 5,
      "createdAt": "2024-01-10T08:00:00.000Z"
    },
    {
      "id": "987fcdeb-51a2-43e8-b789-426614174111",
      "name": "Guest Sarah",
      "description": "Co-host for tech reviews",
      "imageCount": 3,
      "createdAt": "2024-01-12T14:30:00.000Z"
    }
  ]
}

Create Person

Creates a new person profile.

POST /api/persons

Request Body

Parameter	Type	Required	Description
`name`	string	Yes	Person's name (1-100 chars)
`description`	string	No	Description (max 500 chars)
`imageIds`	array	No	Array of uploaded asset IDs to attach

Basic:

curl -X POST https://youthumb.ai/api/persons \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alex YouTuber",
    "description": "Main channel presenter - tech and gaming content"
  }'

With Images:

curl -X POST https://youthumb.ai/api/persons \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alex YouTuber",
    "description": "Main channel presenter",
    "imageIds": [
      "img-123-uuid",
      "img-456-uuid",
      "img-789-uuid"
    ]
  }'

Create Response

{
  "success": true,
  "data": {
    "id": "new-person-uuid",
    "name": "Alex YouTuber",
    "description": "Main channel presenter - tech and gaming content",
    "imageCount": 0,
    "createdAt": "2024-01-15T10:00:00.000Z"
  }
}

Get Person Details

Retrieves details for a specific person.

GET /api/persons/{id}

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

curl https://youthumb.ai/api/persons/123e4567-e89b-12d3-a456-426614174000 \
  -H "x-api-key: your_api_key"

Person Details Response

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Creator",
    "description": "Main channel host",
    "images": [
      {
        "id": "img-1",
        "url": "https://...",
        "name": "front-face.jpg"
      },
      {
        "id": "img-2",
        "url": "https://...",
        "name": "side-profile.jpg"
      }
    ],
    "createdAt": "2024-01-10T08:00:00.000Z",
    "updatedAt": "2024-01-14T12:00:00.000Z"
  }
}

Error: Person Not Found

{
  "success": false,
  "error": "Person not found"
}

Status Code: 404 Not Found

Add Images to Person

Adds face reference images to an existing person.

POST /api/persons/{id}/images

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

Parameter	Type	Required	Description
`imageIds`	array	Yes	Array of asset IDs to add (1-10 images)

Images must first be uploaded using the Assets API. Pass the resulting asset IDs to this endpoint.

curl -X POST https://youthumb.ai/api/persons/123e4567-e89b-12d3-a456-426614174000/images \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "imageIds": [
      "asset-uuid-1",
      "asset-uuid-2"
    ]
  }'

Add Images Response

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Creator",
    "imageCount": 7,
    "addedImages": 2
  }
}

Using Persons in Thumbnail Generation

When creating a thumbnail, reference a person using either:

By Person ID

{
  "prompt": "Excited reaction to new product",
  "personId": "123e4567-e89b-12d3-a456-426614174000"
}

By Person Name

{
  "prompt": "Excited reaction to new product",
  "personName": "John Creator"
}

You cannot use both personId and personName in the same request. Choose one method.

Complete Example: JavaScript

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

// Create a person
async function createPerson(name, description) {
  const response = await fetch(`${API}/persons`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ name, description }),
  });
  return response.json();
}

// List all persons
async function listPersons() {
  const response = await fetch(`${API}/persons`, { headers });
  return response.json();
}

// Get person details
async function getPerson(personId) {
  const response = await fetch(`${API}/persons/${personId}`, { headers });
  return response.json();
}

// Usage
const newPerson = await createPerson('Channel Host', 'Primary presenter');
console.log('Created person:', newPerson.data.id);

const allPersons = await listPersons();
console.log('All persons:', allPersons.data.length);