API reference · Vircasi

API reference · v1

Vircasi API

本页面为英文开发者文档。

Everything the studio does, from your own code: start a fictional character, sculpt its 3D head with sliders or in plain words, then get realistic photos of the same person from every angle and in any role.

The API is organised around REST. It accepts JSON bodies, answers with JSON, uses standard HTTP status codes and authenticates with API keys. Slow work (image generation) runs as jobs you poll. The same API is available to AI agents over MCP and inside ComfyUI.

Free to explore
Library faces, catalogues and every sculpt render cost nothing.
$0.05 an image
Only images that are made and delivered are charged.
One balance
The same prepaid credits as the studio; no subscription.

Base URL

https://vircasi.com/v1

Authentication

Every request needs an API key, sent as a bearer token in the Authorization header. Make and revoke keys on your account page; a key is shown once, when you make it.

Keys spend your account's credits. Each key has its own daily spending cap, set when you make it, so a leaked key or a runaway script cannot drain your balance. Keep keys on the server side: never put them in a web page or in an app you ship.

Requests without a valid key get 401 invalid_api_key.

Authenticated request

curl "https://vircasi.com/v1/account" \
  -H "Authorization: Bearer $VIRCASI_KEY"

Quickstart

From a key to a cast character in six calls. Set your key first: export VIRCASI_KEY=vk_live_…

1. Check your key

Make a key on your account page and keep it in an environment variable. This call is free and shows your balance.

curl "https://vircasi.com/v1/account" \
  -H "Authorization: Bearer $VIRCASI_KEY"

2. Start a character

Pick a library face (free and instant), or generate a new one with POST /characters and generate.

curl -X POST "https://vircasi.com/v1/characters" \
  -H "Authorization: Bearer $VIRCASI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"face_id":"gal_0118b203fb"}'

3. Sculpt the 3D head

Change the face with sliders or words. Each call returns renders, free: look at them before you pay for photos.

curl -X POST "https://vircasi.com/v1/characters/chr_d334f85b0e/sculpt" \
  -H "Authorization: Bearer $VIRCASI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sliders":{"jaw_width":0.8,"cheekbone_projection":1}}'

4. Make the face photos

Realistic photos at front, 45° and 90° ($0.15). This starts a job: poll it until it is done.

curl -X POST "https://vircasi.com/v1/characters/chr_d334f85b0e/photos" \
  -H "Authorization: Bearer $VIRCASI_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

5. Poll the job

Every 2–3 seconds until status is done (with the photos) or error (not charged).

curl "https://vircasi.com/v1/jobs/job_1651bccd50" \
  -H "Authorization: Bearer $VIRCASI_KEY"

6. Cast it in a role

A full-body look at three angles ($0.15): a ready-made look_id or a role in your words.

curl -X POST "https://vircasi.com/v1/characters/chr_d334f85b0e/looks" \
  -H "Authorization: Bearer $VIRCASI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body_type":"lean_athletic","role":"a 1980s Hong Kong detective"}'

Pricing and billing

Call	Images	Price
Sculpt, renders, catalogues, characters, jobs	—	Free
Start face (front + side, 3D head included)	2	$0.10
Face photos (front, 45°, 90°)	3	$0.15
Full-body look (front, 45°, 90°)	3	$0.15

Every generated image is $0.05 (half a credit; 1 credit = $0.10), clean and full resolution.
A job is charged when it starts. Images that are not delivered are refunded when it ends, and a failed job costs nothing.
The API, MCP and ComfyUI spend the same prepaid credits as the studio. Buy credits on the pricing page; they never expire.
Photos made through the API count as paid in the studio, so downloading them there is free.

Characters

A character is one fictional person. Its life follows the studio's steps:

Start face: a library face, or a generated front and side photo.
3D head: built from the start face (ready at once for library faces, about 30 s for generated ones).
Sculpt: slider values change the head and renders show the result. The sliders are kept with the character.
Face photos: the sculpted head at front, 45° and 90° as realistic photos.
Looks: the same person full-body, in as many roles as you like.

