> ## 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. Every plan includes unlimited saved custom avatars. Image moderation quotas and creation capacity limits still apply. ## 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: Avatar Videos - name: Meetings - name: Personas - name: Avatars - name: Voices - name: Pronunciation Dictionaries - name: LLMs - name: Knowledge - name: Tools - name: Share Links - name: Engine 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. Every plan includes unlimited saved custom avatars. Image moderation quotas and creation capacity limits still apply. 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. imageProcessing: type: string enum: - auto - preserve default: auto description: >- auto crops and may outpaint the image. preserve uses the source pixels without resizing, cropping, padding, outpainting or alignment/refinement. Requires an opaque, static, 8-bit RGB or RGBA PNG of exactly 1152x1152 pixels, at most 4.5MB, with no EXIF metadata. RGBA alpha must be fully opaque. Cannot be combined with zoomOutPercent or widerPercent. Moderation, quotas and facial compatibility checks still apply. Character animation quality varies with human-like facial features. Output video still uses the normal landscape or portrait crop; sourceImageUrl returns the square source. Animation frames may change. widerPercent: type: integer minimum: 0 maximum: 40 description: >- Frames the avatar this many percent wider than the standard crop, so more of the scene shows around the face, like the framing control in the Lab. The image is outpainted where it doesn't reach. An image that still falls up to 2 points short is framed as wide as it reaches; one that falls further short returns 422 with code framing_too_wide. 0 is the standard crop, which can be tighter than the default crop you get by omitting the field: on photos where the face is small, the default zooms out by up to about 10%. The Lab's framing control starts at 10. The framing is fixed when the avatar is created. Cannot be combined with zoomOutPercent or imageProcessing preserve. In production it is enabled per organization; otherwise the request returns 403 with code framing_not_enabled. zoomOutPercent: type: number minimum: 0 maximum: 60 deprecated: true description: >- Deprecated; use widerPercent. Zooms the default crop out by this percent, up to the organization's zoom-out limit (10 unless Anam raises it). A value above the limit returns 400. Cannot be combined with widerPercent or imageProcessing preserve. avatarModel: type: string description: >- Avatar model for creation. Defaults to cara-4.1-express. Cara 2 and Cara 3 creation are not supported. enum: - cara-4 - cara-4.1-express - cara-4-latest application/json: examples: default: $ref: '#/components/examples/AvatarCreate' preserve: summary: Use a prepared PNG without cropping or outpainting value: displayName: My character imageUrl: https://example.com/character-1152.png imageProcessing: preserve avatarModel: cara-4.1-express schema: type: object required: - displayName - imageUrl properties: displayName: type: string description: Display name for the avatar (1+ characters) imageUrl: type: string format: uri description: >- Public URL of a JPEG, PNG or WebP image, at most 4.5MB. It is downloaded, processed and stored permanently. imageProcessing: type: string enum: - auto - preserve default: auto description: >- auto crops and may outpaint the image. preserve uses the source pixels without resizing, cropping, padding, outpainting or alignment/refinement. Requires an opaque, static, 8-bit RGB or RGBA PNG of exactly 1152x1152 pixels, at most 4.5MB, with no EXIF metadata. RGBA alpha must be fully opaque. Cannot be combined with zoomOutPercent or widerPercent. Moderation, quotas and facial compatibility checks still apply. Character animation quality varies with human-like facial features. Output video still uses the normal landscape or portrait crop; sourceImageUrl returns the square source. Animation frames may change. widerPercent: type: integer minimum: 0 maximum: 40 description: >- Frames the avatar this many percent wider than the standard crop, so more of the scene shows around the face, like the framing control in the Lab. The image is outpainted where it doesn't reach. An image that still falls up to 2 points short is framed as wide as it reaches; one that falls further short returns 422 with code framing_too_wide. 0 is the standard crop, which can be tighter than the default crop you get by omitting the field: on photos where the face is small, the default zooms out by up to about 10%. The Lab's framing control starts at 10. The framing is fixed when the avatar is created. Cannot be combined with zoomOutPercent or imageProcessing preserve. In production it is enabled per organization; otherwise the request returns 403 with code framing_not_enabled. zoomOutPercent: type: number minimum: 0 maximum: 60 deprecated: true description: >- Deprecated; use widerPercent. Zooms the default crop out by this percent, up to the organization's zoom-out limit (10 unless Anam raises it). A value above the limit returns 400. Cannot be combined with widerPercent or imageProcessing preserve. avatarModel: type: string description: >- Avatar model for creation. Defaults to cara-4.1-express. Cara 2 and Cara 3 creation are not supported. enum: - cara-4 - cara-4.1-express - cara-4-latest 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, a body that is neither valid JSON nor multipart/form-data, or a multipart body with neither or both of image file and image URL. JSON bodies must supply imageUrl. Legacy engineKey creation is no longer supported. details lists the offending field path. widerPercent must be a whole number from 0 to 40. zoomOutPercent, widerPercent and preserve cannot be combined; invalid imageProcessing values are rejected. content: application/json: schema: type: object properties: error: type: string details: type: array items: type: object properties: path: type: string message: type: string code: type: string summary: type: string example: error: Validation error details: - path: imageUrl message: imageUrl is required code: custom summary: 'imageUrl: imageUrl is required' '401': description: Unauthorized - Invalid or missing API key '403': description: >- Forbidden - API key lacks the required permission, custom avatar API access is disabled for this organization, or widerPercent is not enabled for this organization (code framing_not_enabled). content: application/json: schema: type: object required: - error properties: error: type: string code: type: string enum: - framing_not_enabled description: >- Present when widerPercent is not enabled for this organization. '409': description: >- An identical image, name, model, processing mode and crop request is already in progress for this organization. Code CREATION_IN_PROGRESS. Check the avatar list before submitting again; completed results are not replayed. content: application/json: schema: type: object required: - error - code properties: error: type: string code: type: string enum: - CREATION_IN_PROGRESS '422': description: >- Unprocessable Entity - Image could not be processed, does not meet preserve-mode PNG requirements, falls more than 2 points short of the requested widerPercent even after outpainting (code framing_too_wide, with maxWiderPercent), or was rejected by Anam or the outpainting provider. This includes photos in which the avatar model cannot find exactly one human face to animate, such as many animal, cartoon or statue images; repeating the same request gets the same result. Provider content rejections include code outpaint_content_blocked and should not be retried with the same image. content: application/json: schema: type: object required: - error - code properties: error: type: string code: type: string enum: - image_unprocessable - moderation_blocked - outpaint_content_blocked - framing_too_wide description: >- image_unprocessable means the image can't be used as an avatar source, for example no single human face or an invalid preserve-mode PNG. moderation_blocked means Anam's content moderation rejected it. outpaint_content_blocked means the outpainting provider's content checker rejected it. framing_too_wide means the image holds more than 2 points less than the requested widerPercent; retry with at most maxWiderPercent. maxWiderPercent: type: integer description: >- With framing_too_wide, the widest widerPercent this image holds. example: error: >- The image provider could not extend this photo because its content checker rejected the request. Try another photo, or contact support if you believe this is a mistake. code: outpaint_content_blocked '429': description: >- Creation capacity is full (code CREATION_BUSY, Retry-After 5 seconds, no job started) or organization-wide image moderation quota exhausted. Quotas depend on the plan. Per UTC day they are 10 on Free, 100 on Starter, 250 on Explorer, 500 on Growth and 1,000 on Professional, Enterprise and Anam Partner. Per UTC minute they are 5 on Free and Starter, 10 on Explorer, 20 on Growth and 30 on Professional, Enterprise and Anam Partner. Anam can raise them per organization. Checks count even if moderation rejects the image or avatar creation later fails; cached moderation does not consume another check. The daily reset takes precedence when both quotas are exhausted. Retry at resetAt or contact Anam support for a higher image moderation limit. Saved custom avatars are unlimited. Session concurrency is a separate limit. headers: Retry-After: description: >- Seconds to wait before retrying. Creation capacity returns 5; moderation returns time until the exhausted quota resets, rounded up. schema: type: integer minimum: 1 example: 12045 Access-Control-Expose-Headers: description: Allows browser clients to read Retry-After. schema: type: string example: Retry-After content: application/json: schema: type: object required: - error - code properties: error: type: string description: >- Human-readable quota, usage, UTC reset time, and recovery advice. code: type: string enum: - moderation_rate_limited - CREATION_BUSY rateLimit: type: object required: - scope - window - limit - used - remaining - resetAt - retryAfterSeconds properties: scope: type: string enum: - organization window: type: string enum: - minute - day description: >- The exhausted window that determines when requests can resume. limit: type: number description: Effective quota for this organization and window. used: type: integer description: Checks already counted in this window. remaining: type: integer enum: - 0 resetAt: type: string format: date-time description: >- Absolute reset time in UTC, at the next minute boundary or midnight. retryAfterSeconds: type: integer minimum: 1 description: Same delay as the Retry-After response header. upgrade: type: object description: >- Present on the daily window when a self-serve plan has a higher daily quota. Absent on the per-minute window and when no self-serve plan raises the quota. required: - plan - planName - limit - url properties: plan: type: string example: explorer planName: type: string example: Explorer limit: type: integer description: The plan's daily image moderation quota. url: type: string format: uri description: >- Lab checkout page for the plan. An organization owner completes the upgrade there. examples: creationBusy: value: error: Avatar creation is busy. Waiting for an available slot. message: Avatar creation is busy. Waiting for an available slot. code: CREATION_BUSY retryable: true dailyLimit: $ref: '#/components/examples/AvatarModerationDailyLimit' minuteLimit: $ref: '#/components/examples/AvatarModerationMinuteLimit' '500': description: Server error '502': description: >- The avatar worker or an upstream generation provider failed. This is a service failure, not an invalid image. The request is not automatically replayed. content: application/json: schema: type: object required: - error - code properties: error: type: string example: >- Avatar processing could not be completed. Contact support if the problem persists. code: type: string enum: - worker_failed - outpaint_provider_failed - outpaint_download_failed description: >- worker_failed includes uncertain worker outcomes and does not establish that retrying is safe. The outpainting codes identify recognized, completed provider or output-download failures. '503': description: >- Creation admission is unavailable (code CREATION_UNAVAILABLE), or the API key could not be checked because of a temporary server problem (the key may be valid; retry after `Retry-After` seconds). No avatar job has started; retry later. headers: Retry-After: description: Seconds to wait before retrying, when known. schema: type: integer content: application/json: schema: oneOf: - type: object required: - error - code properties: error: type: string code: type: string enum: - CREATION_UNAVAILABLE - $ref: '#/components/schemas/ServiceUnavailableError' 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/api/avatars/071b0286-4cce-4808-bee2-e642f1062de3/image/landscape?v=3f2a1b0c9d8e7f6a sourceImageUrl: >- https://example.public.blob.vercel-storage.com/avatar-previews/liv_home.webp landscapeImageUrl: >- https://lab.anam.ai/api/avatars/071b0286-4cce-4808-bee2-e642f1062de3/image/landscape?v=3f2a1b0c9d8e7f6a portraitImageUrl: >- https://lab.anam.ai/api/avatars/071b0286-4cce-4808-bee2-e642f1062de3/image/portrait?v=3f2a1b0c9d8e7f6a videoUrl: >- https://example.com/avatars/cara-4/stock/liv_home/talking_preview_video.mp4?X-Amz-Signature=... idleVideoUrl: >- https://example.com/avatars/cara-4/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: - cara-4 activeVersion: cara-4 description: >- A friendly professional in a modern office setting, warm expression, business casual attire. displayTags: - professional - friendly - office renderStyle: realistic AvatarModerationDailyLimit: summary: Daily organization image moderation quota exhausted value: error: >- Your organization has used 100 of 100 daily image moderation checks. This quota is shared across your organization and counts checks even when an image is rejected or avatar creation fails. Upgrade to Explorer for 250 checks a day at https://lab.anam.ai/subscription/confirm?plan=explorer, or retry after 2026-09-10 00:00:00 UTC, in 12045 seconds. code: moderation_rate_limited rateLimit: scope: organization window: day limit: 100 used: 100 remaining: 0 resetAt: '2026-09-10T00:00:00.000Z' retryAfterSeconds: 12045 upgrade: plan: explorer planName: Explorer limit: 250 url: https://lab.anam.ai/subscription/confirm?plan=explorer AvatarModerationMinuteLimit: summary: Minute organization image moderation quota exhausted value: error: >- Your organization has used 5 of 5 per-minute image moderation checks. This quota is shared across your organization and counts checks even when an image is rejected or avatar creation fails. Retry after 2026-09-09 20:40:00 UTC, in 45 seconds, or contact Anam support to request a higher image moderation limit. code: moderation_rate_limited rateLimit: scope: organization window: minute limit: 5 used: 5 remaining: 0 resetAt: '2026-09-09T20:40:00.000Z' retryAfterSeconds: 45 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: >- Still image of the avatar, framed exactly like `videoUrl`, `idleVideoUrl` and a landscape session (the default). Use it as the thumbnail, poster or loading image wherever a preview video or the live stream replaces it, and give the image and the video the same box, `object-fit` and `object-position` so the avatar doesn't move when they swap. For Cara 4 avatars this is the 1152x768 landscape crop (the same image as `landscapeImageUrl`). Cara 4 avatars used to return their square source image here; that image is now `sourceImageUrl`. Empty when the avatar has no image yet, or when its images are not available through the API. May be a time-limited link; see `imageUrlsExpireAt`. sourceImageUrl: type: string format: uri description: >- The image the avatar was created from. For Cara 4 avatars it is square (1152x1152) and shows more of the scene than the 1152x768 crop that preview videos and sessions use, so the avatar appears to zoom in when a video or call replaces it. Don't use it as a thumbnail, poster or loading image next to `videoUrl` or a session; use `imageUrl`, `landscapeImageUrl` or `portraitImageUrl`. For legacy avatars it is the same landscape image as `imageUrl`. Empty when the avatar's images are not available through the API. May be a time-limited link; see `imageUrlsExpireAt`. landscapeImageUrl: type: - string - 'null' format: uri description: >- Still image cropped exactly as the engine frames landscape (1152x768) output, which is also the framing of `videoUrl` and `idleVideoUrl`. Use it with landscape sessions (the default) and preview videos. For avatars with legacy landscape source images this is the source image. `null` when the avatar's images are not available through the API. May be a time-limited link; see `imageUrlsExpireAt`. portraitImageUrl: type: - string - 'null' format: uri description: >- Still image cropped exactly as the engine frames portrait (768x1152) output. Use it as the poster for a session started with portrait `videoWidth`/`videoHeight`. Preview videos are landscape, so don't swap this image for `videoUrl`. `null` when the avatar cannot render portrait output or its images are not available through the API. May be a time-limited link; see `imageUrlsExpireAt`. imageUrlsExpireAt: type: - string - 'null' format: date-time description: >- When set, `imageUrl`, `sourceImageUrl`, `landscapeImageUrl` and `portraitImageUrl` are time-limited links that stop working at this time; fetch the avatar again for fresh ones. They stay valid for at least an hour, and repeated requests within the same hour return the same links, so browsers can cache them. Treat them as credentials for those images, since anyone holding a link can load the image until it expires. `null` when the image URLs don't expire. videoUrl: type: - string - 'null' format: uri description: >- Signed URL for a verified muted MP4 preview of the avatar. Uses the idle loop if the talking preview is unavailable. Landscape (1152x768 for Cara 4 avatars, 720x480 for legacy avatars) and framed exactly like `imageUrl`, so pair it with `imageUrl` or `landscapeImageUrl`, not `sourceImageUrl`. The URL expires after 1 hour; re-fetch the avatar to get a fresh URL. `null` when the preview is unavailable or still generating. idleVideoUrl: type: - string - 'null' format: uri description: >- Signed URL for a muted idling-loop MP4 of the avatar, if one exists. Landscape and framed exactly like `imageUrl`, like `videoUrl`. The URL expires after 1 hour; re-fetch the avatar to get a fresh URL. `null` when 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: >- Avatar models this avatar can be used with. Pass one of these values as `avatarModel` when creating a persona or starting a session. activeVersion: type: - string - 'null' description: >- Avatar model used by default when no explicit `avatarModel` is requested. description: type: - string - 'null' description: >- AI-generated description of the avatar's appearance, setting, and style. `null` if metadata generation has not completed. displayTags: type: array items: type: string description: >- Curated tags describing the avatar. Empty array if metadata generation has not completed. renderStyle: type: string enum: - realistic - animated_3d - illustrated - unknown description: >- Render style of the avatar. `unknown` covers custom avatars and avatars whose metadata has not yet been generated. ServiceUnavailableError: type: object required: - error - message properties: error: type: string example: Service temporarily unavailable message: type: string example: We could not check your API key. Please retry shortly. securitySchemes: BearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.