Kallfi API

Kallfi's proposed third-party API gives companies one versioned interface for creating and operating Souls on platforms they own or control. The base URL is https://api.kallfi.com/v1—for example, POST https://api.kallfi.com/v1/souls.

Pricing

All amounts are in USD and exclude applicable taxes and payment-processing fees. The monthly platform fee may be paid monthly or prepaid for a 12-month term. Annual prepayment discounts the price of additional Gems; it does not also discount the platform fee.

Included Gems form one company-level monthly pool, expire at the end of the billing period, cannot be transferred or redeemed for cash, and are consumed before additional Gems. Additional Gems are usage-billed from the same versioned commercial catalog. A quote reserves the exact rate and Gem amount for an operation before work starts; retries of the same operation cannot spend twice.

A paying Soul is a distinct company-scoped Soul for which the partner enables a paid or revenue-producing experience during the billing period. Draft, test, suspended, and deleted Souls do not count merely because a record exists. The final agreement must define the evidence that activates and ends that state; the implementation must meter state intervals rather than infer it by scanning activity.

Optional A-to-Z AI management costs an additional $2 per enabled Soul per month, prorated daily from durable enable/disable intervals. It covers Kallfi-managed orchestration for the Soul under an agreed policy and service boundary; provider usage still consumes Gems unless the order form explicitly says otherwise.

Video chat

An annually prepaid subscription is eligible to enable video chat, if and when Kallfi makes it generally available, through the end of that prepaid term. The current product target is January 2027, not a guaranteed release date. Eligibility does not include unmetered video, GPU, bandwidth, moderation, or telecom usage. Monthly subscribers may purchase a separate video-chat add-on after launch. Exact limits and rates must be published before activation.

Usage rights

The license is non-transferable and limited to the contracting company and the platforms it owns or controls. The company may use the API to power and monetize experiences for users on those platforms, but may not sublicense, resell, expose, white-label, or broker API access or Gem capacity to another business. Resale, agency use on behalf of unrelated companies, or an embedded platform offering requires a separate written agreement.

All use remains subject to Kallfi safety, age, consent, privacy, intellectual-property, prohibited-content, and deletion requirements. A commercial plan never bypasses a capability or safety decision.

Shared identity and surface-owned resources

For existing first-party Web routes, X-Kallfi-Web-Surface provenance, and the safe-only native tRPC slice, see the Application API surface and endpoint contract. Those transports do not inherit the partner REST body selector.

Kallfi has one Account, Supabase Auth identity, handle namespace, application, and Soul identity. The same Account can use both trusted web surfaces, and a Soul keeps one owner, handle, and static identity. A developer-documentation host is presentation context only: developers.kallfi.com and developers.kallfi.red do not authenticate a request, choose its resource surface, or change the API origin. The third-party API remains one proposed origin at https://api.kallfi.com/v1.

The exact WebSurface values are nsfw-disabled and nsfw-enabled. Real Gems, Posts, Soul subscriptions and their benefits, and conversations involving a Soul are surface-owned:

• A Real-Gem wallet belongs to one Account and one surface. A .com operation cannot spend, fund, refund, or convert value in the .red wallet, and the reverse also applies.
• Bonus Gems remain one Account-wide pool with their existing eligibility and spending rules. Shared Bonus does not transfer Real value or make a surface-owned resource cross-surface.
• Every Post has one immutable creation surface. Reads, media, access grants, and derived work must use that same surface.
• A Soul subscription is keyed by the subscriber Account, Soul, and surface. Access, paid benefits, free-message units, renewals, cancellations, and reversals remain independent per surface.
• A conversation involving a Soul is keyed by its exact ProfileSubject pair and surface. Messages, drafts, unread state, offers, media, deferred work, and private memory stay with that conversation.

Source-asset creation and Soul creation/read/update remain surface-neutral because they establish shared inputs and Soul identity. ResponseCreateRequest and GenerationCreateRequest require an explicit surface value; callers must never infer it from a documentation host or a client label. Kallfi persists that value on the accepted surface-owned operation. Later operation reads derive the immutable surface from operation_id and do not accept a surface selector. Replaying an idempotency key or resource operation with a conflicting surface returns the stable surface_conflict error.

Authorized image and video locators

Cloudflare Images use ordinary direct image URLs after application authorization. MediaLocator distinguishes a direct image (kind: "image", url, no expires_at) from an expiring video or other explicitly authorized gateway capability (expires_at required). A direct image URL is not a revocable, expiring, or surface-bound bearer capability: Post/operation surface membership, safety, access, and entitlement checks happen before its authorized projection. Mux video playback keeps its existing signed delivery and expiry. Private source upload targets keep their separate short-lived upload contract.

