> ## Documentation Index > Fetch the complete documentation index at: https://anam.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # create avatar > Create a new one-shot avatar from an image file or image URL. You can use either multipart/form-data with an image file, or JSON with an image URL. ## OpenAPI ````yaml https://api.anam.ai/swagger.json post /v1/avatars openapi: 3.1.0 info: title: Anam AI API version: '1.0' servers: - url: https://api.anam.ai description: Anam API security: - BearerAuth: [] tags: - name: Sessions - name: Personas - name: Avatars - name: Voices - name: LLMs - name: Knowledge - name: Tools - name: Share Links paths: /v1/avatars: post: tags: - Avatars summary: create avatar description: >- Create a new one-shot avatar from an image file or image URL. You can use either multipart/form-data with an image file, or JSON with an image URL. operationId: createAvatar requestBody: description: >- Source image and display name for the new one-shot avatar. Provide either an uploaded file (`multipart/form-data` with `imageFile`) or a URL (`application/json` with `imageUrl`) — not both. required: true content: multipart/form-data: schema: type: object required: - displayName properties: displayName: type: string description: Display name for the avatar (3-50 characters) imageFile: type: string format: binary description: >- Image file to create the avatar from (JPEG, PNG, or WebP, max 4.5MB). Either imageFile or imageUrl must be provided, but not both. imageUrl: type: string format: uri description: >- URL of the image to create the avatar from (JPEG, PNG, or WebP, max 4.5MB). Either imageFile or imageUrl must be provided, but not both. avatarModel: type: string description: >- Avatar model to use (e.g. "cara-3", "cara-4-latest"). Defaults to the server default model. Gated models require organization-level access. application/json: examples: default: $ref: '#/components/examples/AvatarCreate' schema: type: object required: - displayName - imageUrl properties: displayName: type: string description: Display name for the avatar (1+ characters) imageUrl: type: string format: uri description: >- URL of the image to create the avatar from (JPEG, PNG, or WebP, max 4.5MB). The image will be downloaded, processed, and stored permanently. avatarModel: type: string description: >- Avatar model to use (e.g. "cara-3", "cara-4-latest"). Defaults to the server default model. Gated models require organization-level access. responses: '201': description: Successfully created avatar content: application/json: schema: $ref: '#/components/schemas/Avatar' examples: default: $ref: '#/components/examples/AvatarResponse' '400': description: >- Bad request - Invalid avatar data, missing image file/URL, or both provided '401': description: Unauthorized - Invalid or missing API key '403': description: Forbidden - Requires enterprise plan '422': description: Unprocessable Entity - Image could not be processed '500': description: Server error components: examples: AvatarCreate: summary: Create a one-shot avatar from an image URL value: displayName: Alex imageUrl: https://example.com/alex.jpg AvatarResponse: summary: A single avatar resource value: id: 071b0286-4cce-4808-bee2-e642f1062de3 displayName: Liv variantName: home imageUrl: https://lab.anam.ai/persona_thumbnails/liv_home.png videoUrl: >- https://anam-prod.r2.cloudflarestorage.com/avatars/v2/stock/liv_home/idling_video.mp4?X-Amz-Signature=... createdAt: '2026-04-20T10:00:00.000Z' updatedAt: '2026-04-20T10:00:00.000Z' createdByOrganizationId: null availableVersions: - v1 - v2 - cara-4-3 activeVersion: v2 schemas: Avatar: type: object description: A face preset that a persona can use as its visual representation. properties: id: type: string format: uuid description: Unique identifier for the avatar. displayName: type: string description: Human-readable name shown in the Lab and share links. variantName: type: string description: >- Name of the specific variant (e.g. lighting or pose) within the avatar family. imageUrl: type: string format: uri description: URL of the still image used as a preview of the avatar. videoUrl: type: - string - 'null' format: uri description: >- Signed URL for a muted idling MP4 preview of the avatar, if one exists. The URL expires after 1 hour; re-fetch the avatar to get a fresh URL. `null` when the preview is unavailable or still generating. createdAt: type: string format: date-time description: Timestamp when the avatar was created. updatedAt: type: string format: date-time description: Timestamp when the avatar was last updated. createdByOrganizationId: type: - string - 'null' description: >- ID of the organization that created the avatar, or `null` for stock avatars. IDs may be either UUIDs or nanoid-style strings depending on when the organization was created. availableVersions: type: array items: type: string description: >- Internal avatar version identifiers this avatar has generated assets for. Current public model mappings are `v1` = `cara-2`, `v2` = `cara-3`, and `cara-4-*` = `cara-4-latest`. Use the public `avatarModel` request field when selecting a model. activeVersion: type: string description: >- Internal avatar version used by default when no explicit `avatarModel` is requested. Current public model mappings are `v1` = `cara-2`, `v2` = `cara-3`, and `cara-4-*` = `cara-4-latest`. securitySchemes: BearerAuth: type: http scheme: bearer ````