Characters made through the API appear in your studio too, and studio characters are available to the API.

The character object

{
  "character": {
    "id": "chr_d334f85b0e",
    "created": "2026-11-05T03:01:14+0000",
    "description": "about 24 years old, a man, of white appearance",
    "gender": "male",
    "age": 24,
    "look": "white",
    "hairstyle": "low_taper_fade",
    "head": "done",
    "sliders": {
      "jaw_width": 0.8,
      "cheekbone_projection": 1
    },
    "start_photos": {
      "face_front": "https://vircasi.com/v1/files/characters/chr_d334f85b0e/face_front.jpg?exp=1793936254&sig=2e15517f1064136a…",
      "face_side": "https://vircasi.com/v1/files/characters/chr_d334f85b0e/face_side.jpg?exp=1793936254&sig=2e15517f1064136a…"
    },
    "face_photos": {
      "45": "https://vircasi.com/v1/files/…/45.jpg?exp=1793936254&sig=2e15517f1064136a…",
      "90": "https://vircasi.com/v1/files/…/90.jpg?exp=1793936254&sig=2e15517f1064136a…",
      "front": "https://vircasi.com/v1/files/characters/chr_d334f85b0e/previews/prev_9a1c/front.jpg?exp=1793936254&sig=2e15517f1064136a…"
    },
    "looks": [
      {
        "id": "look_dc43b8b548",
        "title": "Road-Worn Wanderer",
        "body_type": "lean_athletic",
        "photos": {
          "45": "https://vircasi.com/v1/files/…/45.jpg?exp=1793936254&sig=2e15517f1064136a…",
          "90": "https://vircasi.com/v1/files/…/90.jpg?exp=1793936254&sig=2e15517f1064136a…",
          "front": "https://vircasi.com/v1/files/…/final_c40e/front.jpg?exp=1793936254&sig=2e15517f1064136a…"
        }
      }
    ]
  }
}

Jobs

Generating a start face, face photos or a look takes 45–90 seconds, so these calls answer at once with a job. PollGET /v1/jobs/{id} every 2–3 seconds: status is running, then done with a result, or error with an error message (and no charge).

One job runs at a time per account; starting another while one runs gives 409 job_running. Jobs are kept for an hour.

The job object

{
  "id": "job_1651bccd50",
  "status": "done",
  "seconds": 49,
  "error": null,
  "result": {
    "character_id": "chr_d334f85b0e",
    "photos": {
      "45": "https://vircasi.com/v1/files/…/45.jpg?exp=1793936254&sig=2e15517f1064136a…",
      "90": "https://vircasi.com/v1/files/…/90.jpg?exp=1793936254&sig=2e15517f1064136a…",
      "front": "https://vircasi.com/v1/files/…/front.jpg?exp=1793936254&sig=2e15517f1064136a…"
    },
    "images": 3,
    "charged_credits": 1.5,
    "charged_usd": 0.15
  }
}

Images and links

Images are returned as HTTPS links signed for 24 hours. They work without your key, so you can hand them to a browser, a video model or a teammate. Download the files you keep; GET /v1/characters/{id} always gives fresh links.

Photos are 1024 × 1024 JPEG. Sculpt renders are 1024 × 1024 PNG on a plain light background.

Errors

Errors use HTTP status codes and always have the same body, {"detail": {"error": code, "message": text}}, with extra fields for some codes.

