KeenFace
Pricing
Contact SalesCreate in Studio

Developers

KeenFace API reference

Every endpoint, parameter and response, as plain text.

Interactive referenceMarkdownOpenAPI spec

Create MetaHuman-compatible 3D heads with production-ready 4K PBR textures from photos.

Turn images of one person into a neutral head in MetaHuman topology, ready to download as GLB, OBJ or MetaHuman ZIP. Choose Default for everyday photos and references, or Scan Reconstruction for a deliberately captured photo set. Both include PBR textures by default; Scan Reconstruction also offers Raw textures.

Request workflow

The request sequence is the same in both modes. Choose the mode from your images, then follow these steps.

Step Request Result / next action
1. Supply images Attach files to the create request, or upload each with POST /v2/photos Files, or reusable ph_… identifiers until a head consumes them
2. Create a head POST /v2/heads Save the returned Head.id. No separate “start processing” request is needed.
3. Wait for completion GET /v2/heads/{id}?wait=600, an event stream, or a webhook Continue only on status: completed. A failed head is final and free.
4. Request a file GET /v2/heads/{id}/model On event: retry-after, wait data.time_sec seconds and repeat the same GET.
5. Download GET the URL in event: redirect → data.url Start within 20 seconds. This signed URL needs no API key.

/model returns JSON, not file bytes or an HTTP redirect. Head creation and file preparation are separate asynchronous steps. A completed head may have models: [] until you request a file.

Choose a mode

Feature Default Scan Reconstruction
Create option Omit scan_reconstruction, or send false scan_reconstruction: true
Images 1–15 images of the same person 2–15 photos from one consistent capture set
Suitable sources Everyday photos, phone photos, portraits, downloaded internet references Photos deliberately captured from multiple angles with a still subject and consistent lighting
Processing Prepares the references for reconstruction Reconstructs directly from the supplied views
Texture PBR with clean up PBR with optional clean up, or Raw
Camera settings Automatic; no input-camera data returned Automatic or manual focal lengths; solved cameras returned
Files GLB, OBJ, MetaHuman ZIP; optional ARKit in GLB The same formats; texture content depends on your settings
Price 150 credits, all files included 150 credits, all files included

Default: everyday photos and references

Use 1–15 images that all depict the same person. They can come from different shoots, cameras, backgrounds or lighting conditions; downloaded images from the internet are welcome. A single photo works. You do not need a scan session.

For a clearer likeness:

  • Use different angles: a front view, three-quarter views from both sides and profiles when available.
  • Choose sharp images where the head is large in the frame and facial features are easy to see. Avoid distant faces, blur and crops that cut off facial features.
  • Prefer photos at a similar age, with a neutral expression, open eyes and an unobstructed face. Visible ears also help capture their shape.
  • Prefer even lighting and images without heavy filters or retouching that alter facial features.

These are quality recommendations; a single everyday photo is still valid input. All images must depict the same person. Avoid frames with other people.

Upload image files, not website links: download an online reference first, then send its bytes. The API does not accept image URLs, base64 strings, videos or 3D scans as photo inputs. Content rejection produces a free failed head with error.code: content_rejected.

Default always includes PBR and clean up. Omit texture, cleanup and focal_length from the create request; sending them, even with their usual defaults, returns 400 field_not_applicable. Head.settings is {} and Head.cameras is null.

Scan Reconstruction: capture requirements

Use 2–15 photos of one person from the same capture session, with geometrically consistent views.

Recommended views

  • Start with at least three photos: one front view and a three-quarter view from each side, about 40° from the front. The API accepts two, but three or more are recommended.
  • Add left and right profiles for a more accurate head shape.
  • For full 360° coverage, also add rear three-quarter views from both sides and a straight rear view. These supplement the front and side views.
  • To reduce texture gaps on the top and underside of the head, add views from slightly above at the front and back, and slightly below at the front. Keep these areas in frame and unobstructed.

Subject and capture setup

  • Keep the subject still, with the head upright and the same relaxed, neutral expression in every photo. Eyes should be open and looking straight ahead, without following each camera. Avoid smiling, talking and changes in expression.
  • Ideally, capture all photos simultaneously with a synchronized multi-camera rig. Otherwise, move the camera around the subject while keeping the subject and lighting unchanged.
  • Keep lighting consistent across the set. Use even, indirect light; avoid deep shadows, blown highlights, direct sunlight and flash straight at the face.
  • Keep the whole head in frame, centred, sharp and large enough to show detail from each angle. Avoid motion blur, excessive head tilt and crops that cut off features or the top of the head.
  • Keep the ears uncovered and visible in the relevant views for more accurate reconstruction. Tie back long hair, keep hands and hair away from the face, and remove glasses and head coverings where possible.

Different cameras or lenses can be used in a consistent capture setup. Use focal_length: "auto" or known per-photo focal lengths. auto_common additionally requires every image to have the same pixel dimensions. If your images come from different days or unrelated conditions, choose Default.

The API accepts any image resolution; the capture advice concerns reconstruction quality. Passing file validation does not guarantee that a photo set can be reconstructed.

Scan texture and focal length

Create field Values and effect
texture pbr (default): lighting removed from base color, plus normal, roughness and specular maps. raw: base color projected from photos, with photographed lighting and possible gaps; no PBR maps.
cleanup With PBR only. true (default) fills texture gaps, removes hair from the texture and generates the eye textures. false retains photographed hair, gaps and eyes. Omit with Raw, even if you want false.
focal_length auto (default): per-image estimate, using EXIF when every photo provides it. auto_common: a shared estimate. A number: the same focal length for every photo. An array: one number per photo, in upload order. Manual values are 35 mm equivalent, 1–2000 mm.

In a multipart form, use focal_length=50 for one value shared by the set, or focal_length=50,35,70 for three per-photo values. In JSON, use 50 or [50,35,70]. The array length must match the photo count. The supplied scalar or array is preserved in Head.settings; the solved values are in Head.cameras.

Model files

Choose files after the head completes. You can request multiple formats from the same head without reconstructing or paying again.

Two different texture fields: at creation, pbr / raw determines which maps exist. At download, jpg / png / none selects their image encoding, or omits them. Download options cannot add PBR maps to a Raw head or change its clean up setting.

/model option Default What you can request
mesh_format glb glb, obj, metahuman
texture jpg jpg, png, none (no texture maps)
blendshapes None arkit, GLB only, available in both modes and with PBR or Raw

Omit blendshapes for OBJ or MetaHuman; either format with blendshapes=arkit returns 400 invalid_request. Unknown parameters are rejected. Expression-from-photo blendshapes and configurable mesh LOD are not part of v2.

Texture content

The following applies when the download includes textures. Clean up changes texture content, not the number of source photos or the head price.

