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.
- POST/v1/chars
- POST/v1/uploads
- POST/v1/runs
- POST/v1/licenses
- GET/v1/licenses/{key}/verify
- GET/v1/teams/{id}/webhooks
Hosted for your product, local for your GPU
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.
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/runsand follow it over a websocket. Fetch takes, upload assets, score media against a character. - The full interactive reference is at
/apion 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/modelsYour 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.
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.
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
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
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
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
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
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
| Calls with a key | 120 a minute per key |
|---|---|
| POST /v1/licenses | 60 a minute per key |
| GET /v1/licenses/{key}/verify | 60 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.
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 NoneWhere to go next
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.