Plask Motion Capture API

Use the Plask API to process video, follow extraction progress, or stream poses into your own application. Manage API keys and credits in the Developer page.

For artist tools, follow Plask to Blender or Plask to UE5.

1. Create an API key

Open the Developer page and create a key with the scopes your application needs: jobs:read, jobs:write, live:write, or usage:read.
Save the key when it is shown. Keep it on your server or in a private local file.
Send it in the Authorization: Bearer YOUR_API_KEY header. Do not put it in a URL, browser bundle, Blender scene, or Unreal project.

The base URL is https://pose-api.plask.ai. See the API reference for request and response fields.

2. Check your credits

Call GET /v1/usage to check available and reserved credits before starting work.

A realtime session reserves the limit you choose. Each committed pose costs one credit; dropped and rejected frames are not charged. Closing the session releases unused credits. Development keys use a separate test allowance with the same metering rules.

Use a new Idempotency-Key for each new job or session. If admission times out, retry with the same key and request body to recover the original operation.

3. Process a video

Create an upload with POST /v1/uploads, including its byte count and SHA-256 checksum.
Send the file to the returned signed PUT URL with the required headers. Then call POST /v1/uploads/{id}/complete.
Create a job with POST /v1/jobs, using the upload ID, model: "accurate", and the required frame range.
Follow GET /v1/jobs/{id}/events for server-sent progress events, or poll the job. Reconnect the event stream with Last-Event-ID.
When processing finishes, download from GET /v1/jobs/{id}/result.

Progress reports a stage and completed/total work in a named unit. Show progress within that stage. While allocating a worker or loading a model, show a waiting state until measured progress is available. Video jobs use Plask's batch GPU workers; realtime sessions use on-demand Modal GPUs.

Browser clients can request the result with ?redirect=false, then fetch the returned signed URL without forwarding the API key. To stop a job, call POST /v1/jobs/{id}/cancel.

4. Stream realtime poses

Create a session with a bounded pose budget:

POST /v1/realtime/sessions
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: A_NEW_UUID
Content-Type: application/json

{"model":"realtime-preview","max_frames":300,"fps":30,"width":640,"height":480}

Call the returned token endpoint, connect to the returned WebSocket URL, and authenticate within five seconds with {"type":"authenticate","token":"YOUR_SESSION_TOKEN"}.
Handle session.warming while the GPU starts. Keep your local preview running and wait for session.ready before sending images.
Read the negotiated epoch, batch size, pending-frame limit, and last committed sequence/timestamp from session.ready.
Send JPEG frames and read pose, dropped, and rejected acknowledgements concurrently.
Stop capture, drain outstanding responses, then call POST /v1/realtime/sessions/{id}/close.

Frames have a 24-byte network-byte-order header followed by the JPEG: PLK1 (4 bytes), epoch (uint32), sequence (uint64), and monotonic capture timestamp in microseconds (uint64). Sequence and timestamp must increase and fit within JavaScript's safe integer range. JPEGs must match the negotiated dimensions and be no larger than 1 MiB.

Sample on a steady capture clock and keep outstanding frames within pending_frames. Do not replay a camera backlog after a network delay. The server processes up to eight frames per GPU call without waiting for a full batch. Preview, network capture, and rig display should run independently.

Poses use plask.pose.v1, a smpl24-neutral-v1 skeleton, metres, camera-relative root position, right-handed X-right/Y-forward/Z-up coordinates, and local xyzw quaternions. Handle tracking_reset by starting a new interpolation segment. A reconnect uses a new epoch; resume after the committed values returned by the server.

Respect startup_timeout_seconds. Session expiry is ten minutes from admission, including startup. Cold allocation can take substantially longer than steady streaming. On a connection failure, close the session through REST to release the remaining reservation.

Set up native capture

Blender and Unreal use the same local runtime. For native capture, use macOS 14 or later and Python 3.12.

1. Install the runtime

python3.12 -m venv ~/plask-env
~/plask-env/bin/python -m pip install \
  https://pose-api.plask.ai/integrations/downloads/plask_serving-0.4.3-py3-none-any.whl

2. Build the camera helper

Download and extract the macOS camera helper source. From the extracted folder, run:

bash macos/build_camera.sh

Apple's command-line developer tools are required. This builds Plask Camera.app in ~/.local/share/plask. It is a local build, not a notarized installer. Allow camera access when prompted.

3. Save your key

Create ~/.config/plask/development.env with these contents, replacing the placeholder with a key that has live:write access:

PLASK_API_KEY=YOUR_PRIVATE_KEY
PLASK_API_URL=https://pose-api.plask.ai

Make the file private:

chmod 600 ~/.config/plask/development.env

Continue with Blender setup or Unreal setup. Keep the runtime and extension versions matched when upgrading.

Connect Unreal

After the native capture setup, list your cameras and generate a pairing code:

PLASK_CAMERA="$HOME/.local/share/plask/Plask Camera.app/Contents/MacOS/PlaskCamera"
"$PLASK_CAMERA" --list /tmp/plask-cameras.json
cat /tmp/plask-cameras.json
PLASK_PAIRING=$(~/plask-env/bin/python -c 'import secrets; print(secrets.token_urlsafe(24))')
printf '%s\n' "$PLASK_PAIRING"

In Unreal, open Window → Virtual Production → Live Link → Add Source → Plask Live. Enter port 14046 and the pairing code shown in your terminal.

In the same terminal, replace CAMERA_ID with your camera's ID and run:

PLASK_TAKE=$(mktemp -d)
~/plask-env/bin/python -m plask_serving.native_capture \
  --target unreal --port 14046 --pairing "$PLASK_PAIRING" \
  --directory "$PLASK_TAKE" --parent $$ --budget 300 \
  --key-file "$HOME/.config/plask/development.env" \
  --camera-binary "$PLASK_CAMERA" --camera CAMERA_ID \
  --model realtime-preview

Allow camera access when prompted. Keep the helper running while you capture, then press Ctrl-C to finish. Continue with recording in Unreal.

Earlier SDK integrations

The earlier @plask-ai/client SDK uses a different authentication and job interface. The REST and realtime workflows on this page use API keys and the current API reference; they are not drop-in replacements for existing SDK calls.

Updated October 11, 2026. Runtime 0.4.3.

Plask Motion Capture API

On this page