Add AI to your app

1. Check that the app has AI. In the project, open Settings, choose Secrets and look for PLAYCODE_AI_URL, marked Managed. If it is missing, ask the agent to switch on AI for the app: it adds the setting and restarts the app.

2. Call the model from the app's backend. A new Cloud app has an AI service in backend-nest/src/ai/: complete() answers with text, and stream() answers while the model writes.

   import { Injectable } from '@nestjs/common'
   import { AiService } from '../ai'
   
   @Injectable()
   export class DescriptionService {
     constructor(private readonly ai: AiService) {}
   
     write(product: string): Promise<string> {
       return this.ai.complete({
         system: 'Write a two-sentence product description. Plain text only.',
         prompt: product,
       })
     }
   }
   

3. Give the feature an endpoint of its own in the backend, with a sign-in check, and call that endpoint from the page. The browser never calls Playcode AI Gateway and never sees the key.

4. Try the feature once. In Settings, Usage, the project's AI Gateway row counts the requests, with their calls and tokens.

Your app names a model by its id. The AI service uses claude-haiku-4-5-20251001 unless you pass another, like claude-sonnet-5 for harder tasks. Ask the agent which models your app can use: it reads the current list and prices from Playcode.

The gateway speaks each model maker's own interface, so their official SDKs work with two changes: PLAYCODE_SECRET_KEY as the SDK's apiKey, and Playcode's address as its base URL. Claude models use the Anthropic SDK at PLAYCODE_AI_URL plus /anthropic; other models use the OpenAI SDK at PLAYCODE_AI_URL plus /openai.

import Anthropic from '@anthropic-ai/sdk'

const client = new Anthropic({
  apiKey: process.env.PLAYCODE_SECRET_KEY,
  baseURL: process.env.PLAYCODE_AI_URL + '/anthropic',
})

The workspace is out of credits. Add credits; do not retry the request in a loop.

The credits ran out while the model was answering. The text that arrived was delivered and billed.

A request limit was reached. The error body's playcode part says which limit refused and what remains. Wait, then try once more.

Playcode does not offer that model id through this SDK, or the id is misspelled. Ask the agent for the list.

The app's key cannot use AI yet. Ask the agent to switch on AI for the app: it renews the key and restarts the app.

The app uses an old key. A PLAYCODE_SECRET_KEY line in the project's .env.local file can hide the current one: remove that line. See Secrets and environment.

The model's own provider refused the request, for example for a wrong parameter or an input that is too long. Fix the request.

• AI needs a Cloud app. A static site has no server to keep the key.
• The key works only through Playcode AI Gateway. It is not a key for a model maker's own API.
• Model ids pass through unchanged, with no aliases. A model that is not in Playcode's list is refused.
• The models on offer and their prices change over time. Ask the agent before you choose.
• Requests pause when the workspace's credits run out. See Credits and balance.