POSTalphaExperience APIs

Future Partner Vision

Generate a structured future partner profile, relationship scene, attraction pattern, timing window, and optional image prompt from birth data and love context.

POST /v1/experiences/future-partner-visionQuickstart OpenAPI JSON

Credits

8 credits per vision

Minimum Plan

Pro+

Billing Lane

Premium AI

SDK Helper

futurePartnerVision / future_partner_vision

Inputs

+birth data
+relationship intent
+orientation/context
+optional photo signal
+optional transit window

Outputs

+future partner archetype
+meeting scene
+chemistry signals
+timing windows
+image prompt
+quality metadata

Tool Functions

Capabilities behind this endpoint

5 functions

partner.vision.generate

Creates a structured future partner profile and scene.

love.signature.extract

Reads Moon, Venus, Mars, 5th, 7th, and 8th house signals when available.

timing.romance.window

Uses owned transits and relationship timing rules for timing windows.

image.prompt.partner

Returns a safe visual prompt for partner-vision image generation.

quality.experience.enforce

Blocks generic, thin, or fallback-looking outputs.

Partner Vision request

{
  "subject": {
    "id": "user_123",
    "dob": "1990-07-23",
    "tob": "14:30",
    "pob": "New York, US"
  },
  "intent": "future long-term partner",
  "context": {
    "relationship_status": "single",
    "desired_tone": "direct, cinematic, grounded"
  }
}

Partner Vision response

{
  "request_id": "req_...",
  "data": {
    "partner_archetype": "magnetic builder with public confidence and private loyalty",
    "meeting_scene": {
      "setting": "a work-adjacent creative event",
      "signal": "conversation starts through a practical offer, then turns intimate"
    },
    "timing_windows": [
      { "start": "2026-08-04", "end": "2026-09-12", "confidence": 0.72 }
    ],
    "image_prompt": "premium cinematic future partner portrait..."
  },
  "usage": { "lane": "ai", "credits": 8, "billableUnits": 1 },
  "meta": { "status": "alpha", "requiredSystems": ["geocentric_tropical", "love_5_7_8"] }
}

curl

curl https://theleokingai.com/api/v1/experiences/future-partner-vision \
  -X POST \
  -H "Accept: application/json" \
  -H "x-api-key: $LEOKING_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: future-partner-vision-subject-123-v1" \
  -d '{
  "subject": {
    "id": "user_123",
    "dob": "1990-07-23",
    "tob": "14:30",
    "pob": "New York, US"
  },
  "intent": "future long-term partner",
  "context": {
    "relationship_status": "single",
    "desired_tone": "direct, cinematic, 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.futurePartnerVision(
  {
  "subject": {
    "id": "user_123",
    "dob": "1990-07-23",
    "tob": "14:30",
    "pob": "New York, US"
  },
  "intent": "future long-term partner",
  "context": {
    "relationship_status": "single",
    "desired_tone": "direct, cinematic, grounded"
  }
},
  "future-partner-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.future_partner_vision(
    {
        "subject": {
            "id": "user_123",
            "dob": "1990-07-23",
            "tob": "14:30",
            "pob": "New York, US",
        },
        "intent": "future long-term partner",
        "context": {
            "relationship_status": "single",
            "desired_tone": "direct, cinematic, grounded",
        },
    },
    idempotency_key="future-partner-vision-subject-123-v1",
)

print(result["request_id"])
print(result["usage"]["credits"])

Error Behavior

HTTP	Code	Partner Action
400	`INVALID_REQUEST`	Fix the payload shape, enum value, required field, or request body before retrying.
401	`AUTH_REQUIRED`	Send x-api-key from a trusted server environment. Do not expose keys in browser code.
401	`AUTH_INVALID`	Check the key prefix, rotate compromised keys, and verify the target environment.
402	`CREDITS_EXHAUSTED`	Upgrade the plan, add credits, or switch to a lower-cost Core Compute route.
403	`AUTH_FORBIDDEN`	Use a key scoped for this endpoint or upgrade to the required plan.
404	`NOT_FOUND`	Verify the job id, environment, API key, and whether the job belongs to the same workspace.
409	`IDEMPOTENCY_CONFLICT`	Reuse idempotency keys only for the same logical operation and identical request payload.
429	`RATE_LIMITED`	Back off, retry later, reduce concurrency, or request enterprise limits.

Related Endpoints

POSTalpha

Love Reveal

/v1/experiences/love-reveal

POSTalpha

Crystal Ball Vision

/v1/experiences/crystal-ball

/v1/past-life/reading