Status	error	Meaning
400	bad_request	The request cannot be done as asked, e.g. an unknown hairstyle.
401	invalid_api_key	No key, a wrong key or a revoked key.
402	not_enough_credits	The balance is too low for this call; the answer has needed_usd, balance_usd and top_up_url.
402	daily_cap_reached	This key reached its daily spending cap (resets at 00:00 UTC).
404	not_found	No such character, look, face or job for your account.
409	job_running	Your account already has a job running; wait for it to finish.
409	head_not_ready	The character's 3D head is still being built.
422	invalid_request	A field is missing or invalid; fields lists each problem.
429	rate_limited	Too many calls; retry after the Retry-After header (seconds).
503	service_unavailable	Image generation is paused for a moment; try again later.

Error answer

{
  "detail": {
    "error": "not_enough_credits",
    "needed": 1.5,
    "balance_credits": 1,
    "needed_usd": 0.15,
    "balance_usd": 0.1,
    "top_up_url": "https://vircasi.com/pricing"
  }
}

Rate limits and caps

Sculpt: 120 calls an hour per account.
Image generation: 300 calls an hour per account, one job at a time.
Daily cap per key: the dollar amount you set when you made the key (UTC days).

Over a limit you get 429 rate_limited with a Retry-After header in seconds. For higher limits, write to [email protected].

Retrieve your account

GET/accountFree

The balance this key spends, the current prices, and the key's own daily cap and spend today (UTC).

Request

curl "https://vircasi.com/v1/account" \
  -H "Authorization: Bearer $VIRCASI_KEY"

Response

{
  "email": "[email protected]",
  "balance_credits": 25,
  "balance_usd": 2.5,
  "prices_usd": {
    "per_image": 0.05,
    "start_face": 0.1,
    "photos": 0.15,
    "look": 0.15,
    "sculpt": 0
  },
  "key": {
    "id": "key_6dfb9a91bb",
    "name": "ComfyUI",
    "daily_cap_usd": 10,
    "spent_today_usd": 0.5
  }
}

List library faces

GET/facesFree

Ready-made adult faces whose 3D head is already built. Starting a character from one is free and instant.

Query parameters

genderstring: female or male
lookstring: east_asian, south_asian, black, white, latino or middle_eastern
min_age / max_ageinteger: Age range, 18 to 90
limitinteger: Up to 200; default 50
offsetinteger: For paging; default 0

Request

curl "https://vircasi.com/v1/faces?gender=male&look=white&limit=1" \
  -H "Authorization: Bearer $VIRCASI_KEY"

Response

{
  "total": 103,
  "faces": [
    {
      "id": "gal_0118b203fb",
      "gender": "male",
      "age": 24,
      "look": "white",
      "front": "https://vircasi.com/v1/files/gallery/gal_0118b203fb/face_front.jpg?exp=1793936254&sig=2e15517f1064136a…",
      "side": "https://vircasi.com/v1/files/gallery/gal_0118b203fb/face_side.jpg?exp=1793936254&sig=2e15517f1064136a…"
    }
  ]
}

List hairstyles

GET/hairstylesFree

Hairstyle and hair colour ids for generating a start face.

Query parameters

genderstring: female or male

Request

curl "https://vircasi.com/v1/hairstyles?gender=male" \
  -H "Authorization: Bearer $VIRCASI_KEY"

Response

{
  "hairstyles": [
    {
      "id": "textured_spiky",
      "gender": "male",
      "label": "Textured spikes",
      "card": "https://vircasi.com/v1/files/hairstyles/textured_spiky_front.jpg?exp=1793936254&sig=2e15517f1064136a…"
    }
  ],
  "hair_colors": [
    {
      "id": null,
      "label": "Natural (not specified)"
    },
    {
      "id": "black",
      "label": "Black"
    },
    {
      "id": "dark_brown",
      "label": "Dark brown"
    }
  ]
}

List sliders

GET/slidersFree

Every face slider of the 3D head: its name, range and what positive and negative values do. 0 is the face as in its start photo.

Request

curl "https://vircasi.com/v1/sliders" \
  -H "Authorization: Bearer $VIRCASI_KEY"

Response

