Avatars

Generate, save, and retrieve marketing-style avatar images.

Create marketing-style avatar images from a short creative prompt. Generation runs in the background; you poll a job until the image is ready, then optionally save it for reuse.

Endpoints

Method	Path	Description
POST	/api/v1/avatars/generate	Queue an avatar generation job
POST	/api/v1/avatars/save	Save a completed avatar for reuse
GET	/api/v1/avatars	List saved avatars
GET	/api/v1/avatars/:id	Get a specific saved avatar

Authentication

Authorization: Bearer <your_api_key>

---

Generate an avatar

POST /api/v1/avatars/generate

Returns 202 Accepted with a job_id. You poll the Jobs API for the result.

Input modes

Library-assisted — Send only prompt (and optional hints). The service selects an internal reference for inspiration and generates a new character. The internal library is always used.

Bring your own references — Send reference_images (1–6 items). The internal library is skipped; generation uses your images together with prompt and hints.

Reference images: max 6 per request, max 15 MB each. Accepted formats: JPEG, PNG, WebP.

Request parameters

prompt · string · required

Creative description of the avatar you want. Non-empty string up to 5,000 characters.

hints · object

Flat object to steer composition, style, and cultural context. Invalid keys are ignored downstream; prefer documented keys for predictable results.

Show Common hint keys

hints.filter_culture · string

Cultural context, e.g. "middle_east", "west_africa", "east_asia".

hints.avatar_composition · string

Framing, e.g. "Portrait", "Half Body", "Full Body".

hints.art_direction · string

Visual style, e.g. "Ultra Realistic", "Illustration".

hints.lighting · string

Lighting style, e.g. "soft studio", "natural outdoor".

hints.background · string

Background description, e.g. "clean white", "blurred city street".

hints.ethnicity · string

Ethnic presentation hint.

hints.gender_expression · string

Gender expression hint.

hints.filter_industry · string

Industry context for style calibration, e.g. "fintech", "health".

reference_images · string[]

1–6 reference images as data URLs (data:image/...;base64,...) or raw base64 strings. When provided, the internal library is skipped.

output · object

Output controls. All subfields are optional.

Show output fields

output.aspect_ratio · string

Canvas aspect ratio. Use auto to let the server derive it from hints.avatar_composition, or specify one of: 1:1, 1:4, 1:8, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, 21:9. Defaults to auto.

output.resolution · string

Pixel tier: 512, 1K, 2K, or 4K. Defaults to 1K. Note: lowercase 1k is rejected by validation.

output.thinking_intensity · string

Reasoning depth. Options: minimal or high.

client_reference_id · string

Your own correlation ID for workflow or agent tracing. Echoed into the job record. Maximum 200 characters.

metadata · object

String map echoed into the job payload and webhook delivery. Maximum 16 keys; each value up to 500 characters.

Example request

curl

curl -X POST "https://api.trypi.ai/api/v1/avatars/generate" \
  -H "Authorization: Bearer pi_live_***" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4cb74a64-83f1-4fb8-96cf-1098f145008f" \
  -d '{
    "prompt": "confident founder vibe for a fintech app, modest professional outfit",
    "hints": {
      "filter_culture": "middle_east",
      "avatar_composition": "Portrait",
      "art_direction": "Ultra Realistic"
    },
    "output": {
      "aspect_ratio": "auto",
      "resolution": "1K",
      "thinking_intensity": "minimal"
    },
    "client_reference_id": "workflow-run-123-step-7",
    "metadata": {
      "workflow": "lead-enrichment",
      "customer_id": "cus_123"
    }
  }'

Response (202)

id · string

Request identifier (e.g. req_pi_...).

object · string

Always "job".

status · string

Initial status: "queued".

created_at · number

Unix timestamp of when the request was created.

data.job_id · string

UUID of the background generation job.

{
  "id": "req_pi_...",
  "object": "job",
  "status": "queued",
  "created_at": 1710000000,
  "data": { "job_id": "<uuid>" }
}

Polling for the result

GET /api/v1/jobs/:job_id?wait_for_completion=true&timeout_seconds=30&expand=avatar

When the job is completed, use data.avatar.image_url for the generated image.

Idempotency

Send an Idempotency-Key header to make retries safe. Replaying the same key with the same request body returns the original 202 response. Using the same key with a different body returns 409 idempotency_key_mismatch.

---

Save an avatar

POST /api/v1/avatars/save

Persist a completed generation so you can retrieve the URL later without regenerating. The job must be completed and owned by your organization.

Request parameters

job_id · string · required

UUID of the completed avatar generation job.

label · string

Human-readable label for the saved avatar, e.g. "CEO hero v2".

Example request

curl

curl -X POST "https://api.trypi.ai/api/v1/avatars/save" \
  -H "Authorization: Bearer pi_live_***" \
  -H "Content-Type: application/json" \
  -d '{"job_id": "<job_id>", "label": "CEO hero v2"}'

Avatar object

id · string

Unique identifier of the saved avatar record.

label · string

The label you assigned when saving.

image_url · string

URL of the generated avatar image.

job_id · string

UUID of the source generation job.

created_at · number

Unix timestamp of when the avatar was saved.

---

List saved avatars

GET /api/v1/avatars

Returns a paginated list of saved avatars for your organization.

Query parameters

limit · number

Number of results to return. Default: 20.

offset · number

Pagination offset. Default: 0.

Example request

curl -X GET "https://api.trypi.ai/api/v1/avatars?limit=20&offset=0" \
  -H "Authorization: Bearer pi_live_***"

---

Get a saved avatar

GET /api/v1/avatars/:id

Returns a single saved avatar by its ID.

Path parameters

id · string · required

ID of the saved avatar record.

Example request

curl -X GET "https://api.trypi.ai/api/v1/avatars/<saved_avatar_id>" \
  -H "Authorization: Bearer pi_live_***"