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"
  }
}

POST

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"
  }
}

Getting Started

Sessions

Avatars

OpenClaw

Usage & Billing

Schemas

Upload Face Avatar

Input Methods

Body

Response

​Input Methods

​Body

​Response

Input Methods

Body

Response