{
  "sliders": [
    {
      "name": "jaw_width",
      "label": "Jaw width",
      "category": "Jaw & chin",
      "range": [
        -2,
        2
      ],
      "plus": "the jaw wider",
      "minus": "the jaw narrower"
    },
    {
      "name": "cheekbone_projection",
      "label": "Cheekbone projection",
      "category": "Overall face",
      "range": [
        -2,
        2
      ],
      "plus": "the cheekbones more prominent (further forward)",
      "minus": "the cheekbones flatter"
    }
  ]
}

List body types

GET/body-typesFree

Body types for full-body looks. Use the ones of your character's gender.

Query parameters

genderstring: female or male

Request

curl "https://vircasi.com/v1/body-types?gender=male" \
  -H "Authorization: Bearer $VIRCASI_KEY"

Response

{
  "body_types": [
    {
      "id": "lean_athletic",
      "gender": "male",
      "label": "Lean athletic",
      "card": "https://vircasi.com/v1/files/bodies/male_lean_athletic_front.jpg?exp=1793936254&sig=2e15517f1064136a…"
    }
  ]
}

List looks

GET/looksFree

Ready-made full-body looks (outfit, accessories and hair styling), grouped by genre. The answer also lists every genre.

Query parameters

genderstring: female or male
genrestring: e.g. wuxia, office, cyberpunk, fashion_korean; see genres in the answer
limit / offsetinteger: Paging; limit up to 500

Request

curl "https://vircasi.com/v1/looks?gender=male&genre=wuxia&limit=1" \
  -H "Authorization: Bearer $VIRCASI_KEY"

Response

{
  "total": 3,
  "genres": [
    "ancient_china",
    "cyberpunk",
    "fashion_korean",
    "office",
    "wuxia",
    "…"
  ],
  "looks": [
    {
      "id": "wuxia_1",
      "genre": "wuxia",
      "gender": "male",
      "title": "Road-Worn Wanderer",
      "card": "https://vircasi.com/v1/files/looks/male_adult_wuxia_1.jpg?exp=1793936254&sig=2e15517f1064136a…"
    }
  ]
}

Create a character

POST/charactersFree · $0.10

Start a character from a library face (free, ready at once) or generate a new start face from your choices: two images (front and side) for $0.10, with its 3D head built in about a minute. Generating answers with a job.

Body parameters

face_idstring: A library face. Give this or generate.
generate.genderstringrequired: female or male
generate.ageinteger: 18 to 90; default 25
generate.lookstring: east_asian, south_asian, black, white, latino, middle_eastern
generate.hairstylestring: A hairstyle id; empty lets the model choose
generate.hair_colorstring: A hair colour id
generate.descriptionstring: Anything else about the face, up to 400 characters

With face_id the answer is {"character": {…}} at once.

When the job is done, its result is {"character": {…}, "images": 2, "charged_usd": 0.1}.

Request

curl -X POST "https://vircasi.com/v1/characters" \
  -H "Authorization: Bearer $VIRCASI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"generate":{"gender":"male","age":24,"look":"white","hairstyle":"textured_spiky","description":"a calm, steady gaze"}}'

Response

{
  "job": {
    "id": "job_4c8110c20a",
    "kind": "api_start_face",
    "status": "running",
    "result": null,
    "error": null,
    "seconds": 0
  }
}

List characters

GET/charactersFree

Your account's characters, newest first, including the ones made in the studio.

Query parameters

limitinteger: Up to 200; default 50

Request

curl "https://vircasi.com/v1/characters?limit=20" \
  -H "Authorization: Bearer $VIRCASI_KEY"

Response

{
  "characters": [
    {
      "id": "chr_d334f85b0e",
      "created": "2026-11-05T03:01:14+0000",
      "description": "about 24 years old, a man, of white appearance"
    }
  ]
}

Retrieve a character

GET/characters/{id}Free

The character with its current sliders and fresh links to its start photos, newest face photos and every look.

Request

