Create Avatar
API reference for avatar generation.
Create Avatar
Generate an AI avatar by creating a job.
Endpoint
POST /api/v1/projects/{project_id}/jobs/avatars
Request
curl -X POST 'https://api.smavatar.com/api/v1/projects/{project_id}/jobs/avatars' \
-H 'Authorization: Bearer sma_your_api_key' \
-H 'Content-Type: application/json' \
-d '{
"style_id": "cartoon_flat_modern",
"quality": "standard",
"size": "square",
"parameters": {
"subject": "fox",
"theme": "astronaut",
"gender": "neutral",
"color": "orange"
}
}'
Required Fields
| Field | Type | Description |
|---|---|---|
style_id | string | Art style ID (see Styles) |
parameters.subject | string | Character type: fox, cat, dog, owl, bear, robot, etc. |
parameters.theme | string | Role/costume: astronaut, scientist, chef, detective, etc. |
parameters.gender | string | male, female, or neutral |
parameters.color | string | Primary color: orange, blue, purple, green, etc. |
Optional Fields
| Field | Type | Default | Description |
|---|---|---|---|
quality | string | standard | economy, standard, or high |
size | string | square | square, landscape, or portrait |
Response
Success (201)
{
"success": true,
"job": {
"id": "abc123-def456-ghi789",
"job_type": "avatar",
"project_id": "your-project-id",
"style": {
"id": "cartoon_flat_modern",
"label": "Cartoon (Flat Modern)"
},
"quality": "standard",
"size": "square",
"status": "pending",
"estimated_token_cost": 2,
"created_at": "2024-01-15T10:30:00Z"
},
"message": "Avatar job created successfully. It will be processed shortly."
}
Insufficient Tokens (402)
{
"statusCode": 402,
"statusMessage": "Insufficient Tokens",
"message": "Not enough tokens",
"data": {
"required_tokens": 2,
"available_tokens": 1,
"action_type": "avatar.generate.standard.square"
}
}
Style Not Found (404)
{
"statusCode": 404,
"message": "Style 'invalid-style' not found or inactive"
}
Check Job Status
curl 'https://api.smavatar.com/api/v1/projects/{project_id}/jobs/avatars/{job_id}' \
-H 'Authorization: Bearer sma_your_api_key'
Completed Response
{
"success": true,
"job": {
"id": "abc123-def456-ghi789",
"status": "completed",
"actual_token_cost": 2,
"assets": [
{
"id": "asset-uuid",
"storage_path": "project-id/job-id/avatar.png",
"format": "png",
"width": 1024,
"height": 1024
}
]
}
}
Download Image
Construct the URL from storage_path:
https://hxqvyxnnppomqqwglxwo.supabase.co/storage/v1/object/public/avatars/{storage_path}
Rate Limits
- 60 job creations per hour per API key
- Exceeds limit returns
429 Too Many Requests
See Pricing for token costs by quality and size.