Upload Face Avatar
curl --request POST \
--url https://api.agenthuman.com/v1/avatars/upload-face \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"image_url": "<string>",
"image_base64": "<string>"
}
'import requests
url = "https://api.agenthuman.com/v1/avatars/upload-face"
payload = {
"image_url": "<string>",
"image_base64": "<string>"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({image_url: '<string>', image_base64: '<string>'})
};
fetch('https://api.agenthuman.com/v1/avatars/upload-face', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.agenthuman.com/v1/avatars/upload-face",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'image_url' => '<string>',
'image_base64' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.agenthuman.com/v1/avatars/upload-face"
payload := strings.NewReader("{\n \"image_url\": \"<string>\",\n \"image_base64\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.agenthuman.com/v1/avatars/upload-face")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"image_url\": \"<string>\",\n \"image_base64\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.agenthuman.com/v1/avatars/upload-face")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"image_url\": \"<string>\",\n \"image_base64\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"preview_url": "https://cdn.agenthuman.com/avatars/avat_01KMZHXFPBVCXA5ATK85HCP8G1/preview",
"image_url": "https://cdn.agenthuman.com/avatars/avat_01KMZHXFPBVCXA5ATK85HCP8G1/image",
"avatar_id": "avat_01KMZHXFPBVCXA5ATK85HCP8G1"
}
{
"success": false,
"error": {
"message": "No image provided",
"suggestion": "Supply an image via: file upload (\"file\" field in multipart/form-data), URL (\"image_url\"), or base64 string (\"image_base64\")"
}
}
{
"success": false,
"error": {
"message": "Failed to fetch image from URL (HTTP 403)",
"suggestion": "Check that the URL is publicly accessible"
}
}
{
"success": false,
"error": {
"message": "No face detected in the image",
"suggestion": "Upload a clear portrait photo with one visible face"
}
}
{
"success": false,
"error": {
"message": "Multiple faces detected",
"suggestion": "Upload a photo with only one person"
}
}
{
"success": false,
"error": {
"message": "Unauthorized"
}
}
Avatars
Upload Face Avatar
Upload a portrait photo to create a face-aligned avatar image
POST
/
v1
/
avatars
/
upload-face
Upload Face Avatar
curl --request POST \
--url https://api.agenthuman.com/v1/avatars/upload-face \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"image_url": "<string>",
"image_base64": "<string>"
}
'import requests
url = "https://api.agenthuman.com/v1/avatars/upload-face"
payload = {
"image_url": "<string>",
"image_base64": "<string>"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({image_url: '<string>', image_base64: '<string>'})
};
fetch('https://api.agenthuman.com/v1/avatars/upload-face', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.agenthuman.com/v1/avatars/upload-face",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'image_url' => '<string>',
'image_base64' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.agenthuman.com/v1/avatars/upload-face"
payload := strings.NewReader("{\n \"image_url\": \"<string>\",\n \"image_base64\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.agenthuman.com/v1/avatars/upload-face")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"image_url\": \"<string>\",\n \"image_base64\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.agenthuman.com/v1/avatars/upload-face")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"image_url\": \"<string>\",\n \"image_base64\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"preview_url": "https://cdn.agenthuman.com/avatars/avat_01KMZHXFPBVCXA5ATK85HCP8G1/preview",
"image_url": "https://cdn.agenthuman.com/avatars/avat_01KMZHXFPBVCXA5ATK85HCP8G1/image",
"avatar_id": "avat_01KMZHXFPBVCXA5ATK85HCP8G1"
}
{
"success": false,
"error": {
"message": "No image provided",
"suggestion": "Supply an image via: file upload (\"file\" field in multipart/form-data), URL (\"image_url\"), or base64 string (\"image_base64\")"
}
}
{
"success": false,
"error": {
"message": "Failed to fetch image from URL (HTTP 403)",
"suggestion": "Check that the URL is publicly accessible"
}
}
{
"success": false,
"error": {
"message": "No face detected in the image",
"suggestion": "Upload a clear portrait photo with one visible face"
}
}
{
"success": false,
"error": {
"message": "Multiple faces detected",
"suggestion": "Upload a photo with only one person"
}
}
{
"success": false,
"error": {
"message": "Unauthorized"
}
}
What This Does: Validates that the image contains exactly one prominent face, automatically detects the image orientation (landscape, portrait, or square), aligns the face to the appropriate avatar profile, and stores the result. Returns a preview URL, a full-resolution image URL, and an avatar ID for use in sessions.
Input Methods
Supply the image using exactly one of the following options:| Method | Content-Type | Field |
|---|---|---|
| File upload | multipart/form-data | file |
| Image URL | application/json or multipart/form-data | image_url |
| Base64 string | application/json or multipart/form-data | image_base64 |
Body
file
Portrait photo to process. Accepted formats:
jpeg, jpg, png, gif, webp. Maximum size: 10 MB.
The image must contain exactly one clearly visible, prominent face.
Send as multipart/form-data.string
Publicly accessible URL of a portrait photo. The server fetches the image directly.
Accepted formats:
jpeg, jpg, png, gif, webp. Maximum size: 10 MB.
Can be sent as JSON (application/json) or as a text field in multipart/form-data.string
Base64-encoded portrait photo. A data URI prefix (e.g.
data:image/jpeg;base64,) is accepted but not required.
Maximum decoded size: 10 MB.
Can be sent as JSON (application/json) or as a text field in multipart/form-data.Response
boolean
Whether the upload and face alignment succeeded.
string
Signed URL of the aligned avatar at 500×500 px, suitable for display in the UI.
string
Signed URL of the full-resolution aligned avatar (capped at 1200 px wide).
string
The avatar ID (format:
avat_<ULID>). Use this as the avatar_id when calling Preview Avatar or as the avatar_image_url in session and agent payloads.{
"success": true,
"preview_url": "https://cdn.agenthuman.com/avatars/avat_01KMZHXFPBVCXA5ATK85HCP8G1/preview",
"image_url": "https://cdn.agenthuman.com/avatars/avat_01KMZHXFPBVCXA5ATK85HCP8G1/image",
"avatar_id": "avat_01KMZHXFPBVCXA5ATK85HCP8G1"
}
{
"success": false,
"error": {
"message": "No image provided",
"suggestion": "Supply an image via: file upload (\"file\" field in multipart/form-data), URL (\"image_url\"), or base64 string (\"image_base64\")"
}
}
{
"success": false,
"error": {
"message": "Failed to fetch image from URL (HTTP 403)",
"suggestion": "Check that the URL is publicly accessible"
}
}
{
"success": false,
"error": {
"message": "No face detected in the image",
"suggestion": "Upload a clear portrait photo with one visible face"
}
}
{
"success": false,
"error": {
"message": "Multiple faces detected",
"suggestion": "Upload a photo with only one person"
}
}
{
"success": false,
"error": {
"message": "Unauthorized"
}
}