Actors

List available actors for video generation.

Base URL

https://api.ugclab.app/api/v1

UGCL 2.0 Actors

Actors for the UGCL 2.0 workflow with high customization capabilities.

List Actors

GET /actors

Query Parameters

Parameter	Type	Default	Description
`gender`	string	-	Filter by gender: `male`, `female`
`age`	string	-	Filter by age group
`isPro`	boolean	-	Filter by pro status
`limit`	number	`50`	Number of items per page (max 100)
`cursor`	string	-	Cursor for pagination

Response

{
  "data": {
    "items": [
      {
        "id": "clactor123...",
        "name": "Sarah",
        "username": "sarah_pro",
        "videoPreviewUrl": "https://...",
        "age": "25-34",
        "color": "#FF5733",
        "gender": "female",
        "tags": ["professional", "friendly"],
        "isPro": true
      }
    ],
    "pagination": {
      "hasMore": true,
      "nextCursor": "clactor456...",
      "limit": 50
    }
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
}

Response Fields

Field	Type	Description
`id`	string	Unique actor ID (use in `actorIds` for UGCL 2.0)
`name`	string	Actor display name
`username`	string	Actor username
`videoPreviewUrl`	string	URL to actor preview video
`age`	string	Age group
`color`	string	Theme color (hex)
`gender`	string	Gender
`tags`	string[]	Actor tags/categories
`isPro`	boolean	Whether this is a pro-tier actor

UGCL 1.0 Actors

Actors for the UGCL 1.0 workflow with extended duration support.

List UGCLab Actors

GET /ugclab-actors

Query Parameters

Parameter	Type	Default	Description
`gender`	string	-	Filter by gender: `male`, `female`
`limit`	number	`50`	Number of items per page (max 100)
`cursor`	string	-	Cursor for pagination

Response

{
  "data": {
    "items": [
      {
        "id": "clugcactor123...",
        "name": "Emma",
        "gender": "female",
        "imageUrl": "https://..."
      }
    ],
    "pagination": {
      "hasMore": false,
      "nextCursor": null,
      "limit": 50
    }
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
}

Response Fields

Field	Type	Description
`id`	string	Unique actor ID (use in `ugclabActorIds` for UGCL 1.0)
`name`	string	Actor display name
`gender`	string	Gender
`imageUrl`	string	Actor reference image URL

Examples

# List UGCL 2.0 Actors
curl -X GET "https://api.ugclab.app/api/v1/actors?gender=female&limit=20" \
  -H "Authorization: Bearer ugc_your_api_key"

# List UGCL 1.0 Actors
curl -X GET "https://api.ugclab.app/api/v1/ugclab-actors?limit=20" \
  -H "Authorization: Bearer ugc_your_api_key"

// Get UGCL 2.0 actors
const actorsResponse = await fetch(
  'https://api.ugclab.app/api/v1/actors?gender=female',
  {
    headers: { 'Authorization': 'Bearer ugc_your_api_key' },
  }
);
const actors = await actorsResponse.json();

// Get UGCL 1.0 actors
const ugclabActorsResponse = await fetch(
  'https://api.ugclab.app/api/v1/ugclab-actors',
  {
    headers: { 'Authorization': 'Bearer ugc_your_api_key' },
  }
);
const ugclabActors = await ugclabActorsResponse.json();

console.log('UGCL 2.0 Actors:', actors.data.items.length);
console.log('UGCL 1.0 Actors:', ugclabActors.data.items.length);

import requests

headers = {'Authorization': 'Bearer ugc_your_api_key'}

# Get UGCL 2.0 actors
actors = requests.get(
    'https://api.ugclab.app/api/v1/actors',
    headers=headers,
    params={'gender': 'female'}
).json()

# Get UGCL 1.0 actors
ugclab_actors = requests.get(
    'https://api.ugclab.app/api/v1/ugclab-actors',
    headers=headers
).json()

print(f"UGCL 2.0 Actors: {len(actors['data']['items'])}")
print(f"UGCL 1.0 Actors: {len(ugclab_actors['data']['items'])}")

Which Actors to Use?

Workflow	Endpoint	Actor ID Field
UGCL 2.0	`GET /actors`	Use `id` in `actorIds`
UGCL 1.0	`GET /ugclab-actors`	Use `id` in `ugclabActorIds`

Error Codes

Code	HTTP Status	Description
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INTERNAL_ERROR`	500	Internal server error

See Authentication for authentication-related errors.

On this page