AI inference

Apps with the ai_inference scope can run text completions on the Stayblox AI platform. Calls are billed to the store's monthly AI credits, so you can ship AI features without running your own model infrastructure. Every call is attributed to your app, and hosts can set a monthly credit cap per app.

Requesting the scope

Add ai_inference to your app's scopes. Hosts see it as "Run AI on your credits" when they install or review your app. Adding the scope to a published app triggers a new review.

Generating text

Compose your own context into the prompt. The API is stateless: no conversation memory, no tools.

mutation {
  aiGenerate(input: {
    system: "You are a short and factual pricing analyst."
    prompt: "Given these bookings ... suggest a weekend price."
    model: "gpt-4.1-mini"
    maxOutputTokens: 1024
  }) {
    text
    usage { inputTokens outputTokens creditsCharged }
    userErrors { field message code }
  }
}

model is optional. Query aiModels { key isDefault } for the models you can request. maxOutputTokens above the platform ceiling is clamped, not rejected.

Billing

Calls consume the store's AI credits. usage.creditsCharged reports the exact fractional credits for each call. Your app never sees the store's remaining balance; handle the error codes below and degrade gracefully.

Error codes

Failed calls return userErrors with a machine readable code:

Code	Meaning
AI_UNAVAILABLE	The store's plan does not include AI.
INSUFFICIENT_CREDITS	The store has no AI credits left this month.
INSTALL_CAP_EXCEEDED	The host capped your app's monthly AI usage and the cap is reached.
MODEL_UNAVAILABLE	The requested model is not available. Pick one from aiModels.
PROMPT_TOO_LONG	The prompt exceeds the maximum length.
RATE_LIMITED	Too many requests. Retry after a short pause.
GENERATION_FAILED	The provider failed. Nothing was charged. Retry is safe.

A failed call never charges credits.

Host controls

Hosts see your app's AI usage for the current month on the app's settings page and can set a monthly credit cap there. Design your feature so a capped or credit-exhausted store still works without AI.