youcam-cli

youcam is the command-line interface for the YouCam AI APIs. Every one of its AI features (face and body editing, hair, skin analysis, makeup, virtual try-on, background and photo editing, image and video generation...etc.) runs from the terminal with the same models and parameters as the API. You can also check task status, browse predefined templates, and look up your units and feature costs.

The CLI works whether you are evaluating a feature, building an integration, or automating a pipeline:

• Evaluating YouCam API AI features: run a feature on your own photos and check the results, e.g. to compare styles or confirm a feature fits your product. No code needed.
• Integrating the API: try any endpoint from the terminal before writing code. Options map one-to-one to request fields, and each feature links to its API reference.
• AI agents: Claude Code, Cursor, Codex and other agents can use any YouCam feature as a plain shell command. Every command prints JSON and exits with code 1 on failure, every feature and option is self-described in --help, and invalid values are rejected before a request is sent.
• Automation and batch jobs: run features from shell scripts, CI pipelines, or containers over whole folders of product shots and portraits. Local files are uploaded for you, with no upload step to script.

• Node.js 18 or later (and npm).
• A YouCam API key.

npm install -g @youcam_cli/youcam-cli

# Verify the installation
youcam --help

# Version of the YouCam CLI
youcam --version

To uninstall, run npm uninstall -g @youcam_cli/youcam-cli.

youcam auth login <apiKey> saves your API key once, the key is stored locally and reused by every later command.

youcam auth login <apiKey>

# or explicitly with a flag
youcam auth login --api-key <apiKey>

# Remove the saved API key (logout CLI tool)
youcam auth logout

# List the available authentication options
youcam auth --help

auth login writes the key to a plain JSON file, ~/.youcam-cli/credentials.json:

{
  "apiKey": "<your-api-key>"
}

• Every run, status, template and client command reads this file automatically.
• When YOUCAM_CLI_API_KEY environment variable is set, it takes precedence over the saved key.

Run your first AI task, from checking your units to downloading the result. This runs one real task, so it uses units (see Checking feature cost).

Every YouCam feature runs as a background task: you start it, get a task_id back, then check that task_id until the result is ready.

1. Install and log in (see Installation and Authentication for details)

npm install -g @youcam_cli/youcam-cli
youcam auth login <apiKey>

2. Check your units

youcam client credit

Response:

{
  "status": 200,
  "results": [
 {
 "id": 0,
 "type": "ApiPaygToken",
 "amount": 8193,
 "amount_dec": 8193,
 "expiry": 1801958399000
 }
  ]
}

amount is the number of units in each entry, and expiry is when they expire (milliseconds since the Unix epoch). The command is named credit because the API calls a unit a "credit" (see Units and feature cost).

3. Start a task

This enhances a sample photo to twice its resolution with AI Photo Enhance:

youcam run enhance --src_file "https://plugins-media.makeupar.com/strapi/assets/hair_color_03_81c0c8a3c8.jpg" --scale 2

Response:

{
  "status": 200,
  "data": {
 "task_id": "32tu4jQvRbI9NfnKlw13cls8tyT1zA2ZoOtKq-RkiTL_FrIEOLYHJX1HxYVrnWz"
  }
}

The CLI also prints the command for the next step. It goes to stderr, so stdout stays pure JSON for scripts:

Run `youcam status enhance 32tu4jQvRbI9NfnKlw13cls8tyT1zA2ZoOtKq-RkiTL_FrIEOLYHJX1HxYVrnWz` to check the result.

To use your own photo, pass a local path instead, e.g. --src_file ./photo.jpg.

4. Check & download the result

youcam status enhance <task_id>

While the task is still processing, task_status is running; run the command again after a few seconds. Once it is done:

{
  "status": 200,
  "data": {
 "error": null,
 "results": {
 "url": "https://yce-us.s3-accelerate.amazonaws.com/ttl30/.../509f8acd-8d41-4459-aa31-1d4738d7a922.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&...&X-Amz-Expires=7200&..."
 },
 "task_status": "success"
  }
}

results.url is the enhanced image. It is a signed link that expires after 2 hours (X-Amz-Expires=7200), so download it soon.

Next steps

• Browse the available AI features, and run youcam run <feature> --help to see a feature's options.
• Learn how options, files and JSON parameters work in Running an AI task.
• Some features detect faces or bodies first, see Pre-process.

Units are what you spend to use the YouCam API, and each AI feature uses a different number of them. The API, and therefore the CLI, calls a unit a "credit", which is why the commands are client credit and client credit-history. See What does 'Unit' mean, and how is it used? in the official FAQ.