curl "https://vircasi.com/v1/characters/chr_d334f85b0e" \
  -H "Authorization: Bearer $VIRCASI_KEY"

Response

{
  "character": {
    "id": "chr_d334f85b0e",
    "created": "2026-11-05T03:01:14+0000",
    "description": "about 24 years old, a man, of white appearance",
    "gender": "male",
    "age": 24,
    "look": "white",
    "hairstyle": "low_taper_fade",
    "head": "done",
    "sliders": {
      "jaw_width": 0.8,
      "cheekbone_projection": 1
    },
    "start_photos": {
      "face_front": "https://vircasi.com/v1/files/characters/chr_d334f85b0e/face_front.jpg?exp=1793936254&sig=2e15517f1064136a…",
      "face_side": "https://vircasi.com/v1/files/characters/chr_d334f85b0e/face_side.jpg?exp=1793936254&sig=2e15517f1064136a…"
    },
    "face_photos": {
      "45": "https://vircasi.com/v1/files/…/45.jpg?exp=1793936254&sig=2e15517f1064136a…",
      "90": "https://vircasi.com/v1/files/…/90.jpg?exp=1793936254&sig=2e15517f1064136a…",
      "front": "https://vircasi.com/v1/files/characters/chr_d334f85b0e/previews/prev_9a1c/front.jpg?exp=1793936254&sig=2e15517f1064136a…"
    },
    "looks": [
      {
        "id": "look_dc43b8b548",
        "title": "Road-Worn Wanderer",
        "body_type": "lean_athletic",
        "photos": {
          "45": "https://vircasi.com/v1/files/…/45.jpg?exp=1793936254&sig=2e15517f1064136a…",
          "90": "https://vircasi.com/v1/files/…/90.jpg?exp=1793936254&sig=2e15517f1064136a…",
          "front": "https://vircasi.com/v1/files/…/final_c40e/front.jpg?exp=1793936254&sig=2e15517f1064136a…"
        }
      }
    ]
  }
}

Sculpt the 3D head

POST/characters/{id}/sculptFree

Change the face with slider values or in words, and get renders of the 3D head: the exact views the face photos are made from. Free and rate-limited, so iterate as much as you like before you pay for photos.

Body parameters

slidersobject: Slider name → value (see List sliders); values are clamped to the slider's range
modestring: set (default) changes the given sliders; adjust adds to their values; replace keeps only these
textstring: Or the change in words, e.g. "a stronger jaw and a slightly wider nose"
anglesstring[]: Any of front, 45, 90; default all three
langstring: en or zh: the language of summary for text changes

A text change answers with a summary, e.g. "I raised the cheekbones slightly and made the nose a bit narrower."

Request

curl -X POST "https://vircasi.com/v1/characters/chr_d334f85b0e/sculpt" \
  -H "Authorization: Bearer $VIRCASI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sliders":{"jaw_width":0.8,"cheekbone_projection":1},"angles":["front","45"]}'

Response

{
  "sliders": {
    "jaw_width": 0.8,
    "cheekbone_projection": 1
  },
  "summary": null,
  "renders": {
    "45": "https://vircasi.com/v1/files/…/1793848331253_45.png?exp=1793936254&sig=2e15517f1064136a…",
    "front": "https://vircasi.com/v1/files/characters/chr_d334f85b0e/api_renders/1793848331253_front.png?exp=1793936254&sig=2e15517f1064136a…"
  },
  "charged_usd": 0
}

Make face photos

POST/characters/{id}/photos$0.15

Realistic photos of the sculpted head at front, 45° and 90°: three images at $0.05 each. Answers with a job; photos take 45–60 seconds.

Body parameters

glassesstring: none (default), thin_metal, black_rect or round

Result: {"character_id": "chr_…", "photos": {"front": …, "45": …, "90": …}, "images": 3, "charged_usd": 0.15}.

Request

