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

bash

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

json

{
  "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:

bash

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:

bash

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

json

{
  "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

bash

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

Person Details Response

json

{
  "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

json

{
  "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.

bash

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

json

{
  "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

json

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

By Person Name

json

{
  "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

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);

Resources: persons, uploads and catalog

All resource operations use the connected identity. Stored assets must belong to the selected organization and be owned by you or shared with it. Imports stay unpublished and are still discoverable. Unknown or inaccessible IDs return 404; permission refusals return 403; invalid inputs return 400. MCP errors use isError: true. Management operations consume no credits.

REST	MCP	Input / effect
`PATCH /api/persons/:id`	`update_person`	`name?` (1–100), `description?` (max 500); `null` clears description; at least one field
`DELETE /api/persons/:id`	`delete_person`	Deletes profile and photo associations; stored images remain
`DELETE /api/persons/:id/images/:imageId`	`remove_person_image`	Detaches only this existing association, without deleting the asset
`PUT /api/persons/:id/default`	`set_default_person`	Idempotent organization default; existing owner permissions apply
`GET /api/assets/:id`	`get_asset`	Authorized stored asset UUID
`GET /api/templates/:id`	`get_template`	Published catalog template or your own private template

MCP mutations require mcp:assets and active Images and persons access. Reads require mcp:read and active Read access. Tool arguments use personId, imageId, assetId or templateId instead of URL path parameters. Person reads/updates return the profile with images and imageCount; delete returns {"deleted":true}. Existing create/add-photo calls also validate every referenced image before writing.