Live Portrait Serverless API
Live Portrait animates static images using a reference driving video through implicit key point based framework, bringing a portrait to life with realistic expressions and movements. It identifies key points on the face (think eyes, nose, mouth) and manipulates them to create expressions and movements.
POST /v2/live-portrait · submit + poll 1# pip install "segmind>=1.1.0"
2# export SEGMIND_API_KEY="YOUR_API_KEY"
3from segmind import SegmindClient, InferenceFailed, InferenceTimeout
4
5# Async (v2) — recommended for long-running / video models.
6# run() blocks up to 600s; submit_async + job.wait(timeout=...) sets a longer
7# deadline and keeps the request_id so you can re-poll later.
8client = SegmindClient() # reads SEGMIND_API_KEY
9payload = {
10 "face_image": "https://segmind-sd-models.s3.amazonaws.com/display_images/liveportrait-input.jpg",
11 "driving_video": "https://segmind-sd-models.s3.amazonaws.com/display_images/liveportrait-video.mp4",
12 "live_portrait_dsize": 512,
13 "live_portrait_scale": 2.3,
14 "video_frame_load_cap": 128,
15 "live_portrait_lip_zero": True,
16 "live_portrait_relative": True,
17 "live_portrait_vx_ratio": 0,
18 "live_portrait_vy_ratio": -0.12,
19 "live_portrait_stitching": True,
20 "video_select_every_n_frames": 1,
21 "live_portrait_eye_retargeting": False,
22 "live_portrait_lip_retargeting": False,
23 "live_portrait_lip_retargeting_multiplier": 1,
24 "live_portrait_eyes_retargeting_multiplier": 1,
25}
26job = client.submit_async("live-portrait", **payload)
27print(job.request_id) # available immediately
28try:
29 result = job.wait(timeout=900, interval=2.0)
30 print(result["status"]) # COMPLETED
31 print(result.get("output")) # model output (e.g. video URL)
32except InferenceTimeout as e:
33 print("still running:", e.request_id) # re-poll later with this id
34except InferenceFailed as e:
35 print("failed:", e.detail)
36
37# Fast models (<=600s) can use the one-liner instead:
38# result = segmind.run("live-portrait", **payload) 1# pip install "segmind>=1.1.0"
2# export SEGMIND_API_KEY="YOUR_API_KEY"
3from segmind import SegmindClient, InferenceFailed, InferenceTimeout
4
5# Async (v2) — recommended for long-running / video models.
6# run() blocks up to 600s; submit_async + job.wait(timeout=...) sets a longer
7# deadline and keeps the request_id so you can re-poll later.
8client = SegmindClient() # reads SEGMIND_API_KEY
9payload = {
10 "face_image": "https://segmind-sd-models.s3.amazonaws.com/display_images/liveportrait-input.jpg",
11 "driving_video": "https://segmind-sd-models.s3.amazonaws.com/display_images/liveportrait-video.mp4",
12 "live_portrait_dsize": 512,
13 "live_portrait_scale": 2.3,
14 "video_frame_load_cap": 128,
15 "live_portrait_lip_zero": True,
16 "live_portrait_relative": True,
17 "live_portrait_vx_ratio": 0,
18 "live_portrait_vy_ratio": -0.12,
19 "live_portrait_stitching": True,
20 "video_select_every_n_frames": 1,
21 "live_portrait_eye_retargeting": False,
22 "live_portrait_lip_retargeting": False,
23 "live_portrait_lip_retargeting_multiplier": 1,
24 "live_portrait_eyes_retargeting_multiplier": 1,
25}
26job = client.submit_async("live-portrait", **payload)
27print(job.request_id) # available immediately
28try:
29 result = job.wait(timeout=900, interval=2.0)
30 print(result["status"]) # COMPLETED
31 print(result.get("output")) # model output (e.g. video URL)
32except InferenceTimeout as e:
33 print("still running:", e.request_id) # re-poll later with this id
34except InferenceFailed as e:
35 print("failed:", e.detail)
36
37# Fast models (<=600s) can use the one-liner instead:
38# result = segmind.run("live-portrait", **payload)API Endpoint
https://api.segmind.com/v1/live-portraitParameters
driving_videorequiredstring (uri)A video to drive the animation
"https://segmind-sd-models.s3.amazonaws.com/display_images/liveportrait-video.mp4"face_imagerequiredstring (uri)An image with a face
"https://segmind-sd-models.s3.amazonaws.com/display_images/liveportrait-input.jpg"live_portrait_dsizeoptionalintegerSize of the output image
512Range: 64 - 2048live_portrait_eye_retargetingoptionalbooleanEnable eye retargeting
falselive_portrait_eyes_retargeting_multiplieroptionalnumberMultiplier for eye retargeting
1Range: 0.01 - 10live_portrait_lip_retargetingoptionalbooleanEnable lip retargeting
falselive_portrait_lip_retargeting_multiplieroptionalnumberMultiplier for lip retargeting
1Range: 0.01 - 10live_portrait_lip_zerooptionalbooleanEnable lip zero
truelive_portrait_relativeoptionalbooleanUse relative positioning
truelive_portrait_scaleoptionalnumberScaling factor for the face
2.3Range: 1 - 4live_portrait_stitchingoptionalbooleanEnable stitching
truelive_portrait_vx_ratiooptionalnumberHorizontal shift ratio
0Range: -1 - 1live_portrait_vy_ratiooptionalnumberVertical shift ratio
-0.12Range: -1 - 1video_frame_load_capoptionalintegerThe maximum number of frames to load from the driving video. Set to 0 to use all frames.
128video_select_every_n_framesoptionalintegerSelect every nth frame from the driving video. Set to 1 to use all frames.
1Response Type
Returns: Video
Asynchronous requests (v2)
Use Async for video, long-running (>~60s), or high-concurrency workloads; Sync is simplest for fast image & LLM calls. Async submits a request and you poll it to completion.
- 1
POST /v2/live-portraitSubmit — returns request_id, status_url, response_url
- 2
GET /v2/requests/{id}/statusPoll — until COMPLETED or FAILED
- 3
GET /v2/requests/{id}Result — final response body
Status states
- A FAILED request is served as HTTP 422 — the body still carries the error detail.
- An unknown or expired request_id returns HTTP 404.
- Results are retained for 1 hour, then expire.
- Content / RAI blocks surface as FAILED, not a separate state.
- Track completion by polling the status endpoint.
Common Error Codes
The API returns standard HTTP status codes. Detailed error messages are provided in the response body.
Bad Request
Invalid parameters or request format
Unauthorized
Missing or invalid API key
Forbidden
Insufficient permissions
Not Found
Model or endpoint not found
Insufficient Credits
Not enough credits to process request
Rate Limited
Too many requests
Server Error
Internal server error
Bad Gateway
Service temporarily unavailable
Timeout
Request timed out