Content Default / Scan PBR with clean up Scan PBR, cleanup: false Scan Raw
Skin, 4096 × 4096 Base color, normal, roughness, specular Same maps Base color only
Eyes, 1024 × 1024 Generated base color and normal Base color from photos Base color from photos
Teeth 2048 × 2048 base color, 1024 × 1024 normal Same 2048 × 2048 base color
Corneas in GLB / OBJ Transparent reflective shells Transparent reflective shells Absent
Hair and texture gaps Removed / filled Retained Retained

The GLB skin specular map and MetaHuman Head_SRMF.png stay PNG even with texture=jpg, because they require an alpha channel. texture=none omits texture maps, but does not necessarily remove all materials: PBR GLB files retain their cornea materials, as described below.

GLB

One .glb file (model/gltf-binary), with embedded textures when requested. One head node; primitives in order: skin, eye +X, eye −X, teeth, then cornea +X and cornea −X for PBR. Raw has four primitives and no corneas. +X is the character’s left.

Mesh names and materials depend on the head and download settings:

  • PBR with textures (jpg / png): mesh Head; materials Head_Skin, Eye_L, Eye_R, Teeth, Cornea_L, Cornea_R. All six materials have metallicFactor: 0.
  • Raw with textures (jpg / png): the mesh and all four materials are unnamed. Each material has metallicFactor: 1 and no metallic map, so the head can look metallic or dark in a viewer. This applies both with and without blendshapes=arkit.
  • PBR with texture=none: mesh Head; only two materials, Cornea_L and Cornea_R, both transparent (BLEND). Skin, eyes and teeth have no assigned material and use the viewer's default appearance, typically white and matte.

For a non-metallic preview of a textured Raw GLB, set each material's pbrMetallicRoughness.metallicFactor to 0 in your importer or viewer. Identify Raw parts by primitive order, since mesh and material names are absent.

PBR corneas are transparent reflective shells using KHR_materials_ior and KHR_materials_clearcoat, including when texture=none. With PBR textures included, skin uses KHR_materials_specular. A viewer’s support for these extensions affects appearance. No skeleton or ready-made animation is supplied.

blendshapes=arkit includes 51 of the 52 ARKit morph targets; tongueOut is absent. Read morph names from mesh.extras.targetNames, not fixed indices. Without this parameter, no blendshapes are included.

OBJ

A .zip (application/zip). Its contents depend on the download's texture option:

  • jpg / png: neutral.obj, neutral.mtl and texture/ with the available maps.
  • none: only neutral.obj. There is no neutral.mtl or texture/ directory; apply your own material if needed.

OBJ groups are Head, EyeLeft, EyeRight, Teeth, plus CorneaLeft and CorneaRight for PBR. The mesh retains quads. No blendshapes. With textures included, PBR material rendering depends on your application’s MTL support.

MetaHuman ZIP

A .zip (application/zip) for MetaHuman Creator → Conform from Template. It contains head.fbx and, with textures enabled, texture/Head_Color.*. A PBR head also includes Head_Normal.* and Head_SRMF.png; Raw includes only the color map. SRMF packs specular, roughness, metallic and fuzz into RGBA for Unreal materials.

This is a head template, without eyes, teeth or blendshapes; it is not a complete rigged MetaHuman. The FBX inside this archive is distinct from the camera scene exported by Studio.

Normal maps, axes and scale

Export Tangent-space normal maps
GLB and OBJ OpenGL (+Y)
MetaHuman ZIP DirectX (−Y), for Unreal

When transferring a normal map between these conventions, invert its green channel (G′ = 1 − G, or 255 − G for 8-bit data). Do not flip it when the destination already uses the file’s convention. Read normal, roughness, specular and SRMF maps as non-color data.

GLB and OBJ use Y up, face toward +Z. Relative proportions are preserved, but absolute physical scale is not calibrated. Camera translations use the same model units as the GLB; do not assume metres or millimetres.

Cameras

Only a completed Scan Reconstruction head has Head.cameras. Default, unfinished, failed and deleted heads have null.

cameras.items has one slot per source photo, in photos order; a photo that could not be fitted has a null slot. Each non-null camera contains:

  • photo: zero-based source photo index; image_size: [width, height] in pixels.
  • Cameras are solved on a working copy of each photo whose longer side is at most 4096 pixels. image_size, intrinsics and image coordinates refer to that copy; for a larger original, scale fx, fy, cx and cy by original width ÷ image_size[0].
  • intrinsics: fx, fy, cx, cy in image pixels, with the image origin at the top-left.
  • focal_length_mm: 35 mm equivalent focal length. focal_length_type reports what was actually used: manual, exif, estimated_common or estimated_per_image.
  • camera_to_world: a 4 × 4 row-major camera-to-world matrix, using the GLB axes. The camera looks along local −Z with local +Y up. It is already camera-to-world; do not invert it as if it were a view matrix.

For a world point, first compute p = inverse(camera_to_world) × [x,y,z,1]. With d = −p.z > 0, image coordinates are u = fx × p.x / d + cx, v = cy − fy × p.y / d. If your importer rotates or rescales the model, apply the same world transformation to its cameras.

The API returns GLB, OBJ, MetaHuman ZIP and Scan camera data. Standalone FBX camera scenes, STL and PLY are available in Studio, not from this API. API heads and Studio heads are separate; neither interface opens the other’s heads. The credit balance is shared.

Authentication and pricing

Base URL: https://api.keenface.ai/v2. Send Authorization: Bearer ak_... to API endpoints. Create a key at API keys; see pricing.

A head costs 150 credits in either mode, for any photo count and supported options. Every file is included. A failed head is free; deleting a successful head does not refund it. An account that has not bought credits yet, or was fully refunded, receives a preview GLB in place of the full files (see Get a model file). GET /v2/account and POST /v2/heads?dry_run return the current price and available balance.

The price is held before reconstruction and captured on completion; a failure releases the hold. In Default, credits are pending until the content check passes. A dry run validates the request and returns a quote without creating or storing anything, reserving credits, or guaranteeing reconstruction success.

Limits and retention

Item Limit
Image formats JPEG, PNG, WebP, HEIC, HEIF, AVIF
Each image JPEG, PNG, WebP: 64 MiB (67,108,864 bytes). HEIC, HEIF, AVIF: 20 MB (20,000,000 bytes)
Image pixels JPEG, PNG, HEIC, HEIF: at most 100 megapixels and 12,000 pixels on the longer side. WebP: at most 100 megapixels. Larger images return 413 photo_too_large at upload
AVIF Up to 14 megapixels
Multipart create body 100 MB (104,857,600 bytes), including form overhead
JSON body 64 KiB (65,536 bytes); photo IDs only
Images per head Default: 1–15; Scan: 2–15
Wait ?wait: 600 seconds; explicit wait=0–900
Model requests 10 per minute per head, shared by all variants; retry-after responses count
Unused uploaded photo / idempotency key 24 hours / 24 hours
Head, its source photos and built files Until the head is deleted (expires_at: null)
Download link 20 seconds to start; an ongoing download can finish afterwards

