New.char finetuning and scoring are now available in the cloud
Developers · API

Characters, runs and licenses over HTTPS

Build a character from photos, generate with it, and license it to another team. Sandbox keys run the whole flow with mocked builds and no charge. For your own GPU, OmniChar Studio exposes a local API with no account at all.

Base URL https://api.omnichar.org/v1. Bearer team keys: sk_test_ for sandbox, sk_live_ for production.

A few of the endpoints
  • POST/v1/chars
  • POST/v1/uploads
  • POST/v1/runs
  • POST/v1/licenses
  • GET/v1/licenses/{key}/verify
  • GET/v1/teams/{id}/webhooks
Two APIs

Hosted for your product, local for your GPU

Hosted

api.omnichar.org

  • A team key as a Bearer token, created in Settings → API keys and shown once.
  • sk_test_ keys use the sandbox: characters are mocked and ready in about 30 seconds, no GPU runs, nothing is charged.
  • sk_live_ keys build for real and draw on your build balance, then credits.
  • Each key carries scopes, such as chars:write or licenses:read.
Local

127.0.0.1:8848/v1

  • The engine inside OmniChar Studio, on your own GPU. No account, no key.
  • Submit a graph to POST /v1/runs and follow it over a websocket. Fetch takes, upload assets, score media against a character.
  • The full interactive reference is at /api on a running server.
./webui.sh    # Studio + engine on :8848

# live VRAM and RAM budget
curl -s localhost:8848/v1/health
# every node's ports and params
curl -s localhost:8848/v1/models
Example

Your first character in the sandbox

Check the key, upload four face photos, create the character, and wait for char.ready. In sandbox that takes about 30 seconds.

Example · From the API quickstart
export OMNICHAR_API_KEY=sk_test_...
export API=https://api.omnichar.org/v1

# Check the key: the answer names your team and "env": "sandbox"
curl -s $API/team -H "Authorization: Bearer $OMNICHAR_API_KEY"

# Build a character from 4-12 uploaded face photos
curl -s -X POST $API/chars \
  -H "Authorization: Bearer $OMNICHAR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-subject-001" \
  -d '{
    "subject_id": "subject-001",
    "references": { "face": [
      "inputs/...1.png", "inputs/...2.png",
      "inputs/...3.png", "inputs/...4.png"
    ] },
    "description": "Calm presenter"
  }'
# -> {"id":"7f1c...","status":"queued","version":1}

The quickstart carries on from here: license the character to a second team, generate as that team, read the usage, then revoke and watch the next run get blocked.

Send an Idempotency-Key on creates so a retry never builds twice. Prefer webhooks to polling a build in a tight loop.

Follow the full quickstart →
Endpoints

What the hosted API covers

  • Characters

    Build from 4-12 face photos plus optional body photos and voice, check the build, download the .char, retrain as a new version.

    • POST/v1/chars
    • GET/v1/chars/{id}
    • POST/v1/chars/{id}/retrain
    Characters docs →
  • Uploads

    Get a signed link for each photo or voice clip, PUT the bytes, and pass the upload_key as a reference.

    • POST/v1/uploads
    Uploads docs →
  • Runs

    Generate with a character by char_id. A licensed character's output carries the license in its metadata.

    • POST/v1/runs
    • GET/v1/runs/{id}
    • GET/v1/runs/{id}/outputs
    Runs docs →
  • Licenses

    Issue an Ed25519-signed license to a named team with a scope and dates, read every use, revoke it.

    • POST/v1/licenses
    • POST/v1/licenses/{key}/revoke
    • GET/v1/licenses/{key}/usage
    Licenses docs →
  • Verify

    Check a license with no API key: valid, revoked, expired, not found or mismatch. Or verify the signature offline.

    • GET/v1/licenses/{key}/verify
    • GET/v1/.well-known/license-keys
    Verify docs →
  • Webhooks

    Signed char.ready, char.failed, char.updated and license events, retried for 24 hours.

    • GET/v1/teams/{id}/webhooks
    • POST/v1/teams/{id}/webhooks
    Webhooks docs →
Rate limits
Calls with a key120 a minute per key
POST /v1/licenses60 a minute per key
GET /v1/licenses/{key}/verify60 a minute per client address

Licensing on top of the API

A license travels inside the licensee's .char, signed with Ed25519, and every generation is checked against it. Over a rate limit you get 429 with a retry-after header.

Python SDK

Read .char files with no API at all

omnichar-sdk opens a character on disk and hands back its references in prompt order, its description, any LoRA and its voice. Standard library only, Apache-2.0.

# pip install omnichar-sdk
from omnichar_sdk import Character

char = Character.open("Ada.char")
char.get_description()                   # locked description
char.get_references(arch="flux2-klein")  # in prompt order
char.get_lora()                          # adapter, if any
char.get_voice()                         # voice clip or None

Questions

Does OmniChar have an API?

Yes. The hosted API at https://api.omnichar.org/v1 builds characters, runs generations with them, issues and revokes licenses, verifies licenses and sends signed webhooks. OmniChar Studio also runs a local API on 127.0.0.1:8848/v1 on your own GPU, with no account.

How do I authenticate with the OmniChar API?

Send a team API key as a Bearer token. Keys are created in Settings → API keys. sk_test_ keys use the sandbox and sk_live_ keys use production; the environment comes from the key alone.

Can I try the API for free?

Yes, with a sandbox key. Sandbox characters are mocked and ready in about 30 seconds, no GPU runs, and no builds or credits are spent.

How many photos does a character need?

The API builds a character from 4 to 12 face photos, plus optional body photos and a voice clip. Upload each one with POST /v1/uploads and pass its upload_key as a reference.

Can anyone verify an OmniChar license?

Yes. GET /v1/licenses/{key}/verify needs no API key, only the license signature from the .char it came in. The signing keys are published at /v1/.well-known/license-keys for offline checks.

What are the API rate limits?

120 calls a minute per key, with lower limits on issuing and verifying licenses. Over a limit the API answers 429 with a retry-after header.

Start in the sandbox. Nothing is charged until you switch keys.