Getting access

Everything on this site works against a 2wai account that’s been enrolled in the developer program. This page covers that enrollment, where your sk_ key comes from, and the opt-in that lets your own custom avatars be reachable through the developer API.

Enroll at 2wai.ai/developers

The developer portal is hosted on the main 2wai site, not here. Sign up and manage keys at:

https://2wai.ai/developers

1. Create or sign in to a 2wai account at https://2wai.ai. Email/password or Google.
2. Open the Developer area at https://2wai.ai/developers.
3. Accept the developer agreement. This is the legal gate between a regular 2wai account (consumer) and developer access (API usage with billing exposure).
4. Get auto-approved on the thinned baseline (verified email + not disabled + not rate-locked). If you miss one of those, the request goes to a short admin-review queue.
5. Generate a key in the Developer Console. You’ll see:
   • sk_test_... for test mode (canned responses on some endpoints, useful for CI + integration tests without burning real pipeline minutes).
   • sk_live_... for real pipeline runs, metered against your account. The plaintext key is shown once at creation. Copy it immediately into your server’s environment (TWAI_SECRET_KEY=sk_live_...) or secrets manager.

The key is a bearer secret

Treat the sk_ like a password. Anyone with it can create sessions and spend from your account. Never embed in client code, in a mobile app bundle, in a URL, in a public git repo, or in a doc. Rotate immediately if you suspect exposure.

sk_test_ vs sk_live_

	sk_test_	sk_live_
Where it hits	Same api.2wai.ai/v1/* surface	Same
Response shape	Byte-identical	Byte-identical
What it actually runs	Canned responses on test-mode-aware endpoints; real pipeline on others	Real pipeline on everything
Metering	Virtual quota, no account spend	Real metering against your account
Best for	CI, integration tests, dev builds, smoke testing	Production + staging

The gateway decides mode per key, not per request. The two prefixes are just advisory for your own eyes — the actual mode is baked into the key the portal issued.

Expose your own avatars via the developer API

By default, avatars you create in Avatar Studio (the consumer avatar-creation flow) are private to your account and not reachable through api.2wai.ai. To make an avatar available via your developer sk_:

1. Create or open an avatar in Studio at https://2wai.ai/studio.
2. Flip the “API-expose” toggle for that avatar in the Developer Console’s Avatars tab at 2wai.ai/developers/avatars. This writes api_exposed_at on the avatar — the developer-portal gate that lets the API read it.
3. Resolve it from code by handle via GET /v1/avatars/{owner}/{name} — see Catalog hydrate. The response returns the resolved avatar_id you pass to POST /v1/sessions.

Public (listed) avatars on 2wai are reachable with any valid sk_ without this toggle; the toggle only matters for private avatars.

Where the keys live and how they’re billed

• Issuance — the Developer Console at 2wai.ai/developers. SHA-256 hashed in gen-2wai’s gen_developer_key table; the plaintext is shown once and never retrievable.
• Validation — api.2wai.ai (the gateway) checks every sk_ on every request. For keys issued by the Developer Portal, the gateway resolves them via a service-to-service bridge to gen-2wai and lazy-mirrors them locally so repeat requests fast-path.
• Rate + concurrency — see Limits & concurrency. Per-tenant caps enforced at the gateway.
• Spend — real-time metering on sk_live_. Dashboard surfaces are on the Developer Console roadmap.

When you need help

Authentication model How sk_ + participant tokens compose through the mint-proxy pattern.

Rotating or revoking a key Developer Console → Keys. Rotation is a create-new + revoke-old flow.

Expose a Studio avatar Developer Console → Avatars: flip the API-expose toggle per avatar.