For a set near or above the multipart limit, upload each photo separately and create with IDs. Do not store download URLs: keep the head ID and file options, then request a fresh URL when needed. Download a file to your storage if you want to serve it to your users.

Retries and failures

Send a unique Idempotency-Key for each intended head. Within 24 hours, retrying the same request and key returns the same head without another hold. A changed request with the same key, or a repeat before the first request has finished being accepted, returns 409 idempotency_conflict.

HTTP errors use { "error": { "code", "message", "field"?, "suggestion"?, "request_id" } }. Branch on error.code; show the message and retain request_id for support. Unknown creation fields are rejected, never silently ignored, and so are unknown query parameters on POST /v2/heads, GET /v2/heads, GET /v2/heads/{id} and GET /v2/heads/{id}/model. Enum values in the query (mesh_format, texture, blendshapes) are case-insensitive.

Signal Action
Head is queued / running Keep waiting on that head ID. A wait timeout is not a failed reconstruction.
Head is failed Stop waiting and read Head.error. Create a new head with a new idempotency key if retrying.
/model: 425 head_not_ready Wait for the head to complete.
/model: 409 head_failed Stop requesting files; this head cannot complete.
/model: event: retry-after Wait data.time_sec, then repeat the same GET.
/model: 429 rate_limited Wait the Retry-After header’s seconds. All variants share the same limit.
400 invalid_request / field_not_applicable Fix or omit the named field; do not retry unchanged.
400 variant_not_available Request a different file variant.
402 insufficient_credits Top up before creating a head; files require no additional credits.
500 internal_error / 503 service_unavailable Retry with backoff; honour Retry-After when present. Reuse the create request’s idempotency key.

A 200 Head response can still contain status: failed. For Head.error.code: timeout or rate_limited, retry with the same images later; for content_rejected or reconstruction_failed, change the images; for insufficient_credits, top up first.

Quickstart

Use the complete cURL, Python or JavaScript examples under “Create a head” below. They create the head, check its terminal status, repeat the file request until a link is ready, and download immediately. Set KEENFACE_API_KEY and KEENFACE_REQUEST_ID (one unique value per intended head); reuse that request ID only for a retry of identical input within 24 hours.

For a minimal create request:

curl --fail-with-body https://api.keenface.ai/v2/heads \
  -H "Authorization: Bearer $KEENFACE_API_KEY" \
  -H "Idempotency-Key: $KEENFACE_REQUEST_ID" \
  -F photos=@front.jpg -F photos=@left.jpg -F photos=@right.jpg

To use Scan Reconstruction, supply a prepared photo set and add -F scan_reconstruction=true. To inspect the price first, append ?dry_run=true.

Base URL

All endpoints below are relative to https://api.keenface.ai.

GET /v2/heads

List heads

List your API heads, newest first, optionally filtered by status. Studio heads are not accessible. Continue with next_cursor until it is null, even if a filtered page is empty or shorter than limit. Deleted entries may remain as status records; their source photos and files are removed.

Parameters

Name In Required Type Description
cursor query no string next_cursor from the previous page.
limit query no integer Page size. With status, a page can hold fewer than limit heads and still have a next_cursor. Keep paging until next_cursor is null. Default: 20.
status query no HeadStatus Only heads in this status.

Responses

  • 200 — One page of heads
    • data (array of Head, required)
    • next_cursor (string | null, required) — Pass it as cursor to get the next page. It is null on the last page.
  • 401 — Missing or invalid API key (unauthorized)
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 403 — The account cannot use API v2 yet, or the requested option is not available right now (feature_unavailable). Any endpoint can return this. POST /v2/heads also answers 403 legal_acceptance_required while the account must accept updated legal documents for that create mode, and phone_verification_required while an account with only free credits has not verified a phone number in Studio. GET /v2/heads/{id}/model answers 403 downloads_locked for mesh_format=obj or metahuman while the account has not bought credits (or was fully refunded); glb returns a preview file.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 500 — Unexpected server error (internal_error). Retry with backoff; preserve the create request’s Idempotency-Key. Quote request_id to support if the error persists.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 503 — A dependency is temporarily unavailable (service_unavailable). Wait Retry-After seconds. For a create retry, reuse the same Idempotency-Key and input to avoid duplicate work.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.

POST /v2/heads

Create a head

Create one head from images of one person, for 150 credits with every supported file included. Select the image mode independently of how the files are uploaded.

  • Multipart: repeated photos file parts or text ph_… IDs, in order; files and IDs can be mixed. Other options are individual form fields. Each image is at most 64 MiB (20 MB for HEIC, HEIF and AVIF); the body is at most 100 MB including overhead.
  • JSON: photos is an ordered array of IDs from POST /v2/photos. No image URLs or base64 input. Maximum JSON body: 64 KiB.

Default: omit scan_reconstruction or send false; 1–15 everyday photos or references. Omit all three Scan-only fields: texture, cleanup, focal_length.

Scan Reconstruction: send true; 2–15 photos from a consistent capture session, as described under Choose a mode. Defaults are texture: pbr, cleanup: true, focal_length: auto. With texture: raw, omit cleanup entirely. Unknown fields return 400 invalid_request; inapplicable fields return 400 field_not_applicable.

Response: without wait, or with wait=0, returns 202 with the Head immediately. With a positive wait, returns 200 with the final or current Head. Always check status: 200 can mean failed, or still queued / running when the wait expires. Save id before requesting files.

Credits: validation precedes any hold. Scan holds the price on acceptance; Default holds it after the content check (credits.state: pending until then). Completion captures the hold; failure releases it. If the balance becomes insufficient before the hold, the Head can fail with insufficient_credits.

Safe retries: reuse the same Idempotency-Key and input within 24 hours to recover the existing head without another charge. An identical retry has its own wait setting. If the first request is still being accepted, 409 idempotency_conflict means retry shortly with that same key. A different input with the same key also conflicts; use a new key for a genuinely new head.

Dry run: dry_run=true validates and quotes without storing images, consuming photo IDs, creating a head, holding credits or charging. It does not test reconstruction quality. Returns 200 HeadPreview even when the available balance is insufficient (credits.sufficient: false).

Parameters

Name In Required Type Description
wait query no integer Wait for a terminal Head state for up to this many whole seconds. Bare ?wait means 600; maximum 900. Omit or use 0 to return immediately. POST with wait=0 returns 202; positive waits return 200 even if the head fails or the wait expires. Read status before proceeding. Headers arrive immediately; whitespace every 15 seconds keeps the connection alive until the Head JSON is sent. JSON parsers ignore this whitespace. Set client timeouts above the wait. For many simultaneous jobs, use events or webhooks instead of holding a connection per wait.
Idempotency-Key header no string Any unique string up to 255 characters, such as a UUID. A repeat of the same request with the same key within 24 hours returns the head the first request created and holds nothing more. Keys are per account. See Retries under POST /v2/heads.
dry_run query no boolean Validate and quote only. ?dry_run or ?dry_run=true returns 200 HeadPreview without creating, storing or charging anything. A quote is not a successful reconstruction. Default: false.

