API reference

Authentication and base URL

Base URL: https://api.clone.is. Send Authorization: Bearer <app key> from your backend. Never embed the key in browser or mobile bundles. Download the OpenAPI contract for exact field types and response schemas.

App keys do not manage company billing or grant access to arbitrary Clone accounts. The owner-only /v1/developer/apps API uses a verified owner session or account management token. Use the developer management reference.

Prediction fields

Large context is subject to token-budget validation. Do not erase the user's latest correction to fit the envelope. See the schema for exact limits.

The matching media API accepts artifact.images: up to eight JPEG/PNG inputs, each at most 480,000 decoded bytes. Video previews declare increasing timestamps and duration. artifact.media carries up to two selected original video/audio sources, at most 100 MiB combined and one hour per source, with MIME type, base64 data, duration and SHA-256. The SDK preparers run locally; an explicit prediction uploads these originals, including audio. Supply explicit { id, text } entries in artifact.criteria. Advance the context revision when sources or selection change.

Images, decoded video frames, actual audio and artifact-conditioned next-prompt prediction use OpenAI with the server-only OPENAI_API_KEY. No Gemini key is required for artifact review. A missing reviewer returns media_review_provider_not_configured, with no silent summary fallback. Responses include exact source hashes, references and timestamps in media_review, which SDK transports verify. Raw media stays outside textual prompts, persisted turns and the usage ledger. OpenAI requests disable response storage; no provider Files uploads are used. Provider retention terms still apply.

The server decodes original media before prompt prediction. OpenAI receives up to 48 uniform video frames (at most 1fps), detected change frames and an end frame, with up to four 15-second intervals revisited at 5fps. Actual audio is normalized to mono 16kHz WAV and analyzed in up to four 60-second windows per source. The structured visual review incorporates independently validated audio findings. Partial decode or audio coverage remains unverified and cannot yield approval. artifact_review returns findings tied to criteria, sources and time intervals, optional preference suggestions, unverified items and coverage. Source receipts and sampling do not prove every-frame understanding or actual player playback. Missing provider configuration fails explicitly. Matching deployment and SDK builds are required. Judgment quality and personalization gains need held-out human-reviewed evaluation.

Responses and idempotency

The result echoes request/session/draft/context/connection identity. feedback_revision identifies the feedback actually included, or is empty when none was included. usage.prediction_units is 0 or 1. Acceptance is valid only until expires_at; a retained replay receipt does not extend it. Result recovery is available for one hour. Never transform a timed-out paid request into a new ID automatically.

409 prediction_in_progress means the original ID is pending; 409 idempotency_conflict means its body or subject changed. 410 prediction_replay_expired ends result recovery. Terminal failed or canceled IDs do not execute again. Error and outage behavior.

Observation events

Send { "event_id": "event-001", "request_id": "first-prediction-001", "user_id": "your-authenticated-user", "kind": "presented" } to /v1/prediction-events. Kinds are presented, accepted, edited, dismissed, submitted, rejected, feedback, outcome. Keep the same event ID and body on retries. Events do not change billing.

Record submitted only after your host accepts the send. Automatic Clone mode prompts have message origin agent; they must not be counted as independently human-written preferences or manual Tab acceptance.

Explicit rejected or feedback evaluations and opted-in edited submissions can inform the next new prediction. Acceptance counts and task outcomes alone are not preference labels. Text collection is off by default: guidance and edited final_text require content_opt_in: true. Use outcome: "succeeded" or "failed" only after observing the host task result.

Memory is encrypted, limited to this app/user and the same connection grant, and expires after 30 days. Clear it with { "user_id": "your-authenticated-user" } at /v1/prediction-feedback/clear. Old requests cannot restore cleared memory; stale results using it return 409 feedback_context_cleared. See the SDK feedback guide for integration examples and exact limits. This context loop does not train model weights.

Python, without the SDK

import json, os, urllib.request

with open("prediction.json", encoding="utf-8") as source:
    payload = json.load(source)
request = urllib.request.Request(
    "https://api.clone.is/v1/predictions",
    data=json.dumps(payload).encode(),
    headers={"Authorization": "Bearer " + os.environ["CLONE_APP_KEY"],
             "Content-Type": "application/json"},
    method="POST",
)
with urllib.request.urlopen(request, timeout=15) as response:
    result = json.load(response)
# Validate identity and expiry before presenting result["completion"].

Use your host's cancellation and concurrency limits in production. The API returns predictions; your application owns agent execution and permissions.