This accepted policy supersedes mandatory signed Cloudflare Post-image gateway delivery. The immediate provider rollback inventory is Post-image private conversion; other authorized generated Cloudflare images use the same direct delivery policy. The OpenAPI proposal describes this contract, while provider rollback, runtime release, generated SDK adoption, and hosted browser proof remain separate evidence gates. See the media delivery owner for rollout state.

Features

Every mutation is replay-safe and uses stable error codes, versioned schemas, scoped credentials, usage reporting, and company-level quotas. A-to-Z AI management can be enabled per Soul without changing the underlying Soul or API contract.

Video chat is a future, separately metered capability. Bulk export, arbitrary model selection, direct GPU/provider access, marketplace/resale functions, and unbounded batch operations are deliberately absent from the initial surface.

Short API reference

The API origin is https://api.kallfi.com and the versioned base URL is https://api.kallfi.com/v1. Requests use Authorization: Bearer <credential>, JSON, and an opaque Idempotency-Key on every mutation. IDs are company-scoped and must not be treated as authorization by themselves. Long-running work returns 202 Accepted with an operation resource; completion is observed by polling or signed webhook.

Initial webhook events are operation.accepted, operation.succeeded, operation.failed, and operation.canceled. Delivery is at least once, so consumers must deduplicate by event ID. Webhook endpoint registration may remain an operator-assisted onboarding action until a secure self-service lifecycle is justified.

Soul creation inputs

POST /v1/souls creates a Soul from scratch when source_asset_ids is empty. A Human or Creature Soul may instead use any admitted combination of these company-scoped source-asset types:

POST /v1/soul-source-assets records the asset type, declared byte length, content type, checksum, rights/consent attestation, and—only for text_video_timeline—the annotation track, then returns a short-lived direct-to-storage upload target. Kallfi validates the exact uploaded bytes asynchronously. Partner application servers do not send large media through the JSON API process.

{
  "type": "text_video_timeline",
  "media": {
    "content_type": "video/mp4",
    "byte_length": 48210531,
    "sha256": "<lowercase-hex-digest>"
  },
  "annotations": [
    {
      "request_at_ms": 12400,
      "behavior_start_ms": 12850,
      "behavior_end_ms": 17400,
      "user_request": "Welcome the newest viewer and ask where they are watching from."
    }
  ],
  "rights_attestation": {
    "basis": "owned_or_licensed",
    "subject_consent": true
  }
}

Annotations must be ordered, within the exact video duration, non-overlapping unless a later contract explicitly supports overlap, and bounded in count and text length. The server derives profiles only after media safety, identity/likeness, rights, checksum, and annotation validation pass. Source media and derived profiles remain private to the company and Soul; Kallfi does not use them to train another tenant's Soul.

{
  "external_soul_id": "performer-17",
  "kind": "human",
  "description": "An energetic live host with warm, concise delivery.",
  "source_asset_ids": ["ssa_appearance", "ssa_style", "ssa_live_behavior"]
}

Soul creation returns an asynchronous operation because source admission, appearance/style/live-behavior derivation, safety, Looks, and Voice can outlive an HTTP request. The operation freezes the exact ordered source-asset set and profile revisions; a later upload or asset edit cannot mutate an already accepted creation.

Contract rules

• /v1 is additive. Breaking changes require a new major version and a published migration window.
• Every list added later must use a bounded limit and opaque cursor; no endpoint may offer an unbounded response or offset pagination.
• Mutation replay with the same key and same request returns the original result. Reusing a key with different input returns a conflict.
• WebSurface is exactly nsfw-disabled or nsfw-enabled. Surface-owned resource creation requires the explicit surface field; later reads derive surface from the immutable resource or operation and reject a conflicting selector with surface_conflict.
• Documentation hosts are presentation context only. They never authorize, select, or relabel API resources; the proposed third-party API keeps the single origin https://api.kallfi.com/v1.
• Account, Auth identity, handles, and Soul identity are shared. Real wallets, Posts, Soul subscription benefits, and Soul conversations retain their surface ownership; Bonus Gems remain Account-wide.
• The server selects the provider, model, and execution profile. Partners request a product capability, not Modal, RunPod, or a raw model.
• Source-asset roles are explicit. Appearance, content style, and live behavior cannot be inferred from a generic upload or silently substituted for one another.
• Reference-derived profiles are private conditioning artifacts, not permission for cross-tenant training, resale, or provider retention beyond the contracted processing boundary.
• Quotes, Gem rates, included usage, and entitlements are versioned server facts. Client arithmetic is presentation only.
• Safety rejection, quota rejection, and provider unavailability use stable machine codes and do not create a billable successful operation.