Request body (multipart/form-data)

Multipart input: repeat the photos field once per image, in order. Each part is a file or a text photo ID; both may be mixed. Other fields are sent once. Boolean fields are the strings true or false on the wire. Maximum total body: 104,857,600 bytes, including multipart overhead. The same mode restrictions as JSON apply.

  • photos (array of object, required) — One image of the person to reconstruct. JPEG, PNG or WebP of at most 67,108,864 bytes, or HEIC, HEIF or AVIF of at most 20,000,000 bytes. At most 100 megapixels and 12,000 pixels on the longer side (WebP: 100 megapixels only; AVIF: 14 megapixels). Repeat the photos part in source-photo order. Default: 1–15; Scan: 2–15. File parts carry image bytes; text parts carry ph_… IDs.
  • scan_reconstruction (boolean, optional) — false: everyday photos or downloaded references of the same person. true: a consistent multi-angle capture set with a still, neutral face, clear views and even lighting. See Choose a mode for the full input requirements.
  • texture (string (pbr, raw), optional) — Scan only. pbr: 4K skin base color, normal, roughness and specular; raw: photo-projected base color only, retaining lighting and possible gaps. This selects map content, not the jpg/png encoding used when downloading. Omit in Default.
  • cleanup (boolean, optional) — Scan with PBR only. true fills texture gaps, removes hair from the texture and generates eyes; false retains photographed hair, gaps and eyes. Omit in Default and with texture: raw. Sending either true or false in those cases returns 400 field_not_applicable.
  • focal_length (string, optional) — Scan Reconstruction only. All manual values are 35 mm equivalent millimetres, 1–2000. auto (default): estimate per photo; use EXIF when every photo supplies it. auto_common: one estimate for the set; all images must have identical pixel dimensions, otherwise reconstruction can fail. A number, e.g. 50: the same focal length for every photo. An array, e.g. [50,35,70]: one value per photo in photos order. Its length must equal the photo count or the API returns 400 invalid_request, field: focal_length. The supplied representation is preserved in Head.settings; solved values appear in Head.cameras. In this form send auto, auto_common, one number (50), or comma-separated values (50,35,70), not a JSON array string.
  • webhook_url (string, optional) — Public HTTPS URL that receives a POST on completion or failure. No embedded credentials, localhost or private addresses. See the headFinished callback for the payload, signature and retry policy.
  • webhook_secret (string, optional) — Optional shared secret for HMAC-SHA256 webhook signatures. Requires webhook_url. The value is not returned in the Head.

Request body (application/json)

  • photos (array of PhotoId, required) — Photo IDs in source-photo order, each used once. All images must depict the same person. Default: 1–15; Scan Reconstruction: 2–15. Upload image files first with POST /v2/photos. Image URLs and base64 data are not accepted.
  • scan_reconstruction (boolean, optional) — false: everyday photos or downloaded references of the same person. true: a consistent multi-angle capture set with a still, neutral face, clear views and even lighting. See Choose a mode for the full input requirements.
  • texture (string (pbr, raw), optional) — Scan only. pbr: 4K skin base color, normal, roughness and specular; raw: photo-projected base color only, retaining lighting and possible gaps. This selects map content, not the jpg/png encoding used when downloading. Omit in Default.
  • cleanup (boolean, optional) — Scan with PBR only. true fills texture gaps, removes hair from the texture and generates eyes; false retains photographed hair, gaps and eyes. Omit in Default and with texture: raw. Sending either true or false in those cases returns 400 field_not_applicable.
  • focal_length (FocalLength, optional) — Scan Reconstruction only. All manual values are 35 mm equivalent millimetres, 1–2000. auto (default): estimate per photo; use EXIF when every photo supplies it. auto_common: one estimate for the set; all images must have identical pixel dimensions, otherwise reconstruction can fail. A number, e.g. 50: the same focal length for every photo. An array, e.g. [50,35,70]: one value per photo in photos order. Its length must equal the photo count or the API returns 400 invalid_request, field: focal_length. The supplied representation is preserved in Head.settings; solved values appear in Head.cameras.
  • webhook_url (string, optional) — Public HTTPS URL that receives a POST on completion or failure. No embedded credentials, localhost or private addresses. See the headFinished callback for the payload, signature and retry policy.
  • webhook_secret (string, optional) — Optional shared secret for HMAC-SHA256 webhook signatures. Requires webhook_url. The value is not returned in the Head.

