> ## Documentation Index > Fetch the complete documentation index at: https://docs.spatius.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create an Avatar > Accepts a source image URL and queues an asynchronous Avatar creation job. Spatius downloads and validates the image, preprocesses it, and generates the Avatar through the Studio pipeline. Poll `GET /avatar-jobs/{jobId}` until the job reaches `succeeded` or `failed`. The request is admitted only when your account is within its creation rate limits, rolling 24-hour quota, and concurrency limit, and holds enough Avatar Creations. A creation is reserved when the job is accepted and captured when preprocessing completes; it is released if the job fails before capture. Source image requirements: - Public HTTP(S) URL, reachable within 3 seconds - JPEG or PNG, at most 5 MiB - Shorter side at least 340 pixels - PNG images must be fully opaque - Exactly one clearly visible face ## OpenAPI ````yaml /openapi/avatar-open-api.json post /avatars openapi: 3.0.3 info: title: Spatius API version: 1.0.0 description: >- The Spatius API lets you create and manage avatars programmatically. Submit a source image, poll the asynchronous creation job, and use the resulting avatar ID anywhere an avatar ID is accepted in your SDK integration. All endpoints require the `X-App-ID` and `X-API-Key` headers. See [Authentication](/api-reference/authentication) and [Errors and Limits](/api-reference/errors). servers: - url: https://console.spatius.ai/v1/open description: Spatius Console API (global) security: - AppId: [] ApiKey: [] tags: - name: Avatars description: >- Create Avatars and read the canonical Studio Avatar resources owned by your account. - name: Avatar Jobs description: Track asynchronous Avatar creation jobs. paths: /avatars: post: tags: - Avatars summary: Create an Avatar description: >- Accepts a source image URL and queues an asynchronous Avatar creation job. Spatius downloads and validates the image, preprocesses it, and generates the Avatar through the Studio pipeline. Poll `GET /avatar-jobs/{jobId}` until the job reaches `succeeded` or `failed`. The request is admitted only when your account is within its creation rate limits, rolling 24-hour quota, and concurrency limit, and holds enough Avatar Creations. A creation is reserved when the job is accepted and captured when preprocessing completes; it is released if the job fails before capture. Source image requirements: - Public HTTP(S) URL, reachable within 3 seconds - JPEG or PNG, at most 5 MiB - Shorter side at least 340 pixels - PNG images must be fully opaque - Exactly one clearly visible face operationId: createAvatar requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAvatarRequest' examples: default: value: name: Support Agent imageUrl: https://example.com/portraits/agent.png responses: '200': description: The creation job was accepted and queued. content: application/json: schema: $ref: '#/components/schemas/CreateAvatarResponse' example: jobId: 6f1e2b3c-9a1d-4e5f-8b0a-2c4d6e8f0a1b status: queued createdAt: '2026-07-25T09:30:00Z' '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/InsufficientAvatarUnits' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailable' components: schemas: CreateAvatarRequest: type: object required: - imageUrl properties: name: type: string description: >- Optional display name. When omitted, a name like `Avatar-` is generated. imageUrl: type: string format: uri description: >- Public HTTP(S) URL of the source image. Validated asynchronously after the job is accepted. CreateAvatarResponse: type: object properties: jobId: type: string format: uuid description: >- ID of the accepted creation job. Poll it with `GET /avatar-jobs/{jobId}`. status: $ref: '#/components/schemas/JobStatus' createdAt: type: string format: date-time JobStatus: type: string description: Lifecycle status of an Avatar creation job. enum: - queued - processing - succeeded - failed Error: type: object description: The single public error envelope returned by every Spatius API endpoint. properties: error: type: object properties: code: type: string description: Stable machine-readable error code. enum: - unauthorized - forbidden - invalid_request - not_found - insufficient_avatar_units - rate_limit_exceeded - concurrency_limit_exceeded - service_unavailable - unsupported_input - internal_error message: type: string description: Human-readable explanation specific to this occurrence. requestId: type: string description: >- Unique identifier for this request. Quote it when contacting support. responses: InvalidRequest: description: >- The request is malformed or violates a precondition, such as a missing `imageUrl` or an invalid ID in the path. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_request message: imageUrl is required requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f Unauthorized: description: >- The `X-App-ID` / `X-API-Key` pair is missing, does not match, or belongs to an inactive account. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized message: Unauthorized. requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f InsufficientAvatarUnits: description: The account has no Avatar Creations left to create this Avatar. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: insufficient_avatar_units message: There are not enough Avatar Units to create this Avatar. requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f Forbidden: description: >- API access is not configured for the account, or avatar creation is disabled. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: forbidden message: API Avatar creation is disabled requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f RateLimited: description: >- A rate limit, rolling 24-hour quota, or concurrency limit was exceeded. Back off and retry. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limit_exceeded message: Open API rate limit exceeded requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f InternalError: description: An unexpected server error occurred. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: internal_error message: An internal error occurred. requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f ServiceUnavailable: description: >- A transient backend failure occurred, for example reservation contention. Retry the request. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: service_unavailable message: Avatar Unit reservation failed; retry later requestId: b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f securitySchemes: AppId: type: apiKey in: header name: X-App-ID description: Your Spatius App ID. ApiKey: type: apiKey in: header name: X-API-Key description: The API key bound to the App ID. ````