curl -X POST "https://vircasi.com/v1/characters/chr_d334f85b0e/photos" \
  -H "Authorization: Bearer $VIRCASI_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "job": {
    "id": "job_1651bccd50",
    "kind": "api_photos",
    "status": "running",
    "result": null,
    "error": null,
    "seconds": 0
  }
}

Make a full-body look

POST/characters/{id}/looks$0.15

The character in one look at front, 45° and 90°, from a ready-made look or a role in your own words. Three images at $0.05 each; about 60 seconds.

Body parameters

body_typestringrequired: A body type id of the character's gender
look_idstring: A ready-made look. Give this or role.
rolestring: A role in your words, e.g. "a 1980s Hong Kong detective"
glassesstring: none (default), thin_metal, black_rect or round

Result: {"character_id": "chr_…", "look": {"id": "look_…", "title": "…", "photos": {…}}, "images": 3, "charged_usd": 0.15}.

Request

curl -X POST "https://vircasi.com/v1/characters/chr_d334f85b0e/looks" \
  -H "Authorization: Bearer $VIRCASI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body_type":"lean_athletic","role":"a 1980s Hong Kong detective"}'

Response

{
  "job": {
    "id": "job_7e2d90b1aa",
    "kind": "api_look",
    "status": "running",
    "result": null,
    "error": null,
    "seconds": 0
  }
}

Retrieve a job

GET/jobs/{id}Free

Poll a job every 2–3 seconds until its status is done or error. Jobs are kept for an hour.

Request

curl "https://vircasi.com/v1/jobs/job_1651bccd50" \
  -H "Authorization: Bearer $VIRCASI_KEY"

Response

{
  "id": "job_1651bccd50",
  "status": "done",
  "seconds": 49,
  "error": null,
  "result": {
    "character_id": "chr_d334f85b0e",
    "photos": {
      "45": "https://vircasi.com/v1/files/…/45.jpg?exp=1793936254&sig=2e15517f1064136a…",
      "90": "https://vircasi.com/v1/files/…/90.jpg?exp=1793936254&sig=2e15517f1064136a…",
      "front": "https://vircasi.com/v1/files/…/front.jpg?exp=1793936254&sig=2e15517f1064136a…"
    },
    "images": 3,
    "charged_credits": 1.5,
    "charged_usd": 0.15
  }
}

Integrations

MCP for AI agents

Vircasi is an MCP server at https://vircasi.com/mcp (Streamable HTTP, your key as a bearer header), so Claude, Cursor and other agents can design and cast characters for you, at the same prices and limits as the API.

Tools: create_character, sculpt (its renders come back as images the agent can look at),make_face_photos, make_look, get_job, get_character, get_accountand the catalogue lists. Paid tools wait up to 75 seconds for their job, then return its id for get_job.

claude mcp add --transport http vircasi https://vircasi.com/mcp \
  --header "Authorization: Bearer $VIRCASI_KEY"

ComfyUI nodes

Five nodes that output ordinary IMAGE batches, ready for video and consistency workflows:

Library character (free) and Generate character ($0.10)
Sculpt 3D head (free): ten common sliders as widgets, any others as JSON, or words
Face photos 0/45/90 ($0.15) and Full-body look ($0.15)

ComfyUI runs a node again only when its inputs change, so re-queuing a workflow does not pay twice. Download the nodes.

cd ComfyUI/custom_nodes
curl -LO https://vircasi.com/downloads/comfyui-vircasi.zip
unzip comfyui-vircasi.zip && rm comfyui-vircasi.zip
export VIRCASI_API_KEY=vk_live_…   # or paste the key into a node
# then restart ComfyUI

Resources

Usage policies

The API makes fictional adults only (18+). Photos of real people cannot be uploaded, and the content policy and terms of service apply to everything you make.

Changelog

2026-11-05: v1: characters, free sculpt with renders, face photos, full-body looks, jobs and signed links; MCP server and ComfyUI nodes; $0.05 per image.