Responses

  • 200 — With wait, the finished head, or its current state if the wait ran out. Check status. With dry_run, a HeadPreview.
    • Head
      • id (string, required) — Identifies the head.
      • status (HeadStatus, required) — queued: accepted, not yet running. running: reconstruction in progress. completed: reconstruction succeeded; request file variants with /model. failed: final failure, see error; no charge. deleted: data and files removed. A completed head does not imply any file variant has already been prepared.
      • stage (string | null (reconstructing), required) — reconstructing while running, otherwise null. Both modes expose one reconstruction stage.
      • progress (integer | null, required) — Shows the progress of the whole job in percent. It is 0 while queued, never decreases, reaches 100 when completed, and is null when failed or deleted.
      • scan_reconstruction (boolean, required) — Tells whether the head uses Scan Reconstruction.
      • settings (HeadSettings, required) — Effective creation options. Default: {}. Scan PBR: texture, cleanup and focal_length. Scan Raw: texture and focal_length, with no cleanup. Focal length preserves the supplied auto mode, number or array.
        • settings.texture (string (pbr, raw), optional)
        • settings.cleanup (boolean, optional)
        • settings.focal_length (FocalLength, optional) — Scan Reconstruction only. All manual values are 35 mm equivalent millimetres, 1–2000. auto (default): estimate per photo; use EXIF when every photo supplies it. auto_common: one estimate for the set; all images must have identical pixel dimensions, otherwise reconstruction can fail. A number, e.g. 50: the same focal length for every photo. An array, e.g. [50,35,70]: one value per photo in photos order. Its length must equal the photo count or the API returns 400 invalid_request, field: focal_length. The supplied representation is preserved in Head.settings; solved values appear in Head.cameras.
      • photo_count (integer, required) — Counts the source photos.
      • credits (object, required)
        • credits.cost (integer, required) — Head price in credits: 150, regardless of mode, photo count or options. All model files are included.
        • credits.state (string (pending, held, captured, released), required) — Tracks the hold. It is pending while a default head is in its content check, before anything is held. Then it is held, and finally captured when the head completes or released when it fails.
      • models (array of ModelVariant | null, required) — Files successfully built so far. null unless completed; initially [] on completion. Request any supported variant with /model to build it for free, or pass a listed variant’s options to obtain a fresh download URL.
      • cameras (Cameras | null, required) — Solved source-photo cameras for completed Scan Reconstruction only; null otherwise.
      • created_at (string, required) — Records when the head was created.
      • completed_at (string | null, required) — Records when the head became completed or failed. It never changes afterwards. A deleted head keeps it if the head completed. Otherwise it is null.
      • expires_at (null, required) — Stays null. Heads, model files and source photos are kept until DELETE /v2/heads/{id}.
      • error (object | null, required) — Explains why the head failed. It is null otherwise.
        • error.code (string (content_rejected, rate_limited, insufficient_credits, reconstruction_failed, timeout), required) — Stable failure code. content_rejected: choose other images (Default only). rate_limited: wait, then create a new head with the same images (Default only). insufficient_credits: top up. reconstruction_failed: use clearer, more consistent photos. timeout: retry later with the same photos. A failed head is final and free; retrying reconstruction requires a new head and a new idempotency key.
        • error.message (string, required) — Explains the failure, for humans.
    • HeadPreview
      • dry_run (boolean (true), required) — Marks a preview, so it is always true.
      • scan_reconstruction (boolean, required) — Tells whether the head would use Scan Reconstruction.
      • settings (HeadSettings, required) — Effective creation options. Default: {}. Scan PBR: texture, cleanup and focal_length. Scan Raw: texture and focal_length, with no cleanup. Focal length preserves the supplied auto mode, number or array.
        • settings.texture (string (pbr, raw), optional)
        • settings.cleanup (boolean, optional)
        • settings.focal_length (FocalLength, optional) — Scan Reconstruction only. All manual values are 35 mm equivalent millimetres, 1–2000. auto (default): estimate per photo; use EXIF when every photo supplies it. auto_common: one estimate for the set; all images must have identical pixel dimensions, otherwise reconstruction can fail. A number, e.g. 50: the same focal length for every photo. An array, e.g. [50,35,70]: one value per photo in photos order. Its length must equal the photo count or the API returns 400 invalid_request, field: focal_length. The supplied representation is preserved in Head.settings; solved values appear in Head.cameras.
      • photo_count (integer, required) — Counts the photos the head would use.
      • credits (object, required)
        • credits.cost (integer, required) — Prices the head, in credits. The head would hold this amount and charge it once completed.
        • credits.balance (integer, required) — Shows your available balance now.
        • credits.sufficient (boolean, required) — Tells whether the balance covers cost right now.
  • 202 — Without wait. The head is accepted. With Scan Reconstruction its credits are held. In the default they are held after the content check.
    • id (string, required) — Identifies the head.
    • status (HeadStatus, required) — queued: accepted, not yet running. running: reconstruction in progress. completed: reconstruction succeeded; request file variants with /model. failed: final failure, see error; no charge. deleted: data and files removed. A completed head does not imply any file variant has already been prepared.
    • stage (string | null (reconstructing), required) — reconstructing while running, otherwise null. Both modes expose one reconstruction stage.
    • progress (integer | null, required) — Shows the progress of the whole job in percent. It is 0 while queued, never decreases, reaches 100 when completed, and is null when failed or deleted.
    • scan_reconstruction (boolean, required) — Tells whether the head uses Scan Reconstruction.
    • settings (HeadSettings, required) — Effective creation options. Default: {}. Scan PBR: texture, cleanup and focal_length. Scan Raw: texture and focal_length, with no cleanup. Focal length preserves the supplied auto mode, number or array.
      • settings.texture (string (pbr, raw), optional)
      • settings.cleanup (boolean, optional)
      • settings.focal_length (FocalLength, optional) — Scan Reconstruction only. All manual values are 35 mm equivalent millimetres, 1–2000. auto (default): estimate per photo; use EXIF when every photo supplies it. auto_common: one estimate for the set; all images must have identical pixel dimensions, otherwise reconstruction can fail. A number, e.g. 50: the same focal length for every photo. An array, e.g. [50,35,70]: one value per photo in photos order. Its length must equal the photo count or the API returns 400 invalid_request, field: focal_length. The supplied representation is preserved in Head.settings; solved values appear in Head.cameras.
    • photo_count (integer, required) — Counts the source photos.
    • credits (object, required)
      • credits.cost (integer, required) — Head price in credits: 150, regardless of mode, photo count or options. All model files are included.
      • credits.state (string (pending, held, captured, released), required) — Tracks the hold. It is pending while a default head is in its content check, before anything is held. Then it is held, and finally captured when the head completes or released when it fails.
    • models (array of ModelVariant | null, required) — Files successfully built so far. null unless completed; initially [] on completion. Request any supported variant with /model to build it for free, or pass a listed variant’s options to obtain a fresh download URL.
    • cameras (Cameras | null, required) — Solved source-photo cameras for completed Scan Reconstruction only; null otherwise.
    • created_at (string, required) — Records when the head was created.
    • completed_at (string | null, required) — Records when the head became completed or failed. It never changes afterwards. A deleted head keeps it if the head completed. Otherwise it is null.
    • expires_at (null, required) — Stays null. Heads, model files and source photos are kept until DELETE /v2/heads/{id}.
    • error (object | null, required) — Explains why the head failed. It is null otherwise.
      • error.code (string (content_rejected, rate_limited, insufficient_credits, reconstruction_failed, timeout), required) — Stable failure code. content_rejected: choose other images (Default only). rate_limited: wait, then create a new head with the same images (Default only). insufficient_credits: top up. reconstruction_failed: use clearer, more consistent photos. timeout: retry later with the same photos. A failed head is final and free; retrying reconstruction requires a new head and a new idempotency key.
      • error.message (string, required) — Explains the failure, for humans.
  • 400 — Invalid or unknown input, duplicate photo ID, or missing/already-used photo ID (invalid_request); a Scan-only option in Default or cleanup with Raw (field_not_applicable); invalid photo count (too_few_photos / too_many_photos); expired photo ID (photo_expired). Read field and suggestion.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 401 — Missing or invalid API key (unauthorized)
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 402 — Not enough credits (insufficient_credits)
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 403 — The requested mode is not available right now (feature_unavailable), or the account must accept updated legal documents before creating heads in this mode (legal_acceptance_required). The second names the accept URL in error.message; a dry_run or an Idempotency-Key repeat answers the same. Accept there and retry. Other requests on the account keep working. An account that has never made a head and never bought credits gets phone_verification_required until it verifies a phone number in Studio. Free credits need a verified phone; paid credits do not.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 409 — The Idempotency-Key belongs to a request still being accepted, or to a different request (idempotency_conflict)
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 413 — A photo larger than 64 MiB (20 MB for HEIC, HEIF and AVIF), over 100 megapixels, over 12,000 pixels on its longer side, or an AVIF over 14 megapixels (photo_too_large); downscale or re-encode it, since POST /v2/photos has the same limits. A request body over 100 MB never reaches the API; Cloudflare's edge refuses it with its own 413 page, not a JSON error. Keep a multipart create under 100 MB, or upload the photos one at a time with POST /v2/photos and send their IDs.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 415 — Unsupported image format or request Content-Type (unsupported_media_type). Use supported image bytes in multipart/form-data, or photo IDs in application/json.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 429 — More than 30 create or dry_run requests per minute for this API key (rate_limited). The request was not read; send it again after Retry-After.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 500 — Unexpected server error (internal_error). Retry with backoff; preserve the create request’s Idempotency-Key. Quote request_id to support if the error persists.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 503 — A dependency is temporarily unavailable (service_unavailable). Wait Retry-After seconds. For a create retry, reuse the same Idempotency-Key and input to avoid duplicate work.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.

