@genex-ai/embed-sdk 0.36.0 → 0.38.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +326 -4
- package/dist/{chunk-RAAJ2ZK5.js → chunk-M2KOZMPE.js} +964 -56
- package/dist/{chunk-QBCWKMVQ.js → chunk-YQY2WLAJ.js} +180 -1
- package/dist/development.d.ts +10 -3
- package/dist/development.js +4 -2
- package/dist/index.d.ts +318 -10
- package/dist/index.js +18 -2
- package/dist/{runtime-generation-B3oFDmCp.d.ts → runtime-generation-DhyQ9taA.d.ts} +383 -7
- package/dist/sentry.js +2 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -459,13 +459,46 @@ generateButton.addEventListener('click', async () => {
|
|
|
459
459
|
|
|
460
460
|
Call `generate()` directly inside the click handler: a standalone game must
|
|
461
461
|
reserve a confirmation popup before asynchronous work. Embedded games ask the
|
|
462
|
-
trusted Genex parent to show its modal. Native WebViews
|
|
463
|
-
|
|
464
|
-
|
|
462
|
+
trusted Genex parent to show its modal. Native WebViews return
|
|
463
|
+
`native_unsupported`; a dev server (local test mode) returns
|
|
464
|
+
`local_test_unsupported` unless you practise there, below.
|
|
465
|
+
|
|
466
|
+
### Practise on your dev server
|
|
467
|
+
|
|
468
|
+
On `localhost` there is no player, no wallet and no Genex sheet, so model calls
|
|
469
|
+
answer `local_test_unsupported`. To watch them work before you publish, run the
|
|
470
|
+
practice helper beside your dev server and open the game with the key it prints:
|
|
471
|
+
|
|
472
|
+
```bash
|
|
473
|
+
npx genex llm practice
|
|
474
|
+
# genex llm practice listening on 127.0.0.1:41234 — open your game on its dev server with ?genex_llm_practice=41234.<token>
|
|
475
|
+
```
|
|
476
|
+
|
|
477
|
+
With that key in the page's URL, `getGenerationModels()`, `generate()`,
|
|
478
|
+
`generateStream()`, `judge()`, `requestSpendGrant()`, the budget helpers and the
|
|
479
|
+
voice calls (`getVoiceCatalog()`, `transcribe()`, `speak()`) are
|
|
480
|
+
answered by the helper on your machine, in the same shapes, statuses and error
|
|
481
|
+
codes the published lane returns, so the code you write against it runs
|
|
482
|
+
unchanged when published. Answers are made up and free: text starts with
|
|
483
|
+
`[practice]`, JSON is generated from your `schema`, a stream arrives in pieces,
|
|
484
|
+
a spoken line is a babble about as long as the real one, a recording is heard
|
|
485
|
+
as a stock line, and a budget is approved by the helper and counts a pretend
|
|
486
|
+
credit a call.
|
|
487
|
+
Flags stage the hard cases: `--decline`, `--limit-credits <n>`,
|
|
488
|
+
`--fail <code>`, `--latency <ms>`, `--calls-per-minute <n>`, and
|
|
489
|
+
`--answers <file>` for exact answers (`npx genex llm --help`).
|
|
490
|
+
|
|
491
|
+
Every practice result is marked — `source: 'practice'` on a generation (with
|
|
492
|
+
`modelProvenance: 'unverified'`), a budget, a judge answer and the model list —
|
|
493
|
+
and **authorizes nothing**: never grant a reward, a purchase or a score on it,
|
|
494
|
+
and never read it as what a real model would say or cost. The key works only on
|
|
495
|
+
a page served from `localhost`, `127.0.0.1` or `[::1]`; on a published or test
|
|
496
|
+
build it does nothing. Workflows are not practised.
|
|
465
497
|
|
|
466
498
|
`GenerateOptions` requires `maxCredits` (SDK **0.27.0+**; an integer from 1 to
|
|
467
499
|
1,000,000 — the call's ceiling in the player's credits; `estimateCoins`, its old
|
|
468
|
-
name, is still accepted as the same number), `modelId`, `prompt
|
|
500
|
+
name, is still accepted as the same number), `modelId`, `prompt` (or a `messages` conversation, see
|
|
501
|
+
*A system instruction, a conversation and controls*), `outputFormat: 'text' | 'json'`,
|
|
469
502
|
optional bounded `schema`, `maxOutputTokens` (SDK **0.28.0+**, see *How long a
|
|
470
503
|
call may be*), `allowExternal` (default false), `idempotencyKey`,
|
|
471
504
|
`timeoutMs` (default twenty minutes since 0.28.0; ten before) and `grantId` — a standing budget the player
|
|
@@ -505,6 +538,52 @@ gives a call time in proportion to the output it may write (minutes for the
|
|
|
505
538
|
longest answers), so the default wait is twenty minutes; answers that take
|
|
506
539
|
minutes are best streamed (`generateStream()`).
|
|
507
540
|
|
|
541
|
+
### A system instruction, a conversation and controls
|
|
542
|
+
|
|
543
|
+
A call may be more than one prompt: your game's own `system` instruction, a
|
|
544
|
+
`messages` conversation, and controls for the model.
|
|
545
|
+
|
|
546
|
+
```ts
|
|
547
|
+
const reply = await generate({
|
|
548
|
+
modelId, outputFormat: 'text', maxCredits: benchmarkedCeiling, grantId,
|
|
549
|
+
system: 'You are Marn, the gate guard. Short, wary answers.',
|
|
550
|
+
messages: history, // [{ role: 'user' | 'assistant', content }, …]
|
|
551
|
+
prompt: playerLine, // the last user turn
|
|
552
|
+
temperature: 0.8,
|
|
553
|
+
reasoningEffort: 'low',
|
|
554
|
+
cacheSystem: true,
|
|
555
|
+
});
|
|
556
|
+
```
|
|
557
|
+
|
|
558
|
+
- `messages` are `user` / `assistant` turns of plain text, alternating from
|
|
559
|
+
`user`. With a `prompt` they end on an assistant turn (the prompt is the last
|
|
560
|
+
user turn); without one they end on a user turn. Anything else — another
|
|
561
|
+
role, a content part, an extra key — is `invalid_messages`, refused before
|
|
562
|
+
the popup and the network.
|
|
563
|
+
- `temperature` (0–2), `topP` (0–1), `stop` (a few short strings), `seed` and
|
|
564
|
+
`reasoningEffort` (`'none' | 'low' | 'medium' | 'high'`) each need a model
|
|
565
|
+
that takes them: `getGenerationModels().models[i].controls` lists them (and
|
|
566
|
+
`reasoningEfforts` the values), and one the model does not list is
|
|
567
|
+
`unsupported_parameter` — nothing is charged. Reasoning tokens count against
|
|
568
|
+
the answer's length: if a thinking model is cut off (`provider_token_limit`),
|
|
569
|
+
ask for `'low'` or `'none'`, or a larger ceiling.
|
|
570
|
+
- `cacheSystem: true` marks a long, unchanging `system` as a cacheable prefix
|
|
571
|
+
where the vendor needs to be told; it does nothing elsewhere. Calls are billed
|
|
572
|
+
as used, so a cached read simply costs less.
|
|
573
|
+
- Everything you send — prompt, system and every turn — fits
|
|
574
|
+
`limits.maxPromptBytes` together, and is part of what the call costs:
|
|
575
|
+
benchmark the real call (`genex llm bench --system … --messages …`).
|
|
576
|
+
|
|
577
|
+
**It works on every stand.** A stand accepts these fields when
|
|
578
|
+
`getGenerationModels().features?.messages` is `true`. Where it is not — an
|
|
579
|
+
older stand, or one with the feature off — the SDK still runs the call: it
|
|
580
|
+
folds `system`, `messages` and `prompt` into one prompt and drops the controls.
|
|
581
|
+
`foldGenerationRequest({ system, messages, prompt })` returns that exact text
|
|
582
|
+
(`Instructions:` … `Conversation:` … `Answer the last User message as the
|
|
583
|
+
Assistant.`); it is also what a player's own Claude or ChatGPT plan is handed,
|
|
584
|
+
where the controls are likewise not used (`ignoredControls` on the view says
|
|
585
|
+
which). Do not reuse an idempotency key across the two shapes.
|
|
586
|
+
|
|
508
587
|
SDK **0.21.0+** returns the execution `status`, optional `generationId`, and
|
|
509
588
|
`output` plus `source` on success. Cancellation is a normal `canceled` result,
|
|
510
589
|
but it does not imply that consumed work was free. `pending` with
|
|
@@ -695,6 +774,29 @@ sentence for every one of these and for every one-time code as well; show it, or
|
|
|
695
774
|
write your own in-fiction line keyed off the same code. Never show the raw code,
|
|
696
775
|
and never treat `unknown` as failure — it means the outcome is not settled yet.
|
|
697
776
|
|
|
777
|
+
**When what was said isn't allowed.** A stand can check what a game sends to a
|
|
778
|
+
model and what the model answers (`(await getGenerationModels()).features?.moderation`
|
|
779
|
+
is `'enforce'` where it blocks; absent or `'off'`/`'log'` where it does not). A
|
|
780
|
+
blocked call resolves `failed` with `error: 'content_blocked'` and
|
|
781
|
+
`contentBlocked: 'input' | 'output'` — one-time, budget and streamed calls
|
|
782
|
+
alike:
|
|
783
|
+
|
|
784
|
+
```ts
|
|
785
|
+
const reply = await generate({ ...request, grantId });
|
|
786
|
+
if (reply.error === 'content_blocked') {
|
|
787
|
+
// 'input': what the player (or the game) sent was refused before the model
|
|
788
|
+
// ran, at no charge. 'output': the model's answer was withheld; the attempt
|
|
789
|
+
// is charged like any failed one.
|
|
790
|
+
showNotice(generationErrorMessage(reply.error)); // or your own in-fiction line
|
|
791
|
+
if (reply.contentBlocked === 'input') clearTheTextBox();
|
|
792
|
+
}
|
|
793
|
+
```
|
|
794
|
+
|
|
795
|
+
Do not resend the same text: it will be refused again. Violence and dark themes
|
|
796
|
+
inside a game's fiction are not blocked. In a stream, pieces may stop arriving
|
|
797
|
+
before the result says so — as always, the resolved result decides what the
|
|
798
|
+
game keeps, never the pieces.
|
|
799
|
+
|
|
698
800
|
**The receiver pattern.** Persistence is the game's job, and it is what decides
|
|
699
801
|
whether a generated thing survives a reload:
|
|
700
802
|
|
|
@@ -710,6 +812,110 @@ and something that survives a reload. Validate `result.output` against the shape
|
|
|
710
812
|
your game expects before using it, always. It is data, never authority for
|
|
711
813
|
Nex, rewards or items.
|
|
712
814
|
|
|
815
|
+
## Budgets the game's creator pays for
|
|
816
|
+
|
|
817
|
+
A standing budget is normally the player's money, so the player approves it.
|
|
818
|
+
A game whose **creator** has set an allowance aside (`genex llm sponsor set`,
|
|
819
|
+
their own credits, for this one game) can ask for a budget the creator pays
|
|
820
|
+
instead — and then nobody is asked anything:
|
|
821
|
+
|
|
822
|
+
```ts
|
|
823
|
+
import { requestSpendGrant, generate } from '@genex-ai/embed-sdk';
|
|
824
|
+
|
|
825
|
+
// No click needed and no Genex sheet: nobody playing is paying.
|
|
826
|
+
const sponsored = await requestSpendGrant({
|
|
827
|
+
sponsored: true,
|
|
828
|
+
models: ['google/gemini-2.5-flash-lite'],
|
|
829
|
+
perCallMaxCredits: 3,
|
|
830
|
+
});
|
|
831
|
+
if (sponsored.status === 'active') {
|
|
832
|
+
const line = await generate({ grantId: sponsored.grantId, maxCredits: 3, modelId: 'google/gemini-2.5-flash-lite', prompt, outputFormat: 'text' });
|
|
833
|
+
} else if (sponsored.status === 'unavailable') {
|
|
834
|
+
// The creator's allowance cannot serve this player right now. Nothing was
|
|
835
|
+
// asked of the player and nothing is charged. Fall back — your choice:
|
|
836
|
+
// authored content, or the player-paid request above (from a click).
|
|
837
|
+
}
|
|
838
|
+
```
|
|
839
|
+
|
|
840
|
+
- The answer is **`active`** or **`unavailable`** (`failed` only for a
|
|
841
|
+
malformed request). `unavailable` carries `error`, a code:
|
|
842
|
+
`sponsor_not_available` (this game has no live allowance, or the stand does
|
|
843
|
+
not serve them), `sponsor_terms_mismatch` (you asked for a model or a
|
|
844
|
+
ceiling the creator did not allow), `sponsor_player_limit_reached` (this
|
|
845
|
+
player's allowance for today is used; it resets at 00:00 UTC),
|
|
846
|
+
`sponsor_exhausted`, `sponsor_rate_limited`, `sponsor_sign_in_required` (a
|
|
847
|
+
guest, where guests are not served), `sponsor_email_unverified`. A player is
|
|
848
|
+
**never** switched to paying: falling back to a player-paid budget is a
|
|
849
|
+
decision your game makes, in the open, from a click.
|
|
850
|
+
- It works on an older stand too: the SDK reads the stand's `features` (served
|
|
851
|
+
by `getGenerationModels()`) and answers `unavailable` itself, without a
|
|
852
|
+
network error, where sponsored budgets are not served.
|
|
853
|
+
- Ask for only what the game needs: `models` and `perCallMaxCredits` (and
|
|
854
|
+
`judge: { enabled: true, … }`, `maxCallsPerMinute`). The limit is the
|
|
855
|
+
server's — what is left of this player's day — and the pace is at most the
|
|
856
|
+
creator's. The other budget options are accepted and ignored, so the same
|
|
857
|
+
options object can serve the fallback.
|
|
858
|
+
- Asking again returns the budget already running, so ask on every load; there
|
|
859
|
+
is nothing to store. `getActiveSpendGrant()` is the player's OWN budget and
|
|
860
|
+
never returns a sponsored one.
|
|
861
|
+
- Calls then run exactly like any budget's — `generate({ grantId })`,
|
|
862
|
+
`generateStream()`, `judge()` — and can still be refused: by the budget's
|
|
863
|
+
own limits (`grant_limit_reached` is this player's day used up), and when
|
|
864
|
+
the allowance ends (`sponsor_exhausted`, `sponsor_stopped`,
|
|
865
|
+
`sponsor_expired`). Treat any of them as "fall back".
|
|
866
|
+
- Credits only: a sponsored budget is never offered the player's own Claude or
|
|
867
|
+
ChatGPT plan, and never falls back to the player's credits.
|
|
868
|
+
- Guests (no account) are served only where the stand allows it
|
|
869
|
+
(`features.sponsorGuests`) and the creator opted in; elsewhere the answer is
|
|
870
|
+
`unavailable` with `sponsor_sign_in_required`.
|
|
871
|
+
## Shared AI in a multiplayer room
|
|
872
|
+
|
|
873
|
+
A server-authoritative room module can ask a model itself (`ctx.models` in
|
|
874
|
+
`@genex-ai/multiplayer/authority/module`): an AI referee, an NPC's decision, a
|
|
875
|
+
storyteller the whole room hears. It runs on the server, so no player's tab
|
|
876
|
+
has to stay open and no client can forge the answer. The server carries no key
|
|
877
|
+
and no wallet. Its calls are paid from the budgets the players in the room
|
|
878
|
+
**lend** it (SDK **0.37.0+**):
|
|
879
|
+
|
|
880
|
+
```ts
|
|
881
|
+
import { getGenerationModels, requestSpendGrant, lendSpendGrantToRoom, returnSpendGrantFromRoom } from '@genex-ai/embed-sdk';
|
|
882
|
+
import { connectAuthority } from '@genex-ai/multiplayer/authority';
|
|
883
|
+
|
|
884
|
+
// Only where this stand has it: ask, never assume.
|
|
885
|
+
const { features } = await getGenerationModels();
|
|
886
|
+
const shared = features?.roomCalls === true;
|
|
887
|
+
|
|
888
|
+
// From a click, as always. `shareWithRooms` adds one sentence to the sheet.
|
|
889
|
+
const budget = await requestSpendGrant({
|
|
890
|
+
models: ['your-configured-model-id'],
|
|
891
|
+
perCallMaxCredits: 3,
|
|
892
|
+
disclosure: { periodLabel: 'hour', estimatedCallsPerPeriod: 60, estimatedCreditsPerPeriod: 120 },
|
|
893
|
+
...(shared ? { shareWithRooms: true } : {}),
|
|
894
|
+
});
|
|
895
|
+
|
|
896
|
+
const session = await connectAuthority({ room: 'my-game', name: 'Blue' });
|
|
897
|
+
if (shared && budget.status === 'active' && budget.grantId) {
|
|
898
|
+
await lendSpendGrantToRoom(budget.grantId, session.code); // this room, this player's budget
|
|
899
|
+
}
|
|
900
|
+
```
|
|
901
|
+
|
|
902
|
+
- A budget approved **without** `shareWithRooms` can never be spent by a
|
|
903
|
+
server: `lendSpendGrantToRoom()` rejects with `grant_not_shareable`. On a
|
|
904
|
+
stand without room calls, `requestSpendGrant({ shareWithRooms: true })`
|
|
905
|
+
resolves `failed` with `room_calls_unavailable` and shows the player nothing.
|
|
906
|
+
- Every call the room makes is an ordinary call of that budget: the same
|
|
907
|
+
per-call ceiling, limit and pace the player approved, billed as used, on
|
|
908
|
+
their receipts, marked there as asked for by the game's server.
|
|
909
|
+
- The room spreads its calls across the players who lent a budget. A player
|
|
910
|
+
who lends nothing pays nothing, and a room nobody lends to reads `no_budget`
|
|
911
|
+
in the module, which must have a rule of its own for that.
|
|
912
|
+
- A lend ends when the player leaves the room, stops the budget or signs out;
|
|
913
|
+
`returnSpendGrantFromRoom(grantId, session.code)` ends it on a switch of
|
|
914
|
+
yours. A deploy moves a seat to a new room by itself: lend again there,
|
|
915
|
+
`session.on('rejoined', ({ code }) => lendSpendGrantToRoom(grantId, code))`.
|
|
916
|
+
- A budget on the player's own Claude or ChatGPT plan cannot be lent
|
|
917
|
+
(`room_funding_unsupported`).
|
|
918
|
+
|
|
713
919
|
## Streaming replies
|
|
714
920
|
|
|
715
921
|
SDK **0.26.0+**. `generateStream()` is `generate({ grantId })` answered as it is
|
|
@@ -839,6 +1045,119 @@ Benchmark on your own credits with `developmentJudge()` from
|
|
|
839
1045
|
billed one whole credit a call — a player's budget, which meters, spends far
|
|
840
1046
|
less for the same calls.
|
|
841
1047
|
|
|
1048
|
+
## Voice
|
|
1049
|
+
|
|
1050
|
+
SDK **0.38.0+**. The game can **hear the player** and **talk back**. `transcribe()` turns a
|
|
1051
|
+
recording into words; `speak()` says a line in one of Genex's voices, streamed
|
|
1052
|
+
while it is made; `createSpeaker()` plays lines back to back, and can speak a
|
|
1053
|
+
model's reply while `generateStream()` is still writing it. Each is a call
|
|
1054
|
+
under a standing budget, billed as used on its meter like `judge()` (never a
|
|
1055
|
+
credit of its own), so voice is **grant-only**: ask for it when you request the
|
|
1056
|
+
budget. A voice budget is paid from the player's Genex credits, and the sheet
|
|
1057
|
+
names every company the player's voice or the game's lines are sent to.
|
|
1058
|
+
**Genex stores no audio**: a recording is passed to the transcription provider
|
|
1059
|
+
and dropped, and a spoken line is streamed and never kept.
|
|
1060
|
+
|
|
1061
|
+
```ts
|
|
1062
|
+
import { getVoiceCatalog, requestSpendGrant, createVoiceRecorder, transcribe, generateStream, createSpeaker,
|
|
1063
|
+
generationErrorMessage } from '@genex-ai/embed-sdk';
|
|
1064
|
+
|
|
1065
|
+
const catalog = await getVoiceCatalog();
|
|
1066
|
+
if (!catalog.enabled) return useTypedInput(); // no voice here: typing still works
|
|
1067
|
+
|
|
1068
|
+
// From the player's click, as every budget request.
|
|
1069
|
+
const tier = catalog.speech.models[0]!.tier; // tiers and voices come from the catalog
|
|
1070
|
+
const voice = catalog.speech.voices.find((v) => v.tiers.includes(tier))!.id;
|
|
1071
|
+
const budget = await requestSpendGrant({
|
|
1072
|
+
models: [model.id],
|
|
1073
|
+
perCallMaxCredits: 8, perCallEstimateCredits: 2,
|
|
1074
|
+
disclosure: { periodLabel: 'minute', estimatedCallsPerPeriod: 4, estimatedCreditsPerPeriod: 8 },
|
|
1075
|
+
voice: {
|
|
1076
|
+
speech: { tiers: [tier], estimatedCharactersPerPeriod: 1200 }, // the game speaks
|
|
1077
|
+
transcription: { estimatedSecondsPerPeriod: 60 }, // the game listens
|
|
1078
|
+
},
|
|
1079
|
+
});
|
|
1080
|
+
const grantId = budget.grantId!;
|
|
1081
|
+
|
|
1082
|
+
const recorder = createVoiceRecorder({ onLevel: (level) => micMeter.set(level) });
|
|
1083
|
+
const speaker = createSpeaker({ grantId, voice, maxCharacters: catalog.limits.speech.maxCharacters,
|
|
1084
|
+
onLineStart: (line) => subtitle.show(line.text),
|
|
1085
|
+
onLineEnd: (line) => { if (line.error) showNotice(generationErrorMessage(line.error)); } });
|
|
1086
|
+
|
|
1087
|
+
talk.onpointerdown = () => recorder.start().catch((error) => showNotice(generationErrorMessage(error.code)));
|
|
1088
|
+
talk.onpointerup = async () => {
|
|
1089
|
+
const audio = await recorder.stop().catch(() => null); // `not_recording`: the start was refused
|
|
1090
|
+
if (!audio) return;
|
|
1091
|
+
const heard = await transcribe({ grantId, audio });
|
|
1092
|
+
if (heard.status !== 'succeeded') return showNotice(generationErrorMessage(heard.error));
|
|
1093
|
+
if (!heard.text) return; // nobody spoke
|
|
1094
|
+
await generateStream({ grantId, modelId: model.id, prompt: heard.text, outputFormat: 'text', maxCredits: 8,
|
|
1095
|
+
onDelta: (piece) => speaker.feed(piece) }); // each sentence is spoken as it closes
|
|
1096
|
+
await speaker.end(); // the rest, then wait until it has played
|
|
1097
|
+
};
|
|
1098
|
+
```
|
|
1099
|
+
|
|
1100
|
+
- **Cast from the catalog.** `getVoiceCatalog()` lists the voices (a one-line
|
|
1101
|
+
description to cast from, a gender, and the tiers that can speak each), one
|
|
1102
|
+
speech model per tier (`premium`, `standard`, `economy`: a game names a
|
|
1103
|
+
tier, never a vendor), the transcription models, the limits (characters per
|
|
1104
|
+
line, seconds per recording) and estimated prices. Never type a voice id or a
|
|
1105
|
+
tier from memory. It answers `{ enabled: false }` wherever voice cannot run (a
|
|
1106
|
+
stand without it, local test mode without the practice helper, the app, an
|
|
1107
|
+
untrusted frame, no player) and never throws. Keep typed input as the
|
|
1108
|
+
fallback: a player may refuse the microphone, have none, or play where voice
|
|
1109
|
+
is off.
|
|
1110
|
+
- **Push to talk.** `createVoiceRecorder({ maxSeconds?, onLevel?, deviceId? })`:
|
|
1111
|
+
`start()` on the press asks for the microphone, `stop()` on the release
|
|
1112
|
+
resolves a 16 kHz mono WAV `Blob`, `cancel()` throws it away. It stops itself
|
|
1113
|
+
at `maxSeconds` (default 30, at most 60) and the next `stop()` returns that
|
|
1114
|
+
recording. A failure rejects with `error.code` `microphone_denied`,
|
|
1115
|
+
`microphone_unavailable` or `not_recording`. The microphone and the audio
|
|
1116
|
+
graph are let go on stop, cancel and the cut-off. On its Genex page a game is
|
|
1117
|
+
given the microphone only when its build declares it: add
|
|
1118
|
+
`"genex": { "capabilities": ["microphone"] }` to `package.json`.
|
|
1119
|
+
- **`transcribe({ grantId, audio, language?, model?, idempotencyKey?, signal? })`**
|
|
1120
|
+
takes one 16-bit PCM WAV (anything else is `audio_invalid`, before the
|
|
1121
|
+
network) and resolves `text` (`''` when nobody spoke), `language`,
|
|
1122
|
+
`durationMs` and `billing`. Reuse `idempotencyKey` to retry the same recording
|
|
1123
|
+
without paying twice; `pending` with `wait_timeout` means that call is still
|
|
1124
|
+
running: send it again with the same key to read its answer.
|
|
1125
|
+
- **`speak({ grantId, text, voice, tier?, style?, language?, onStart?, onAudio?, signal? })`**
|
|
1126
|
+
streams 16-bit PCM (24 kHz mono; `onStart` names the format) and resolves the
|
|
1127
|
+
line's receipt with all of its audio (`audio`, `wav()`). A spoken line is
|
|
1128
|
+
never replayed: its key is used once, and a reused one is
|
|
1129
|
+
`idempotency_conflict`. A stream that is cut resolves `unknown` with
|
|
1130
|
+
`provider_outcome_unknown` and the audio that arrived; `signal` stops the
|
|
1131
|
+
reading (`request_aborted`), and the line is still made and charged.
|
|
1132
|
+
- **`createSpeaker({ grantId, voice, tier?, style?, language?, onLineStart?, onLineEnd?, maxCharacters? })`**
|
|
1133
|
+
queues lines (`say(text)`) or a streamed reply (`feed(delta)` then `end()`),
|
|
1134
|
+
one request at a time and in order, each made while the one before it plays,
|
|
1135
|
+
so speech has no gaps. A line past `maxCharacters` is split at sentence ends,
|
|
1136
|
+
then at spaces. A line that fails (`grant_limit_reached`, `voice_busy`, …) is
|
|
1137
|
+
reported through `onLineEnd` and the queue moves on; `stop()` silences at once
|
|
1138
|
+
and drops the queue, and each dropped line ends `canceled` with
|
|
1139
|
+
`game_stopped`. **Browsers play audio only after the player has interacted
|
|
1140
|
+
with the page**: create the speaker, or call `say()`, from a click or a key
|
|
1141
|
+
press.
|
|
1142
|
+
|
|
1143
|
+
The refusals to handle as game states: `voice_requires_grant` (no budget),
|
|
1144
|
+
`voice_not_enabled` (the budget was approved without voice, or without the half
|
|
1145
|
+
this call needs: request a new one), `voice_requires_credits`,
|
|
1146
|
+
`voice_not_found` (a voice that is not in the catalog or not on that tier),
|
|
1147
|
+
`voice_busy` and `voice_paused` (the platform's, retry later), `text_too_long`,
|
|
1148
|
+
`audio_invalid`, `audio_too_long`, `audio_too_short`, and every budget code
|
|
1149
|
+
above. `generationErrorMessage()` has a sentence for each.
|
|
1150
|
+
|
|
1151
|
+
The wire, for other clients: `GET /api/runtime/voice` is the catalog (404 where
|
|
1152
|
+
the stand has no voice). `POST /api/runtime/grants/:id/transcriptions` takes the
|
|
1153
|
+
WAV bytes as its body (`Content-Type: audio/wav`), an `Idempotency-Key` header
|
|
1154
|
+
and optional `language` and `model` query parameters, and answers JSON.
|
|
1155
|
+
`POST /api/runtime/grants/:id/speech` takes
|
|
1156
|
+
`{ idempotencyKey, text, voice, tier?, style?, language? }` and answers
|
|
1157
|
+
`text/event-stream`: one `start` `{ generationId, encoding, sampleRate, channels }`,
|
|
1158
|
+
`audio` `{ data }` events (base64 PCM, whole samples, in order) and one `done`
|
|
1159
|
+
carrying the receipt. Both take the embed token as a bearer.
|
|
1160
|
+
|
|
842
1161
|
## Your subscription and the Genex player watcher
|
|
843
1162
|
|
|
844
1163
|
Both approval sheets can offer the player their own Claude or ChatGPT plan
|
|
@@ -1003,6 +1322,9 @@ const receipt = await developmentGenerate({
|
|
|
1003
1322
|
prompt: 'Invent a friendly creature name.',
|
|
1004
1323
|
outputFormat: 'text',
|
|
1005
1324
|
// maxOutputTokens: 24_000, // 0.28.0+: bench exactly what the game will ask for
|
|
1325
|
+
// system, messages, temperature, reasoningEffort, …: sent as given — a stand
|
|
1326
|
+
// without `features.messages` answers `invalid_request` rather than
|
|
1327
|
+
// measuring a different call.
|
|
1006
1328
|
idempotencyKey: 'calibration-sample-001',
|
|
1007
1329
|
},
|
|
1008
1330
|
});
|