youcam client credit  # remaining units
youcam client credit-history  # unit usage history

Look up how many units a feature consumes before running it at scale.

youcam client feature-cost

Both commands page their results with --page_size and --starting_token <token>:

• credit-history: --page_size <1-30>, default 20.
• feature-cost: --page_size <1-20>, default 20.

Note: Pre-process detection tasks and listing predefined templates do not consume units.

youcam <command> [options]

Commands:
  auth Manage authentication credentials
  run  Run an AI task
  status  Check the status of an AI task
  template   List predefined templates
  client  Get account/credit info
  help Display help for a command

Every command and sub-command supports -h, --help to show its own usage and options:

youcam run --help
youcam run face-swap --help

Results are printed as JSON. A command exits with code 1 when the request fails.

Every endpoint in the API reference maps predictably to a CLI command:

Rules of thumb for deriving <feature> from the API reference:

• The CLI feature name is the path segment right before {task_id}, e.g. /s2s/v2.0/task/abs-shape/{task_id} → abs-shape.

• The API version prefix (v2.0, v2.1, …) is handled for you: each command calls the latest API version in the API reference, e.g. skin-analysis and hair-transfer call /s2s/v2.1/.... When a feature has several engine versions, only the newest is offered, e.g. cloth-v4 but not cloth-v3.

• A few endpoints have an extra path segment, drop it to get the CLI name:

  API path	CLI command
  /s2s/v2.0/task/2d-vto/earring (same for necklace, ring, bracelet, watch)	youcam run earring
  /s2s/v2.0/task/image-to-image/youcam, /text-to-image/youcam, /image-to-video/youcam, /text-to-video/youcam	youcam run image-to-image, run text-to-image, run image-to-video, run text-to-video
  /s2s/v2.0/task/colorize/color-correct	youcam run color-correct

• Request body properties become --<property_name> options on the matching run command (see Uploading files and Passing JSON parameters). Query parameters such as page_size and starting_token become --<param_name> options too.

Take AI Hair Color Virtual Try-On as an example, its two endpoints are:

POST /s2s/v2.0/task/hair-color   { src_file_url | src_file_id, preset?, pattern?, palettes? }
GET  /s2s/v2.0/task/hair-color/{task_id}

map to these CLI commands:

youcam run hair-color --src_file <url-or-path> [--preset <value> | --pattern <json> --palettes <json>]
youcam status hair-color <task_id>

To apply a preset color:

youcam run hair-color --src_file "https://plugins-media.makeupar.com/strapi/assets/hair_color_09_76a7a1081e.jpg" --preset "Honey Blonde"
youcam status hair-color <task_id>

The run command sends this request body:

{
  "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/hair_color_09_76a7a1081e.jpg",
  "preset": "Honey Blonde"
}

To apply a custom color instead, pass the pattern and palettes objects:

youcam run hair-color --src_file "https://plugins-media.makeupar.com/strapi/assets/hair_color_09_76a7a1081e.jpg" \
  --pattern '{"name": "full"}' \
  --palettes '[{"color": "#8B4513", "color_intensity": 80, "shine_intensity": 50}]'
youcam status hair-color <task_id>

The equivalent JSON request body is:

{
  "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/hair_color_09_76a7a1081e.jpg",
  "pattern": { "name": "full" },
  "palettes": [{ "color": "#8B4513", "color_intensity": 80, "shine_intensity": 50 }]
}

youcam run prints the new task_id; pass it to youcam status and repeat until task_status is success.

Each AI feature is a sub-command of run. Options vary per feature; use --help on the feature to see its inputs.

youcam run <feature> [options]

For instance, to run AI Abs Filter:

youcam run abs-shape --src_file "https://example.com/photo.jpg" --mode "Six-pack" --intensity 2

Running a task returns a task_id, which you use to check its status.

• Pre-process: a few features detect the faces or bodies in the photo first, so you can choose which person to process. See Pre-process.
• Templates: some features accept a ready-made style preset through --template_id. See Listing predefined templates.
• Validation: option values are checked against the API schema before anything is sent. Options with a fixed set of values list them in --help, and an invalid value is rejected with the allowed choices.

Every feature that takes an image or video exposes it as a single --src_file option, even though the API accepts two mutually exclusive fields: src_file_url (a public URL) or src_file_id (the ID of an uploaded file). The CLI picks the right one based on what you pass:

• A publicly accessible URL is sent as src_file_url. Nothing is uploaded.
  youcam run enhance --src_file "https://example.com/photo.jpg" --scale 2

