Skip to main content
Local apps such as ComfyUI and Omnichar Studio run on the user’s own machine and never sign in to Omnichar. To use a licensed character they check the license online with two things the user has: Every license has a secret, whether it was issued to a named team or as a secret license. The secret is never in the .char. Both calls need no API key. They live on the public API at https://api.omnichar.org/v1, so the full paths are https://api.omnichar.org/v1/licenses/verify and https://api.omnichar.org/v1/licenses/usage.

1. Verify

POST /v1/licenses/verify
model, client and client_version take letters, digits, spaces and . _ : / @ + -. Anything else, or a missing field, answers 422 in the usual error shape.

Valid

200:
ticket is an opaque string for reporting usage. Omnichar keeps only its hash. It lasts ttl_seconds, 600, or less when the license ends sooner; valid_until is when it stops, the earlier of the two. owner_name is the provider team’s name, to show the user whose character it is. Verify again for a new ticket when this one runs out. Verifying does not count as a generation; only usage reports do.

Refused

403, with a status to branch on and a message you can show the user as it is: Messages name the real provider and dates; branch on status, not on message, which can change. These bodies are not the usual {"error": ...} shape. The checks run in this order, so nothing about a license is said until the secret is right:
  1. The secret matches the license. A lsk_test_ secret only verifies a sandbox license and a lsk_live_ secret only a production one. An unknown license ID gets the same wrong_secret as a wrong secret.
  2. The license is not revoked.
  3. It has not expired.
  4. It has started (starts_at). A license named by an email that has not signed up yet works here: the secret is the credential.
  5. char_id is the license’s character.
  6. output is in the license’s scope.media.
  7. If scope.max_generations is set, it has not been reached.
use, territories and allow_list are not checked here: a local app has no team or run context to check them against. When a check after the secret fails, the provider sees it as a blocked usage record and gets usage.blocked, at most once a minute per license and reason.

Too many wrong secrets

After 5 wrong secrets for one license ID in 15 minutes, or 20 from one address for any license IDs, further wrong secrets for that license ID or from that address answer 429 until the 15 minutes pass. The right secret always gets through, so someone sending junk with a license ID from a .char cannot lock out the people it belongs to. The body is the usual error shape with the code rate_limited, and retry-after says how many seconds to wait. License IDs that do not exist lock the same way, so a lockout says nothing about whether a license is real. An IPv6 address counts by its /64. The route also allows 30 verify calls a minute per address, whatever the answer; over that you get the same 429 shape.

2. Report usage

POST /v1/licenses/usage Report each generation once it is made:
202 with {"accepted": true}. The report becomes a usage record the provider sees on its dashboard and in usage, with "surface": "local", "team_id": null and the model, client and client_version you sent, and the provider gets usage.generated. If the license has scope.max_generations, each report counts against it, as a Cloud run does. Refusals with a status use the same {"status": ..., "message": ...} shape as verify.

Rotation and revocation

When the provider rotates the secret, the old one answers wrong_secret at once and every ticket it was given stops working. When the provider revokes the license, its tickets stop working too, and verify answers revoked. Ask the user for the new secret, or tell them the license has ended.

Building a client

  • Ask the user for the secret once and store it as a secret, never in a workflow file, a log or an output.
  • Read license_id and char_id from the .char the user loaded; do not ask for them.
  • Verify before the first generation and again once valid_until passes.
  • Show the message from a refusal; it is written for the user.
  • On 429, wait for retry-after before asking again.