First prediction

Choose the API or SDK

Use the HTTPS API from any backend when you need your own interface or execution flow. Use the Clone SDK quickstart for React ghost text, keyboard handling and a headless controller. They call the same prediction service and use the same app key and billing.

1. Register and prepare billing

Open production onboarding. Create or reuse your company account and app, save the one-time app key on your backend, then review pricing and add your company card. No charge at card registration. The console verifies activation before offering installation.

For evaluation, explicitly choose the free sandbox. Its 1,000 suggestions are shared across the account's apps. No card or automatic upgrade. Customer billing consent and card entry are completed by the customer, never silently by their agent.

2. Make a server-side request

Keep CLONE_APP_KEY in your server's secret store. A runtime key starts with clnp_. An account management token (cl_) cannot replace it. Your product's authenticated session supplies user_id; do not trust an arbitrary browser field.

Save this as prediction.json. Use a fresh request_id for a new input; reuse the same ID and identical body when resolving an unknown outcome.

{
  "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": "Help me edit this product introduction.", "origin": "human" },
    { "role": "assistant", "content": "The introduction is ready for review.", "origin": "agent" }
  ],
  "artifact": { "kind": "video", "id": "intro", "revision": "1", "summary": "A 30-second product introduction with three scenes." },
  "user_preferences": "Prefer concise suggestions in English.",
  "language": "en"
}

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 @prediction.json

No React, Node runtime, Clone end-user account or connected sources are required by the HTTP API. For draft completion, use mode: "complete_draft" and a nonempty draft.text. Preserve the revision in the response when deciding whether to display a candidate.

3. Use the result

status: "suggested" contains the complete completion and expires at expires_at (Unix seconds). status: "abstained" means show nothing. This is JSON, not a token stream. Reject mismatched request, session, draft, context or connection identities. Never display an old response after an edit or account switch.

Do not wait for Clone in the normal send path. A failed, slow or invalid response leaves the normal composer usable. See reliability and the API contract.

4. Verify with a bounded run

Use deterministic fixtures for UI and outage cases. Then make at most four real prediction requests with the authorized app. Production validation is billable at the displayed unit price after explicit PAYG consent. Report fixture behavior, live API behavior and actual customer-composer behavior separately.