First prediction

1. Create a sandbox app

Open the free sandbox, create an app and save its one-time clnp_ key as CLONE_APP_KEY on your backend. No card is required. The sandbox includes 1,000 suggestions, shared across your developer account.

2. Make a prediction

Run this in a server-side shell with CLONE_APP_KEY set. Replace the example user_id with the user ID from your product's authenticated session. Never expose the key in a browser or trust a browser-supplied user ID.

curl --fail-with-body --max-time 15 https://api.clone.is/v1/predictions \
  -H "Authorization: Bearer $CLONE_APP_KEY" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "request_id": "first-prediction-001",
    "user_id": "your-authenticated-user",
    "session_id": "thread-001",
    "mode": "next_prompt",
    "draft": { "text": "", "revision": 0 },
    "context_revision": "1",
    "messages": [
      { "role": "user", "content": "Draft a launch announcement." },
      { "role": "assistant", "content": "Here is an introduction and invitation to try it." }
    ]
  }'

Use a fresh request_id for each new input. To recover an unknown outcome after a timeout, replay the same ID and identical body. An account management token (cl_) cannot replace the runtime app key (clnp_).

3. Read the response

The API returns complete JSON. A suggested result contains text your product can show for review. This is an illustrative response; IDs, expiry and wording vary:

{
  "request_id": "first-prediction-001",
  "prediction_id": "prediction-example",
  "session_id": "thread-001",
  "connection_id": null,
  "draft_revision": 0,
  "context_revision": "1",
  "profile_revision": "",
  "grant_revision": 0,
  "status": "suggested",
  "completion": "Make it more concise and add a clear call to action.",
  "expires_at": 1790812860,
  "context_truncated": false,
  "usage": { "prediction_units": 1 }
}

expires_at is Unix time in seconds. Check that the response is unexpired and that its request, session, draft, context and connection identities still match before displaying it. The example expiry above is a placeholder, not a reusable live result.

When Clone has no suitable suggestion, the response has the same identity fields with these values:

{
  "status": "abstained",
  "completion": "",
  "usage": { "prediction_units": 0 }
}

On abstention or error, show no suggestion. Keep normal typing and sending available. For draft completion, use mode: "complete_draft" with nonempty draft.text. See the API reference for optional context and exact response fields.

4. Connect your product

Use the SDK quickstart for React or a headless composer. With a custom interface, keep prediction requests separate from your normal send path and reject old responses after edits or account switches.

Test typing, edits, cancellation and outage behavior with deterministic fixtures first. Then verify a small number of real requests in your sandbox and in your actual composer. See reliability and limits.

5. Go to production

Review API pricing, then open production setup. The customer accepts billing terms and adds the company card. Card registration does not charge usage; production predictions are billed monthly. The sandbox does not upgrade automatically. See billing for invoices, budgets and hard limits.