Creatify API Docs

Appearance

AI Avatar v1 (Lipsync) ​

Fresh

Purpose ​

Generate a single-scene AI avatar talking head video from text or audio input using the Creatify Lipsync API.

Prerequisites ​

  • Authenticated API access (Authentication SOP)
  • Text script or audio file URL for the avatar to speak
  • Avatar ID (from the avatars list endpoint)
  • Voice ID (from the voices list endpoint)
  • Sufficient credits (5 per 30s of video)

Procedure ​

Step 1: List Available Avatars ​

bash
curl --request GET \
  --url https://api.creatify.ai/api/personas/ \
  --header "X-API-ID: $CREATIFY_API_ID" \
  --header "X-API-KEY: $CREATIFY_API_KEY"

Response (partial):

json
[
  {
    "id": "avatar-uuid-001",
    "name": "Sarah",
    "thumbnail": "https://cdn.creatify.ai/avatars/sarah.jpg",
    "gender": "female"
  },
  {
    "id": "avatar-uuid-002",
    "name": "James",
    "thumbnail": "https://cdn.creatify.ai/avatars/james.jpg",
    "gender": "male"
  }
]

Step 2: List Available Voices ​

bash
curl --request GET \
  --url https://api.creatify.ai/api/voices/ \
  --header "X-API-ID: $CREATIFY_API_ID" \
  --header "X-API-KEY: $CREATIFY_API_KEY"

Response (partial):

json
[
  {
    "id": "voice-uuid-001",
    "name": "Friendly Female",
    "language": "en-US",
    "accent": "American"
  }
]

Step 3: Create a Lipsync Task ​

bash
curl --request POST \
  --url https://api.creatify.ai/api/lipsyncs/ \
  --header "Content-Type: application/json" \
  --header "X-API-ID: $CREATIFY_API_ID" \
  --header "X-API-KEY: $CREATIFY_API_KEY" \
  --data '{
    "text": "Welcome to our product demo. Let me show you the amazing features of our latest release.",
    "creator": "avatar-uuid-001",
    "voice_id": "voice-uuid-001",
    "aspect_ratio": "9:16"
  }'

Key parameters:

ParameterTypeRequiredDescription
textstringYes (or audio_url)The script for the avatar to speak
audio_urlstringYes (or text)URL to an audio file instead of text
creatorstringYesAvatar/persona ID
voice_idstringYes (with text)Voice to use for TTS
aspect_ratiostringNo9:16, 16:9, or 1:1

Response:

json
{
  "id": "lipsync-task-uuid-789",
  "status": "pending",
  "creator": "avatar-uuid-001",
  "voice_id": "voice-uuid-001"
}

Step 4: Poll for Completion ​

bash
curl --request GET \
  --url https://api.creatify.ai/api/lipsyncs/lipsync-task-uuid-789/ \
  --header "X-API-ID: $CREATIFY_API_ID" \
  --header "X-API-KEY: $CREATIFY_API_KEY"

Completed response:

json
{
  "id": "lipsync-task-uuid-789",
  "status": "done",
  "output": "https://cdn.creatify.ai/videos/lipsync-output.mp4",
  "duration": 15
}

Step 5: Download Output ​

Download the video from the output URL when status is done.

Credit Cost ​

OperationCredits
List avatars0
List voices0
Create lipsync task5 per 30s

TIP

For a 15-second video: (15/30) * 5 = 2.5 -- rounded up to 3 credits. For a 60-second video: (60/30) * 5 = 10 credits.

Verification Checklist ​

  • [ ] Selected avatar exists and thumbnail looks correct
  • [ ] Selected voice matches desired language and accent
  • [ ] Task creation returns pending status
  • [ ] Final status is done with valid output URL
  • [ ] Video shows correct avatar with synced lip movements
  • [ ] Audio matches the provided text script

Common Errors ​

ErrorCauseFix
Invalid creatorAvatar ID does not existRe-fetch avatars list and use a valid ID
Invalid voice_idVoice ID does not existRe-fetch voices list and use a valid ID
Text too longExceeds maximum character limitSplit into multiple shorter videos
Audio format unsupportedInvalid audio file formatUse MP3 or WAV format

See Also