Model calls
The gateway speaks the OpenAI chat completions API. Your game holds no key: the play token is the key, for this player, this game and a few minutes.
With the SDK
const reply = await playium.chat({ messages, max_tokens: 200 });
show(reply.text);
const stream = playium.chatStream({ messages, max_tokens: 200 });
for await (const delta of stream) output.textContent += delta.text;max_tokens (or max_completion_tokens) is required on every call. model defaults to the game's default model.
With the openai package
import OpenAI from 'openai';
const openai = new OpenAI(playium.openaiOptions());
const reply = await openai.chat.completions.create({ model: playium.defaultModel, messages, max_tokens: 200 });openaiOptions()setsmaxRetries: 0; keep it that way. The package otherwise retries 408, 409, 429 and 5xx twice, and each attempt is charged to the player.- Name the default model unless we agreed another with you.
GET <gateway>/modelslists the ones you may name. stream: trueworks. Fields passed on:messages,temperature,top_p,max_tokens,max_completion_tokens,stop,presence_penalty,frequency_penalty,seed,n,response_format,tools,tool_choice,parallel_tool_calls,logit_bias,logprobs,top_logprobs,reasoning_effort. Anything else is dropped.- The gateway forwards chat completions to text models. Images, speech and embeddings are not offered yet.
What a call costs
A call is charged to the player after it ends, from the token counts the model reports, at the model's price plus the platform's margin. A short call to a small model costs a few hundredths of a credit; long histories cost the most, because every call pays for the whole prompt again. Upstream failures are not charged; a stream the player abandons is. A call the SDK gave up on after callTimeoutMs (60 seconds; error timeout) may still have finished at the gateway and been charged, so treat it like any failure the player can retry, and never retry it by yourself. In the preview and with dev keys, calls are paid with your own credits.
When the gateway says no
| Status | Code | What your game does |
|---|---|---|
| 401 | invalid_play_token | The SDK gets a new token and tries once more. If that fails too, show it. |
| 402 | insufficient_credits | Say so. The store offers to add credits; try again on unblocked or when the player asks. |
| 403 | purchase_required | The trial of your paid game is used up. The store offers to buy it. |
| 403 | session_limit_reached | The player’s own spending limit for this sitting. The store offers a new session or removing the limit. |
| 403 | game_unavailable | Your game is not available right now. Say so. |
| 404 | model_not_found | Use the default model. |
| 429 | too_many_concurrent_requests | The player has 4 calls running. Wait, then try again on the player’s action. |
| 502, 503 | upstream_error | The provider failed; nothing was charged. Let the player try again. |
| 503 | platform_budget_reached | Model calls are paused for every game. Say the AI is unavailable for now. |
The SDK adds its own codes for calls that got no usable answer (timeout, network, aborted, bad_response, ...): see SDK reference. For every code, playium.describe(error) gives a sentence for the player in the store's ten languages.
Nothing costs credits without the player doing something
No model call on load, none in a loop or on a timer. Setmax_tokens on every call and send only the history the call needs.Next: Cloud saves