GET /v2/heads/{id}

Get a head

Read the current Head. With wait, hold the response until a terminal state or the time limit. HTTP 200 describes a successful status lookup, not necessarily a successful reconstruction: inspect status and error. Only completed heads can produce files. Cameras are populated only for completed Scan Reconstruction heads. A deleted head may be returned as a status record; it has no downloadable files.

Parameters

Name In Required Type Description
id path yes string Head id, as returned by POST /v2/heads.
wait query no integer Wait for a terminal Head state for up to this many whole seconds. Bare ?wait means 600; maximum 900. Omit or use 0 to return immediately. POST with wait=0 returns 202; positive waits return 200 even if the head fails or the wait expires. Read status before proceeding. Headers arrive immediately; whitespace every 15 seconds keeps the connection alive until the Head JSON is sent. JSON parsers ignore this whitespace. Set client timeouts above the wait. For many simultaneous jobs, use events or webhooks instead of holding a connection per wait.

Responses

  • 200 — The head
    • id (string, required) — Identifies the head.
    • status (HeadStatus, required) — queued: accepted, not yet running. running: reconstruction in progress. completed: reconstruction succeeded; request file variants with /model. failed: final failure, see error; no charge. deleted: data and files removed. A completed head does not imply any file variant has already been prepared.
    • stage (string | null (reconstructing), required) — reconstructing while running, otherwise null. Both modes expose one reconstruction stage.
    • progress (integer | null, required) — Shows the progress of the whole job in percent. It is 0 while queued, never decreases, reaches 100 when completed, and is null when failed or deleted.
    • scan_reconstruction (boolean, required) — Tells whether the head uses Scan Reconstruction.
    • settings (HeadSettings, required) — Effective creation options. Default: {}. Scan PBR: texture, cleanup and focal_length. Scan Raw: texture and focal_length, with no cleanup. Focal length preserves the supplied auto mode, number or array.
      • settings.texture (string (pbr, raw), optional)
      • settings.cleanup (boolean, optional)
      • settings.focal_length (FocalLength, optional) — Scan Reconstruction only. All manual values are 35 mm equivalent millimetres, 1–2000. auto (default): estimate per photo; use EXIF when every photo supplies it. auto_common: one estimate for the set; all images must have identical pixel dimensions, otherwise reconstruction can fail. A number, e.g. 50: the same focal length for every photo. An array, e.g. [50,35,70]: one value per photo in photos order. Its length must equal the photo count or the API returns 400 invalid_request, field: focal_length. The supplied representation is preserved in Head.settings; solved values appear in Head.cameras.
    • photo_count (integer, required) — Counts the source photos.
    • credits (object, required)
      • credits.cost (integer, required) — Head price in credits: 150, regardless of mode, photo count or options. All model files are included.
      • credits.state (string (pending, held, captured, released), required) — Tracks the hold. It is pending while a default head is in its content check, before anything is held. Then it is held, and finally captured when the head completes or released when it fails.
    • models (array of ModelVariant | null, required) — Files successfully built so far. null unless completed; initially [] on completion. Request any supported variant with /model to build it for free, or pass a listed variant’s options to obtain a fresh download URL.
    • cameras (Cameras | null, required) — Solved source-photo cameras for completed Scan Reconstruction only; null otherwise.
    • created_at (string, required) — Records when the head was created.
    • completed_at (string | null, required) — Records when the head became completed or failed. It never changes afterwards. A deleted head keeps it if the head completed. Otherwise it is null.
    • expires_at (null, required) — Stays null. Heads, model files and source photos are kept until DELETE /v2/heads/{id}.
    • error (object | null, required) — Explains why the head failed. It is null otherwise.
      • error.code (string (content_rejected, rate_limited, insufficient_credits, reconstruction_failed, timeout), required) — Stable failure code. content_rejected: choose other images (Default only). rate_limited: wait, then create a new head with the same images (Default only). insufficient_credits: top up. reconstruction_failed: use clearer, more consistent photos. timeout: retry later with the same photos. A failed head is final and free; retrying reconstruction requires a new head and a new idempotency key.
      • error.message (string, required) — Explains the failure, for humans.
  • 401 — Missing or invalid API key (unauthorized)
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 403 — The account cannot use API v2 yet, or the requested option is not available right now (feature_unavailable). Any endpoint can return this. POST /v2/heads also answers 403 legal_acceptance_required while the account must accept updated legal documents for that create mode, and phone_verification_required while an account with only free credits has not verified a phone number in Studio. GET /v2/heads/{id}/model answers 403 downloads_locked for mesh_format=obj or metahuman while the account has not bought credits (or was fully refunded); glb returns a preview file.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 404 — No accessible head or unused photo with this ID on your account (not_found).
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 500 — Unexpected server error (internal_error). Retry with backoff; preserve the create request’s Idempotency-Key. Quote request_id to support if the error persists.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 503 — A dependency is temporarily unavailable (service_unavailable). Wait Retry-After seconds. For a create retry, reuse the same Idempotency-Key and input to avoid duplicate work.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.

DELETE /v2/heads/{id}

Delete a head

Delete the head’s source photos and model files, including data retained for building new file variants. A queued or running head cannot be deleted (409 head_running). This is not a cancellation endpoint. Deletion does not refund a completed head. A deleted status record may remain in head listings.

Parameters

Name In Required Type Description
id path yes string Head id, as returned by POST /v2/heads.

Responses

  • 204 — Deleted
  • 401 — Missing or invalid API key (unauthorized)
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 403 — The account cannot use API v2 yet, or the requested option is not available right now (feature_unavailable). Any endpoint can return this. POST /v2/heads also answers 403 legal_acceptance_required while the account must accept updated legal documents for that create mode, and phone_verification_required while an account with only free credits has not verified a phone number in Studio. GET /v2/heads/{id}/model answers 403 downloads_locked for mesh_format=obj or metahuman while the account has not bought credits (or was fully refunded); glb returns a preview file.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 404 — No accessible head or unused photo with this ID on your account (not_found).
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 409 — Head is still running (head_running)
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 500 — Unexpected server error (internal_error). Retry with backoff; preserve the create request’s Idempotency-Key. Quote request_id to support if the error persists.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 503 — A dependency is temporarily unavailable (service_unavailable). Wait Retry-After seconds. For a create retry, reuse the same Idempotency-Key and input to avoid duplicate work.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.