• A local file path is uploaded for you, and the task is sent with src_file_id:
  1. POST /s2s/v2.0/file registers the file (name, content type, size) and returns a presigned upload URL and a file_id.
  2. The file's bytes are PUT to that presigned URL.
  3. run <feature> is called with src_file_id set to that file_id.
  youcam run enhance --src_file ./photo.jpg --scale 2

  Windows paths work too in PowerShell or cmd:
  youcam run enhance --src_file .\photo.jpg --scale 2

Notes:

• Local files must be .jpg, .jpeg, .png or .mp4.
• Size, resolution and duration limits depend on the feature, an oversized file makes the task fail with exceed_max_filesize in status.
• There is no separate upload CLI command, uploads happen only through file options.

Beyond --src_file, some features take extra images (masks, reference photos, product shots). They follow the same rule: pass a public URL or a local path, and local paths are uploaded for you.

Options with ... take several values after one flag, separated by spaces (not commas):

youcam run face-swap \
  --src_file group-photo.jpg \
  --ref_files person-a.jpg person-b.jpg \
  --face_mapping '[{"index":0,"position":0},{"index":1,"position":1}]'

If one multi-value option mixes public URLs and local paths, e.g. --ref_files https://example.com/a.jpg ./b.jpg, every file in it is uploaded, the URLs included: the CLI downloads each URL, uploads it like a local file, and sends all of them as file IDs (e.g. ref_file_ids). Those URLs must then serve a JPG, PNG or MP4. To have URLs sent as URLs, pass only URLs in that option.

Run youcam run <feature> --help to see exactly which of these a feature accepts.

These forms listed below are equivalent, use whichever you prefer:

youcam run skin-simulation --src_file https://example.com/face.png --acne 1
youcam run skin-simulation --src_file=https://example.com/face.png --acne=1
youcam run skin-simulation --src_file="https://example.com/face.png" --acne="1"

• Quotes are only needed when a value contains spaces or characters your shell treats specially (e.g. & in a URL, or JSON).
• Options that take several values accept them space-separated after one flag, or as a repeated flag:
  • --src_files a.jpg b.jpg
  • --src_files=a.jpg --src_files=b.jpg
  • Not --src_files=a.jpg b.jpg, which is rejected.

Options shown as <json> in --help (instead of <value>) correspond to an object or array field in the API request body. Pass the whole structure as one JSON value:

• inline JSON, e.g. --pattern '{"name":"full"}'
• a path to a .json file, e.g. --effects ./effects.json
• - to read the JSON from stdin, e.g. cat effects.json | youcam run makeup-vto --src_file photo.jpg --effects -

Quoting inline JSON:

# bash / zsh / macOS / Linux / Git Bash: single quotes protect the double quotes
youcam run hair-color --src_file photo.jpg --pattern '{"name":"full"}' --palettes '[{"color":"#8B4513","color_intensity":80,"shine_intensity":50}]'

# Windows PowerShell: escape the inner double quotes
youcam run hair-color --src_file photo.jpg --pattern '{\"name\":\"full\"}' --palettes '[{\"color\":\"#8B4513\",\"color_intensity\":80,\"shine_intensity\":50}]'

Nested object and array: hair-color's --pattern is an object, and --palettes an array of {color, color_intensity, shine_intensity} objects (one for full mode, two for ombre mode):

youcam run hair-color \
  --src_file photo.jpg \
  --pattern '{"name":"full"}' \
  --palettes '[{"color":"#FF5733","color_intensity":80,"shine_intensity":50}]'

Once photo.jpg is uploaded and resolved to a src_file_id, the CLI sends this body to POST /s2s/v2.0/task/hair-color:

{
  "src_file_id": "<file_id from the upload>",
  "pattern": {
 "name": "full"
  },
  "palettes": [
 {
 "color": "#FF5733",
 "color_intensity": 80,
 "shine_intensity": 50
 }
  ]
}

Each --<option> <json> value is used as that property's value as-is: --pattern becomes the pattern object and --palettes the palettes array. Nothing is renamed or reshaped, and no defaults are added for options you leave out.

Deeply nested arrays: makeup-vto's --effects is an array of effect objects, some with their own pattern and palettes. Multi-line JSON is fine:

youcam run makeup-vto --src_file photo.jpg --effects '[
  {"category":"skin_smooth","skinSmoothStrength":55,"skinSmoothColorIntensity":45},
  {"category":"blush","pattern":{"name":"1color1"},"palettes":[
 {"color":"#e19f9f","texture":"matte","colorIntensity":60}
  ]}
]'

Pattern names such as 1color1 come from youcam template makeup-vto (see Listing makeup-vto pattern names).

