Skip to main content

Characters API

The Characters API is the main workspace-facing surface for managing AI personas.

Core endpoints​

  • POST /api/v1/characters
  • GET /api/v1/characters
  • GET /api/v1/characters/{id}
  • PATCH /api/v1/characters/{id}
  • POST /api/v1/characters/{id}/default
  • POST /api/v1/characters/{id}/duplicate

The older /api/v1/influencers aliases still exist, but new integrations should prefer /api/v1/characters.

Create a character​

curl https://api.influgen.ai/api/v1/characters \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mila Hart",
    "niche": "fitness",
    "appearance": {
      "age_range": "25-34",
      "aesthetic": "editorial athleisure"
    },
    "identity": {
      "location": "Los Angeles",
      "occupation": "Pilates coach"
    },
    "personality": {
      "tone": "confident"
    },
    "style": {
      "presets": ["soft-luxe"]
    },
    "reference_images": ["https://cdn.example.com/reference/mila-front.jpg"],
    "settings": {
      "autopilot": false
    },
    "talking_head_enabled": false
  }'

Example response:

{
  "character": {
    "id": "char_01HZX6FQJ5N6E7T2M3A4B5C6D7",
    "name": "Mila Hart",
    "niche": "fitness",
    "reference_images": [
      "https://cdn.example.com/reference/mila-front.jpg"
    ],
    "autopilot": false,
    "face_consistency_tier": "ip_adapter",
    "lora_training_status": "none",
    "content_count": 0,
    "last_post_date": null,
    "follower_count": 0,
    "is_default": false
  }
}

Upload a reference image​

Reference image upload is multipart and accepts any of these form fields:

  • file
  • image
  • reference_image
curl https://api.influgen.ai/api/v1/characters/char_01HZX6FQJ5N6E7T2M3A4B5C6D7/reference-images \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "file=@/path/to/reference.jpg" \
  -F "type=primary"

Uploading a reference image stores the file, creates the reference record, and refreshes the stored face embedding for the character.

LoRA endpoints​

  • GET /api/v1/characters/{id}/lora
  • GET /api/v1/characters/{id}/lora/status
  • POST /api/v1/characters/{id}/lora/images
  • GET /api/v1/characters/{id}/lora/images
  • POST /api/v1/characters/{id}/lora/train
  • DELETE /api/v1/characters/{id}/lora

Key rules:

  • Pro or Agency plan required
  • 10 to 30 training images
  • training steps 1000 to 1500
  • rank 16 to 32
  • default cost 500 credits

Example training request:

curl https://api.influgen.ai/api/v1/characters/char_01HZX6FQJ5N6E7T2M3A4B5C6D7/lora/train \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_model": "fal-ai/flux-lora",
    "training_steps": 1200,
    "lora_rank": 16
  }'

Voice endpoints​

  • GET /api/v1/voices
  • GET /api/v1/characters/{id}/voice
  • GET /api/v1/characters/{id}/voice/settings
  • PUT /api/v1/characters/{id}/voice/settings
  • POST /api/v1/characters/{id}/voice-clone
  • POST /api/v1/characters/{id}/voice/preview
  • POST /api/v1/characters/{id}/voice/generate

Voice clone supports JSON with sample_urls or multipart uploads with sample or samples.

Example JSON clone request:

curl https://api.influgen.ai/api/v1/characters/char_01HZX6FQJ5N6E7T2M3A4B5C6D7/voice-clone \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mila Voice",
    "description": "Warm luxury wellness narrator",
    "sample_urls": [
      "https://cdn.example.com/audio/mila-1.mp3",
      "https://cdn.example.com/audio/mila-2.mp3"
    ],
    "stability": 0.55,
    "similarity_boost": 0.8,
    "style": 0.25,
    "use_speaker_boost": true
  }'

Talking head and motion transfer​

Character-scoped video subresources include:

  • POST /api/v1/characters/{id}/talking-head/preview
  • POST /api/v1/characters/{id}/talking-head/generate
  • GET /api/v1/characters/{id}/talking-head/generations
  • GET /api/v1/talking-head/{generationId}
  • POST /api/v1/characters/{id}/motion-transfer
  • GET /api/v1/characters/{id}/motion-transfer/{jobId}
  • GET /api/v1/characters/{id}/motion-transfers

Those routes are documented in more detail under Content API.