POSTalphaExperience APIs

Crystal Ball Vision

Generate a cinematic symbolic vision with concrete interpretation, action guidance, and optional image-generation direction.

POST /v1/experiences/crystal-ballQuickstartOpenAPI JSON
Credits

4 credits per vision

Minimum Plan

Pro+

Billing Lane

Premium AI

SDK Helper

crystalBall / crystal_ball

Inputs
  • +question
  • +topic
  • +optional birth data
  • +desired tone
  • +visual intensity
Outputs
  • +vision scene
  • +symbol meanings
  • +prediction or guidance
  • +action line
  • +image prompt
Tool Functions

Capabilities behind this endpoint

3 functions
vision.crystal.generate

Creates a vivid but grounded symbolic vision.

symbols.interpret

Maps visual symbols to practical meaning using owned spiritual knowledge.

image.prompt.crystal

Returns a premium image-generation prompt for campaign or app use.

Crystal Vision request
{
  "question": "What is the hidden opportunity around this career change?",
  "topic": "career",
  "style": "cinematic, concise, grounded"
}
Crystal Vision response
{
  "request_id": "req_...",
  "data": {
    "vision": "A black door opens into a violet-lit room where a desk is already waiting.",
    "meaning": "The opportunity is not more searching. It is accepting a role that asks you to be seen.",
    "action": "Say yes to the serious invitation, not the familiar backup plan."
  },
  "usage": { "lane": "ai", "credits": 4, "billableUnits": 1 },
  "meta": { "status": "alpha", "knowledge": ["psychic", "symbols"] }
}
curl
curl https://theleokingai.com/api/v1/experiences/crystal-ball \
  -X POST \
  -H "Accept: application/json" \
  -H "x-api-key: $LEOKING_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crystal-ball-vision-subject-123-v1" \
  -d '{
  "question": "What is the hidden opportunity around this career change?",
  "topic": "career",
  "style": "cinematic, concise, grounded"
}'
Node SDK
import { TheLeoKingApi } from "@theleoking/ai-api";

const api = new TheLeoKingApi({
  apiKey: process.env.LEOKING_API_KEY,
  baseUrl: "https://theleokingai.com/api"
});

const result = await api.crystalBall(
  {
  "question": "What is the hidden opportunity around this career change?",
  "topic": "career",
  "style": "cinematic, concise, grounded"
},
  "crystal-ball-vision-subject-123-v1"
);

console.log(result.request_id);
console.log(result.usage.credits);
Python SDK
import os
from theleoking_ai_api import TheLeoKingApi

api = TheLeoKingApi(
    api_key=os.environ["LEOKING_API_KEY"],
    base_url="https://theleokingai.com/api",
)

result = api.crystal_ball(
    {
        "question": "What is the hidden opportunity around this career change?",
        "topic": "career",
        "style": "cinematic, concise, grounded",
    },
    idempotency_key="crystal-ball-vision-subject-123-v1",
)

print(result["request_id"])
print(result["usage"]["credits"])
Error Behavior
HTTPCodePartner Action
400INVALID_REQUESTFix the payload shape, enum value, required field, or request body before retrying.
401AUTH_REQUIREDSend x-api-key from a trusted server environment. Do not expose keys in browser code.
401AUTH_INVALIDCheck the key prefix, rotate compromised keys, and verify the target environment.
402CREDITS_EXHAUSTEDUpgrade the plan, add credits, or switch to a lower-cost Core Compute route.
403AUTH_FORBIDDENUse a key scoped for this endpoint or upgrade to the required plan.
404NOT_FOUNDVerify the job id, environment, API key, and whether the job belongs to the same workspace.
409IDEMPOTENCY_CONFLICTReuse idempotency keys only for the same logical operation and identical request payload.
429RATE_LIMITEDBack off, retry later, reduce concurrency, or request enterprise limits.
Related Endpoints