Invalid JSON, or a value of the wrong type, is rejected before the request is sent and names the offending field, e.g. Invalid value for --palettes: [{"color":123}] (0.color: Invalid input: expected string, received number).

youcam status <feature> <task_id>
# or
youcam status <feature> --task_id <task_id>

Example:

youcam status abs-shape 1234567890abcdef

Poll until task_status is success (or error); the response then includes the results, such as output file URLs. For a pre-process task, use youcam status pre-process <feature> <task_id>.

Pre-process tasks use no units, only the main task does.

For the features below, a photo can contain several people, so you choose which one to process. youcam run pre-process <feature> detects the faces or bodies in the photo and returns them as a list. Each one is numbered by its position in that list: 0 for the first, 1 for the second, and so on.

1. Detect: youcam run pre-process <feature> --src_file <photo> returns a task_id.
2. Read the detections: youcam status pre-process <feature> <task_id> lists the detected faces or bodies. The list's form depends on the feature: body-reshape returns results.result[], boxes relative to the image size (0–1), while face-swap returns results.faces[].bbox, pixel boxes as [x1, y1, x2, y2] (top-left and bottom-right corners).
3. Run the feature on the same photo, passing the chosen number with the option in this table:

For example, youcam run face-lift --src_file <photo> --index 1 ... lifts the second detected face. See the example workflow for a full run with real output.

Some features ship with ready-to-use templates (style or look presets) that you reference with --template_id instead of building parameters yourself.

youcam template <feature> [--page_size <1-20>] [--starting_token <token>]

<feature> is one of:

For makeup-vto, see Listing makeup-vto pattern names for the details of its patterns.

Example:

youcam template ai-avatar --page_size 10
youcam run ai-avatar --src_file ./photo.jpg --template_id <id> --output_count 1

Pass the next_token from a response as --starting_token to fetch the next page.

When the ai-avatar task succeeds, youcam status ai-avatar <task_id> lists the generated images in results.output[].url, one entry per output.

makeup-vto effects pick their shape by name, e.g. "pattern":{"name":"1color1"} for blush or "shape":{"name":"plump"} for lip color. List the valid names for each effect category:

youcam template makeup-vto <categories...>

Pass one or more of blush, bronzer, contour, eyebrows, eyeliner, eyeshadow, eyelashes, lipshape, lipliner, highlighter (or the same names after --category). At least one is required. The catalogs are public, so listing them uses no units.

youcam template makeup-vto blush lipshape

The result is keyed by category. Use an entry's label as the pattern name; colorNum (blush, eyeliner and eyeshadow only) is how many palettes that pattern needs:

{
  "blush": [
 {
 "category": "1 color",
 "label": "1color1",
 "thumbnail": "https://app-cdn-01.makeupar.com/.../a53cd4f4-43b6-4e19-b85a-ec7a95c6a47f.jpg",
 "tags": [
  { "id": 100, "name": "Blush 3D" },
  { "id": 103, "name": "Oblong" }
 ],
 "colorNum": 1
 }
  ],
  "lipshape": [
 {
 "category": "general",
 "label": "original",
 "thumbnail": "https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/original.png",
 "tags": []
 }
  ]
}

A category that can't be fetched shows { "error": "..." } instead, and the command exits with code 1.

Pass any of these as <feature> to run and status. Each links to its API reference page. For the features that have a detection step, see Pre-process. For the ones that work with youcam template, see Listing predefined templates.

• makeup-vto
  • pattern names
• mu-transfer
• look-vto
• eye-color-vto
• nail-vto
• ai-nail

• face-attr-analysis
• skin-analysis
• skin-tone-analysis
• fitzpatrick-scale-analyzer
• skin-simulation
• abs-shape
• aging
• body-reshape
• breast-shape
• face-lift
• face-reshape
• ai-smile
• teeth-whiten

• hair-density-detection
• hair-frizziness-detection
• hair-length-detection
• hair-type-detection
• hair-bang
• hair-color
• hair-curl
• hair-ext
• hair-transfer
• hair-vol
• beard-style

• earring
• necklace
• ring
• bracelet
• watch
• bag
• hat
• scarf
• cloth-v4
• fabric
• shoes-transfer

• enhance
• lighting
• colorize
• color-correct
• sod
• bg-blur
• bg-replace
• generative-fill
• obj-replace
• out-paint
• image-to-image
• text-to-image
• ai-avatar
• ai-studio
• headshot
• wmk-removal
• face-swap

• bg-replace-vid
• face-swap-vid
• image-to-video
• text-to-video
• obj-rem-vid
• video-sr
• video-trans

