SDK quickstart

Run a local composer example, then connect your backend to Clone.

On this page

1. Run the local example

Use Node.js 22.13 or later. In a new, empty directory, download the public npm package and create the example:

npm pack @clone-ai/prompt-prediction@0.8.0
mkdir sdk-release
tar -xzf clone-ai-prompt-prediction-0.8.0.tgz -C sdk-release
node sdk-release/package/scripts/create-example.mjs \
  ./composer ./clone-ai-prompt-prediction-0.8.0.tgz
cd composer
npm install
npm run dev

Open http://127.0.0.1:4317. The example uses local fixtures by default: no app key, card or API calls. Focus the composer, accept a suggestion with Tab, edit it, then send. The generated project includes the React composer and a local backend example.

npm checks the registry package integrity when downloading. Checksum-verified GitHub release archives remain available.

2. Prepare your product

Create an app in the free sandbox and keep its runtime key on your backend. Install the JavaScript package in your frontend and, for a JS/TS server, your backend:

npm install --save-exact @clone-ai/prompt-prediction@0.8.0

For a Python 3.11+ backend:

python -m pip install clone-sdk==0.3.0

Commit your lockfile. The example's local fixture identity is for development only; replace it with your product's authenticated session. Never put an app key in a browser bundle or public environment variable.

3. Add an authenticated proxy

Your product provides /api/clone/predict. Authenticate the product's user, derive their user_id from the server session, validate the request, and call Clone from your backend. Apply your product's rate and usage limits. Never trust a browser-provided user ID.

For JS/TS servers:

import { CloneClient } from '@clone-ai/prompt-prediction/server';

const clone = new CloneClient({
  apiKey: process.env.CLONE_APP_KEY!,
  baseUrl: 'https://api.clone.is',
  requestTimeoutMs: 15000,
  maxConcurrentRequests: 16,
});

// Inside your authenticated server handler:
// body is the validated prediction request; signal cancels abandoned work.
const result = await clone.predict(authenticatedUser.id, body, { signal });

For async Python servers:

import os
from clone_sdk import AsyncCloneClient

clone = AsyncCloneClient(os.environ["CLONE_APP_KEY"])

# Inside your authenticated server handler:
result = await clone.predict(authenticated_user.id, body)

Reuse one client for the backend's lifetime and close it at shutdown. Sync servers can use CloneClient. Keep composer UI in the JavaScript SDK. See the Python guide.

Forward the result to the composer. The HTTP quickstart shows the complete request shape; the API reference covers identity and error handling. See the full integration guide for backend and editor wiring.

4. Connect your composer

Use your product's draft state and current conversation context. Define the transport once, outside the render function:

import { TabCompletionInput } from '@clone-ai/prompt-prediction/react';
import { createPredictionTransport } from '@clone-ai/prompt-prediction';

const transport = createPredictionTransport('/api/clone/predict');

// Inside your existing composer:
<TabCompletionInput
  value={draft}
  onValueChange={setDraft}
  context={context}
  transport={transport}
  presentation="instant"
/>

This excerpt connects your existing app; the standalone example above shows the complete wiring. Leave the frontend deadline unset to use the SDK defaults: 15 seconds for text and 180 seconds for image or original video/audio predictions. An explicit short controller deadline also limits media requests. Keep your existing send handler independent of prediction requests. Tab inserts; your normal send control submits. Custom editors can use CompletionController or useTabCompletion instead of replacing the editor.

5. Choose your experience

An installation agent should inspect the framework, routes and authentication in your repository. Ask the customer only about unresolved product choices: suggestion triggers, instant or typewriter presentation, product context or optional Connect Clone, whether to expose Clone mode, its limits, and rollout controls. Preserve choices already supplied.

Presentation and input behavior: complete text by default, optional typewriter display.
Personalization: product-owned context and optional, explicit Clone sharing.
Clone mode: user-started, bounded automatic sends. Off unless explicitly enabled.

6. Verify before rollout

Use deterministic fixtures to check typing, IME composition, Tab insertion, edit-before-send, dismissal, old responses, timeout and API outage. Test in the actual customer composer. Typing and sending must remain usable when predictions fail.

After that, verify a few real requests with your sandbox app. Before production, review pricing and complete production setup. The customer accepts billing terms and enters the card. Keep fixture results, live API results and customer-composer verification separate. See reliability and limits.

← All guides API reference →