GET /v2/heads/{id}/model

Get a model file

Request one file of a completed head. All files and repeat downloads are included in the head price; this endpoint never needs additional credits.

The response is HTTP 200 JSON with one of two event values:

  • retry-after: preparation is in progress. Wait data.time_sec seconds and repeat the same request.
  • redirect: fetch data.url immediately to download the file. This is a JSON event name, not an HTTP 3xx response.

Each variant is built on its first request (typically 20–40 seconds) and kept until the head is deleted. Later requests issue fresh links to the stored file. Head.models lists variants built so far; an empty list does not mean no variants are available.

Accounts that have not bought credits. An account that has not bought credits yet, or was fully refunded, receives a preview GLB for mesh_format=glb: no blendshapes, a reduced mesh, not for production use. The file is prepared as usual (retry-after), then data.url links to the preview. texture and blendshapes are accepted; the preview has no blendshapes. mesh_format=obj and mesh_format=metahuman answer 403 downloads_locked. The preview costs nothing. Buying credits unlocks the full files for every head, including heads you already created: request the file again.

Options: mesh_format, texture, blendshapes only. Omit all for a GLB with JPG maps and no blendshapes. blendshapes=arkit works only with GLB, in either creation mode. OBJ and MetaHuman carry no blendshapes. Unknown parameters return 400 invalid_request with field. See Model files for archive contents, map dimensions, normal-map conventions and scale.

Readiness: queued / running → 425 head_not_ready; failed → 409 head_failed; deleted / missing → 404 not_found. A failed head will never become ready.

Links: valid for 20 seconds to start downloading, without API authorization. Do not forward your API key to the signed URL. An ongoing download can finish after expiry; a new, interrupted or resumed download needs a fresh link. Store the file or the head ID and variant options, not the URL.

Retries: every variant shares the limit of 10 requests per minute per head, including preparation polls. Honour data.time_sec and, on HTTP 429, the Retry-After header. Avoid preparing many variants of the same head concurrently. Temporary file failures return 503; request again to retry preparation. 400 variant_not_available means choose a different variant.

Parameters

Name In Required Type Description
id path yes string Head id.
mesh_format query no string (glb, obj, metahuman) glb: binary model with optional embedded maps and ARKit targets; mesh names and materials depend on PBR/Raw and the texture option (see Model files). obj: ZIP with neutral.obj; neutral.mtl and texture/ are included only with jpg or png. metahuman: ZIP with a head FBX template and optional MetaHuman maps, without eyes, teeth or morphs. Default: glb.
texture query no string (jpg, png, none) Image encoding of existing maps: jpg, png, or none to omit maps. Does not select PBR/Raw. With none, an OBJ ZIP contains only neutral.obj (no MTL or texture directory). A PBR GLB retains Cornea_L and Cornea_R materials; skin, eyes and teeth have no assigned material. Thus none does not mean that every material is removed. With textures included, Raw GLB mesh/material names are absent and all four materials have metallicFactor: 1; set it to 0 in your importer for a non-metallic preview. The GLB skin specular and MetaHuman SRMF maps stay PNG. Normal maps: OpenGL in GLB/OBJ, DirectX in MetaHuman ZIP. Default: jpg.
blendshapes query no array of string (arkit) Optional 51 ARKit morph targets; GLB only. Omit or send an empty value for no morphs. tongueOut is absent. Sending arkit with obj or metahuman returns 400 invalid_request, field: blendshapes.

Responses

  • 200 — A download link, or how long to wait while the file builds
    • ModelRedirect
      • event (string (redirect), required)
      • data (object, required)
        • data.url (string, required) — Links to the file. Start the download within 20 seconds.
        • data.expires_at (string, required) — Marks when url stops accepting new requests. A download already in progress still completes.
    • ModelRetryAfter
      • event (string (retry-after), required)
      • data (object, required)
        • data.time_sec (integer, required) — Seconds to wait before repeating the same /model request. Preparation is included in the head price.
  • 400 — Unknown, malformed or incompatible parameter (invalid_request), or this head cannot produce the variant (variant_not_available). Correct the request; unchanged retries will not help.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 401 — Missing or invalid API key (unauthorized)
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 403 — The account cannot use API v2 yet, or the requested option is not available right now (feature_unavailable). Any endpoint can return this. POST /v2/heads also answers 403 legal_acceptance_required while the account must accept updated legal documents for that create mode, and phone_verification_required while an account with only free credits has not verified a phone number in Studio. GET /v2/heads/{id}/model answers 403 downloads_locked for mesh_format=obj or metahuman while the account has not bought credits (or was fully refunded); glb returns a preview file.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 404 — No accessible head or unused photo with this ID on your account (not_found).
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 409 — The head failed (head_failed). Stop polling; create a new head to retry reconstruction.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 425 — The head is queued or running (head_not_ready). Wait for completed before requesting the file.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 429 — More than 10 calls per minute for this head (rate_limited)
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 500 — Unexpected server error (internal_error). Retry with backoff; preserve the create request’s Idempotency-Key. Quote request_id to support if the error persists.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 503 — Temporary preparation failure or service unavailable (service_unavailable). Repeat this file request after Retry-After; file preparation is free.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.

POST /v2/photos

Upload a photo

Upload one image ahead of head creation. Send raw image bytes with the matching image Content-Type, not a multipart form, image URL or base64 string.

The image must be JPEG, PNG or WebP up to 64 MiB (67,108,864 bytes), or HEIC, HEIF or AVIF up to 20 MB (20,000,000 bytes). The API detects the format from the file contents. EXIF orientation is applied during image processing.

The returned ph_… ID belongs to your account and expires after 24 hours unless consumed by a head. Pass it in the JSON photos array or as a text photos form part. Keep IDs in the intended source-photo order. Once used, the photo belongs to that head; upload it again for a different head.

Use this endpoint for sets that approach or exceed the 100 MB multipart limit. Uploading a photo does not create a head or charge credits.

Request body

Raw file bytes. Content-Type: image/jpeg, image/png, image/webp, image/heic, image/heif, image/avif.

