API Reference

Persons API

Persons represent characters that can appear in your videos. Each person has a photo used for face-locking in AI generation, and can optionally have a cloned voice.

The Person Object

json

{
  "id": 1,
  "name": "Alex Chen",
  "description": "Tech startup founder",
  "photo_url": "https://storage.twin.actor/persons/1/photo.jpg",
  "photo_base64": null,
  "has_voice": true,
  "voice_provider": "elevenlabs",
  "voice_id": "voice_abc123",
  "company_id": null,
  "user_id": 42,
  "created_at": "2024-03-20T10:00:00Z",
  "updated_at": "2024-03-20T10:00:00Z"
}

Attributes

Name	Type	Description
`id`	`integer`	Unique identifier
`name`	`string`	Display name
`description`	`string`	Optional description or bio
`photo_url`	`string`	URL to the person's photo
`photo_base64`	`string`	Base64 photo (only on create/update)
`has_voice`	`boolean`	Whether a voice clone exists
`voice_provider`	`string`	Voice provider (elevenlabs, hume, chatterbox)
`voice_id`	`string`	Provider's voice ID
`company_id`	`integer`	Associated company (optional)
`user_id`	`integer`	Owner user ID
`created_at`	`datetime`	Creation timestamp
`updated_at`	`datetime`	Last update timestamp

List Persons

GET/persons

List all persons belonging to the authenticated user

Query Parameters

Name	Type	Description
`has_voice`	`boolean`	Filter by voice availability
`company_id`	`integer`	Filter by company

bash

curl https://api.twin.actor/api/v1/persons \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

json

[
  {
    "id": 1,
    "name": "Alex Chen",
    "description": "Tech startup founder",
    "photo_url": "https://storage.twin.actor/persons/1/photo.jpg",
    "has_voice": true,
    "voice_provider": "elevenlabs",
    "created_at": "2024-03-20T10:00:00Z"
  },
  {
    "id": 2,
    "name": "Sarah Johnson",
    "description": "Marketing director",
    "photo_url": "https://storage.twin.actor/persons/2/photo.jpg",
    "has_voice": false,
    "voice_provider": null,
    "created_at": "2024-03-19T15:30:00Z"
  }
]

200List of persons

401Unauthorized

Create Person

POST/persons

Create a new person with a photo

Request Body

Name	Type	Description
`name`required	`string`	Person's name
`description`	`string`	Bio or description
`photo_base64`required	`string`	Photo as base64 data URL
`company_id`	`integer`	Associate with a company

Photo Requirements

Clear, front-facing photo works best
Supported formats: JPEG, PNG, WebP
Recommended size: 512x512 to 1024x1024
Maximum file size: 10MB

bash

curl -X POST https://api.twin.actor/api/v1/persons \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alex Chen",
    "description": "Tech startup founder specializing in AI",
    "photo_base64": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }'

Response:

json

{
  "id": 3,
  "name": "Alex Chen",
  "description": "Tech startup founder specializing in AI",
  "photo_url": "https://storage.twin.actor/persons/3/photo.jpg",
  "has_voice": false,
  "voice_provider": null,
  "voice_id": null,
  "company_id": null,
  "user_id": 42,
  "created_at": "2024-03-20T10:00:00Z",
  "updated_at": "2024-03-20T10:00:00Z"
}

201Person created

400Invalid photo format

401Unauthorized

422Validation error

Get Person

GET/persons/{id}

Get a specific person by ID

bash

curl https://api.twin.actor/api/v1/persons/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

200Person object

404Person not found

Update Person

PUT/persons/{id}

Update a person's details

Request Body

Name	Type	Description
`name`	`string`	Updated name
`description`	`string`	Updated description
`photo_base64`	`string`	New photo

bash

curl -X PUT https://api.twin.actor/api/v1/persons/1 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alex Chen Jr.",
    "description": "Updated bio with new role"
  }'

200Updated person object

404Person not found

Delete Person

DELETE/persons/{id}

Delete a person and associated voice clones

Deleting a person will also delete any associated voice clones. This action cannot be undone. Projects that used this person will retain their generated content but cannot be regenerated.

bash

curl -X DELETE https://api.twin.actor/api/v1/persons/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

204Successfully deleted

404Person not found

Demo Person

Each user account comes with a demo person (Elon Musk with Tesla company) pre-seeded for testing. You can use this immediately without creating your own person.

The demo person is read-only and cannot be deleted. For production use, create your own persons with your own photos.