Run youcam run <feature> --help for the exact parameters each feature accepts.

This walks through AI Body Reshape from start to finish — detect the bodies in a photo, pick one, reshape it, and fetch the result. The request and response bodies below were captured from real runs with this sample photo:

1. Start the detection (pre-process) task

youcam run pre-process body-reshape \
  --src_file "https://plugins-media.makeupar.com/strapi/assets/body_reshape_01_d10c50c97d.jpg"

Response:

{
  "status": 200,
  "data": {
 "task_id": "CKPWaMO-olxd1ECr_3tTDXW5Gu_tQw0EKgN0-dU27zSyXhV8cJR2TzYLMhDqD"
  }
}

2. Get the detected bodies

youcam status pre-process body-reshape CKPWaMO-olxd1ECr_3tTDXW5Gu_tQw0EKgN0-dU27zSyXhV8cJR2TzYLMhDqD

Response:

{
  "status": 200,
  "data": {
 "error": null,
 "results": {
 "result": [
  {
  "left": 0.35347824096679686,
  "top": 0.022326231002807617,
  "width": 0.3041056156158447,
  "height": 0.951037073135376
  }
 ],
 "timed": 4565
 },
 "task_status": "success"
  }
}

Each entry in results.result is one detected person, as a bounding box relative to the image size (0–1). Its position in the array is the --index to pass next; this photo has one person, so the index is 0.

3. Run the main task on the chosen person

youcam run body-reshape \
  --src_file "https://plugins-media.makeupar.com/strapi/assets/body_reshape_01_d10c50c97d.jpg" \
  --version 1.0 \
  --index 0 \
  --features '{"slim": 20}'

Response:

{
  "status": 200,
  "data": {
 "task_id": "ZV3WIzcB1rk7I5o8hMxKP5VdgIEpnHf7VOpsk1YC76tZy2Wur0lg4Bunb3KY-7Qa"
  }
}

4. Poll the main task until it finishes

youcam status body-reshape ZV3WIzcB1rk7I5o8hMxKP5VdgIEpnHf7VOpsk1YC76tZy2Wur0lg4Bunb3KY-7Qa

While the task runs, task_status is running; repeat the command every few seconds. Once it succeeds (GET /s2s/v2.0/task/body-reshape/{task_id}):

{
  "status": 200,
  "data": {
 "error": null,
 "results": {
 "url": "https://yce-us.s3-accelerate.amazonaws.com/ttl30/.../0b333891-60be-4cd1-81cd-7d8cae35b3eb.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&...&X-Amz-Expires=7200&...",
 "timed": 12131,
 "slim": true
 },
 "task_status": "success"
  }
}

results.url is the reshaped image. It is a signed link that expires (X-Amz-Expires=7200, i.e. 2 hours), so download it soon after the task succeeds.

The CLI sends standard YouCam API requests, so everything in the API documentation applies unchanged: the same rate limits, error codes, and file retention periods. See also the API's own Debugging Guide.

A problem can surface at three points:

A failed task still exits with 0, because the status request itself succeeded. Scripts must check data.task_status, not only the exit code.

The API rate limits apply to every youcam command:

• Per IP address: at most 250 requests per 300 seconds.
• Per access token (API key): at most 250 requests per 300 seconds.
• Both limits must be met. A request that breaks either one gets 429 Too Many Requests, and the CLI exits with code 1.
• The recommended pace is about 5 requests per second.

Most commands send one API request. run with local files also sends one POST /s2s/v2.0/file request per file before the task request. Polling counts too — checking several tasks every second can use up the limit quickly. Poll every few seconds, and when you get a 429, wait and retry with an increasing delay instead of retrying right away.

These are caught before the task request is sent, so they use no units.

The API rejected the request. The CLI prints the API's response on stdout, for example:

{
  "status": 400,
  "error": "This task ID doesn't exist, or the task has expired.",
  "error_code": "InvalidTaskId"
}

The task was accepted but the AI engine couldn't process it. youcam status returns "task_status": "error", with the code in data.error and a description in data.error_message. Look the code up in the API's Error Codes page. Some features have extra codes, which are listed under "File Specs & Errors" on the feature's API reference page, along with its size, resolution and pose limits.

A result URL (e.g. results.url, or results.output[].url for ai-avatar) works for 2 hours after the task succeeds. If it has expired, run youcam status <feature> <task_id> again to get a new link; this works for 30 days after the task was created. Results are deleted after 30 days, so download anything you want to keep before then.

youcam help
youcam help <command>
youcam <command> <subcommand> --help # e.g., youcam run pre-process --help