Responses

  • 201 — Photo stored
    • id (PhotoId, required) — Opaque ID returned by Upload a photo; not an image URL or base64 data.
    • expires_at (string, required) — The API removes the photo at this time, unless a head uses it first.
  • 401 — Missing or invalid API key (unauthorized)
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 403 — The account cannot use API v2 yet, or the requested option is not available right now (feature_unavailable). Any endpoint can return this. POST /v2/heads also answers 403 legal_acceptance_required while the account must accept updated legal documents for that create mode, and phone_verification_required while an account with only free credits has not verified a phone number in Studio. GET /v2/heads/{id}/model answers 403 downloads_locked for mesh_format=obj or metahuman while the account has not bought credits (or was fully refunded); glb returns a preview file.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 413 — Photo larger than 64 MiB, a HEIC, HEIF or AVIF photo larger than 20 MB, a photo over 100 megapixels or 12,000 pixels on its longer side, or an AVIF over 14 megapixels (photo_too_large). A body over 100 MB gets Cloudflare's own 413 page before the API runs, not JSON.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 415 — Not a supported image type (unsupported_media_type)
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 500 — Unexpected server error (internal_error). Retry with backoff; preserve the create request’s Idempotency-Key. Quote request_id to support if the error persists.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 503 — A dependency is temporarily unavailable (service_unavailable). Wait Retry-After seconds. For a create retry, reuse the same Idempotency-Key and input to avoid duplicate work.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.

DELETE /v2/photos/{id}

Delete an unused photo

Deletes a photo that no head has used. A photo used by a head belongs to that head. DELETE /v2/heads/{id} removes it with the head.

Parameters

Name In Required Type Description
id path yes PhotoId Photo id from POST /v2/photos.

Responses

  • 204 — Deleted
  • 401 — Missing or invalid API key (unauthorized)
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 403 — The account cannot use API v2 yet, or the requested option is not available right now (feature_unavailable). Any endpoint can return this. POST /v2/heads also answers 403 legal_acceptance_required while the account must accept updated legal documents for that create mode, and phone_verification_required while an account with only free credits has not verified a phone number in Studio. GET /v2/heads/{id}/model answers 403 downloads_locked for mesh_format=obj or metahuman while the account has not bought credits (or was fully refunded); glb returns a preview file.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 404 — No such unused photo on this account (not_found)
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 500 — Unexpected server error (internal_error). Retry with backoff; preserve the create request’s Idempotency-Key. Quote request_id to support if the error persists.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 503 — A dependency is temporarily unavailable (service_unavailable). Wait Retry-After seconds. For a create retry, reuse the same Idempotency-Key and input to avoid duplicate work.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.

GET /v2/heads/{id}/events

Stream head updates

Server-sent events (SSE), authenticated with your API Bearer token. The first event: head contains the current full Head JSON; later events report changes in status, stage, progress or credit state. A : ping comment every 15 seconds keeps the connection active.

The stream closes on completed, failed or deleted. Stop reconnecting on those terminal states. On a connection drop before a final state, reconnect with Last-Event-ID when available; the server sends the current snapshot again, not a guaranteed replay of historical events.

Native browser EventSource does not support a custom Authorization header. Use an authenticated fetch-based SSE client or your own server; never put the API key in the URL. One stream follows one head.

Parameters

Name In Required Type Description
id path yes string Head id.
Last-Event-ID header no string Last received event id when reconnecting. Current state is sent on connection; historical replay is not guaranteed.

Responses

  • 200 — Event stream of Head snapshots
  • 401 — Missing or invalid API key (unauthorized)
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 403 — The account cannot use API v2 yet, or the requested option is not available right now (feature_unavailable). Any endpoint can return this. POST /v2/heads also answers 403 legal_acceptance_required while the account must accept updated legal documents for that create mode, and phone_verification_required while an account with only free credits has not verified a phone number in Studio. GET /v2/heads/{id}/model answers 403 downloads_locked for mesh_format=obj or metahuman while the account has not bought credits (or was fully refunded); glb returns a preview file.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 404 — No accessible head or unused photo with this ID on your account (not_found).
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 500 — Unexpected server error (internal_error). Retry with backoff; preserve the create request’s Idempotency-Key. Quote request_id to support if the error persists.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 503 — A dependency is temporarily unavailable (service_unavailable). Wait Retry-After seconds. For a create retry, reuse the same Idempotency-Key and input to avoid duplicate work.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.

GET /v2/account

Get balance and prices

Read the current price list and the balance shared with Studio. credits is available to spend, with held_credits already excluded; do not subtract it again. A successful head costs 150 credits, and every model file is included. Use a dry run to validate and quote a particular create request.

Responses

  • 200 — Account
    • credits (integer, required) — Shows the available balance, held credits excluded.
    • held_credits (integer, required) — Counts the credits reserved by heads in progress.
    • prices (object, required) — Current price list in credits. All supported files are included in each head.
      • prices.head (integer, required) — Cost of one successful head in either mode.
      • prices.file (integer, required) — No additional charge for any supported file or repeated download.
  • 401 — Missing or invalid API key (unauthorized)
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 403 — The account cannot use API v2 yet, or the requested option is not available right now (feature_unavailable). Any endpoint can return this. POST /v2/heads also answers 403 legal_acceptance_required while the account must accept updated legal documents for that create mode, and phone_verification_required while an account with only free credits has not verified a phone number in Studio. GET /v2/heads/{id}/model answers 403 downloads_locked for mesh_format=obj or metahuman while the account has not bought credits (or was fully refunded); glb returns a preview file.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 500 — Unexpected server error (internal_error). Retry with backoff; preserve the create request’s Idempotency-Key. Quote request_id to support if the error persists.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.
  • 503 — A dependency is temporarily unavailable (service_unavailable). Wait Retry-After seconds. For a create retry, reuse the same Idempotency-Key and input to avoid duplicate work.
    • error (object, required)
      • error.code (string (invalid_request, field_not_applicable, too_few_photos, too_many_photos, photo_expired, photo_too_large, unsupported_media_type, feature_unavailable, legal_acceptance_required, phone_verification_required, downloads_locked, insufficient_credits, idempotency_conflict, head_running, head_not_ready, variant_not_available, rate_limited, not_found, unauthorized, internal_error, service_unavailable, head_failed), required) — Names the failure. The value is stable, so your code can match on it.
      • error.message (string, required) — Explains what went wrong, for humans.
      • error.suggestion (string, optional) — Suggests a next step when there is one, for example which files a head has or how to send fewer bytes.
      • error.field (string, optional) — Names the request field the error is about, when there is one.
      • error.request_id (string, required) — Identifies the request. Quote it when contacting support.

Product

  • Studio
  • Pricing
  • Documentation
  • Capture guidelines

Features

  • MetaHuman topology
  • Production-ready texture
  • Scan Reconstruction
  • ARKit blendshapes

Solutions

  • MetaHumans
  • 3D Character Artists
  • Medical & Healthcare Visualisation
  • 3D Scanner Integration
  • In-Game Character Customisation
  • Avatar Creation
  • E-Commerce & Virtual Try-on

Company

  • Contact Sales
  • Terms of Service
  • Privacy Policy
  • Subprocessors
  • Affiliate Terms
© 2026 KeenFace
Terms and Policies