FantasyDocs

Fantasy API · v1

One API. Every model.

Talk to Claude, GPT, Gemini, DeepSeek and 30+ more through a single OpenAI-compatible endpoint. No tokens to count, no provider lock-in, no surprise bills.

Get your API keyQuickstart

Drop-in compatible

Change the base URL — keep your OpenAI or Anthropic SDK.

No token metering

Flat Pro plan. Unlimited interactive requests across every model, with fair-use protection for heavy automation.

30+ models

Claude, GPT, Gemini, DeepSeek, Grok — one key.

Automatic failover

Provider down? Fantasy reroutes before you notice.

Quickstart

Your first call, in under a minute.

Three steps — none of them involve changing your SDK. Pro plan required to issue a key.

  1. 1

    Generate a key

    From your account dashboard. One key, every endpoint.

  2. 2

    Point your client at Fantasy

    Override the base URL to https://fantasyai.cloud/api/v1.

  3. 3

    Call any model

    Same request shape, same response shape. Streaming, tools, vision — all in.

bash
curl https://fantasyai.cloud/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $FANTASY_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

Authentication

One key. Two header styles.

Generate a key from the dashboard. Use Authorization: Bearer on OpenAI routes, and x-api-key on Anthropic routes. Keys never expire on their own — revoke and rotate from the dashboard.

EndpointFormatHeader
/v1/chat/completionsOpenAIAuthorization: Bearer <key>
/v1/completionsOpenAIAuthorization: Bearer <key>
/v1/messagesAnthropicx-api-key: <key>
/v1/jev/decisionsFantasyAuthorization: Bearer <key>
/v1/systemoneTypeSafeAuthorization: Bearer <key>

API reference

Try it live.

Paste your API key, pick an endpoint, edit the payload and hit send. The response appears instantly — no terminal needed.

Authorization
OpenAI/api/v1/chat/completions

OpenAI-compatible chat endpoint. Supports streaming.

Body · JSON
Response

Send a request to see the response

API reference

Endpoints.

Chat protocols and structured Jev decisions through one Fantasy API key.

POSTOpenAI
/api/v1/chat/completions

Chat completions

OpenAI-compatible chat endpoint. Supports streaming, function calling and tool use across every model in the catalog. Drop-in for the OpenAI SDK.

Authentication

Authorization: Bearer
bash
curl https://fantasyai.cloud/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $FANTASY_API_KEY" \
  -d '{
    "model": "deepseek-v4",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Sort a Python list."}
    ],
    "stream": true,
    "temperature": 0.7
  }'
POSTAnthropic
/api/v1/messages

Anthropic messages

Full Anthropic Messages compatibility. Use with Claude Code, Cline, or any client built against the Anthropic protocol.

Authentication

x-api-key
bash
curl https://fantasyai.cloud/api/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FANTASY_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, world"}
    ]
  }'
GETOpenAI
/api/v1/models

List models

Returns every available model with provider and capability metadata. Useful to populate a model picker in your own UI.

Authentication

Authorization: Bearer
bash
curl https://fantasyai.cloud/api/v1/models \
  -H "Authorization: Bearer $FANTASY_API_KEY"
POSTFantasy
/api/v1/jev/decisions

Jev decisions for Fantasy

Send 1–50 text messages to get routing, research, context, answer length and memory recommendations. Provider calls bill actual input tokens at the Jev rate, converted to EUR without markup. Cached decisions are free. Shadow mode returns advisory decisions.

Authentication

Authorization: Bearer
bash
curl https://fantasyai.cloud/api/v1/jev/decisions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $FANTASY_API_KEY" \
  -d '{"messages":[{"role":"user","content":"Help me debug this function."}]}'
POSTTypeSafe
/api/v1/systemone

Jev native evaluations

Evaluate your own state with 1–32 Choice, Score or Noul questions. Returns structured answers, probabilities, confidence and token usage as JSON. Bills actual input tokens at USD 0.042 per million, converted to EUR without markup; output is free. X-Jev-Credits reports the charge. Your supplied state and criteria are sent to TypeSafe.

Authentication

Authorization: Bearer
bash
curl https://fantasyai.cloud/api/v1/systemone \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $FANTASY_API_KEY" \
  -d '{
    "model":"jev-latest",
    "state":{"message":"I was billed twice."},
    "questions":{
      "department":{
        "type":"choice",
        "instructions":"Which team should handle this?",
        "criteria":{"billing":"Invoices and refunds","technical":"Bugs and outages"}
      },
      "urgency":{
        "type":"score",
        "instructions":"How urgent is this request?",
        "criteria":["Normal","Urgent","Critical"]
      },
      "duplicate":{
        "type":"noul",
        "instructions":"Does the message report duplicate billing?"
      }
    }
  }'

Jev guide

Use the Jev API in your application.

Jev evaluates context and returns structured decisions: classify a request, choose a capability, assess urgency or estimate a probability. Use the dedicated routes above for these evaluations; they return JSON without streaming.

You need an active Pro subscription, a Fantasy user API key and prepaid credits. Send your key with Authorization: Bearer or x-api-key. The TypeSafe key is configured by the administrator on the Fantasy server.

Manage my API keyTop up my creditsTry in the playground

Fantasy recommendations — /jev/decisions

Send your conversation’s text history in messages. The preset evaluates task type, model tier, research, required context, answer length and suitability for durable memory. Your application can then use these recommendations.

1–50 messages, at most 24,000 characters each, including at least one non-empty user message. Only recent user and assistant text is used; system, developer and tool content is excluded.

Your own questions — /systemone

Define state (text, object or array), then questions, an object keyed by your question names. Each question contains type, instructions and, depending on its type, criteria. model is optional and defaults to the configured Jev model, normally jev-latest.

1–32 questions. Choice: 1–255 named options. Score: 2–10 ordered descriptions. Noul: optional true/false criteria. Unsupported fields, including stream, are rejected.

Call Jev from JavaScript or Python

Set FANTASY_API_KEY in your application’s environment. The JavaScript example uses fetch in Node.js; the Python example uses requests and demonstrates all three question types. In the playground, select Jev decisions or Jev native API, paste your key and send the request; successful evaluations consume credits.

javascript
// Node.js: set FANTASY_API_KEY in your environment.
const response = await fetch("https://fantasyai.cloud/api/v1/jev/decisions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FANTASY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    messages: [{ role: "user", content: "Help me debug this function." }],
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? response.statusText);
console.log("Credits:", response.headers.get("X-Jev-Credits"));
console.log(result.decision);
if (result.active && result.decision?.taskType.confidence >= 0.7) {
  console.log("Recommended capability:", result.decision.taskType.value);
  // Map the capability to a model in your application.
}

Read the response

These responses are illustrative: values, latency, the resolved model and token counts depend on your request.

json
{
  "object": "jev.decision",
  "decision": {
    "taskType": {
      "value": "code",
      "confidence": 0.91
    },
    "modelTier": {
      "value": "standard",
      "confidence": 0.83
    },
    "research": {
      "value": "none",
      "confidence": 0.94
    },
    "contextNeeded": {
      "value": "short",
      "confidence": 0.88
    },
    "answerLength": {
      "value": "short",
      "confidence": 0.9
    },
    "memoryCandidate": 0.12,
    "model": "jev-latest",
    "latencyMs": 42,
    "cached": false
  },
  "active": false,
  "usage": {
    "credits": 2
  }
}

For /jev/decisions, each recommendation contains value and confidence. taskType identifies a capability (general, code, reasoning, security or vision); modelTier is economy, standard or premium. decision.model is the Jev model that evaluated the request. Your application chooses the corresponding chat model.

Check active before applying a Fantasy recommendation. In shadow mode, active is false: decisions are advisory. A Desktop request carrying x-fantasy-desktop-context: 1 then receives decision: null and usage.credits: 0. Native /systemone evaluations remain usable in shadow mode.

Choice: answers.department.choice is the selected option name; probabilities maps each option to its probability.

Score: answers.urgency.score ranges from 0 to the number of criteria minus one and can be fractional. legend maps each index to its description; probabilities provides the distribution over those indices.

Noul: answers.duplicate.noul is a probability between 0 and 1, not a boolean. Choose a threshold suitable for your application if you need a true/false result.

For Choice and Score, confidence is distinct from the winning option’s probability. The 0.7 threshold in the JavaScript example is an application choice. usage.input_tokens and usage.output_tokens describe TypeSafe-reported consumption on the native route.

Credits and submitted data

Both /jev/decisions and /systemone bill the input tokens reported by Jev at its provider rate: USD 0.042 per million input tokens, converted to EUR using the cached ECB reference rate or the configured settlement rate, without markup. Output tokens and cached decisions are free. One credit equals EUR 0.01; charges round up to EUR 0.000001 (0.0001 credit). For example, 1,000 input tokens at a USD-to-EUR rate of 0.8 use 0.0034 credits. Before a paid call, the price of the 64,000-token maximum is reserved; only actual usage is captured on success and the unused hold is returned. Failures release the reservation. X-Jev-Credits reports the actual charge; usage.credits also reports it for the preset.

The preset truncates recent history and redacts known secrets; basic personal information redaction is enabled by default. The native route sends your state and criteria to TypeSafe without automatic redaction or truncation.

Understand errors

400
Invalid JSON or parameters: check messages or the question schema.
401
Invalid or disabled Fantasy key, or expired Pro subscription.
402
Insufficient prepaid credits: top up your balance in Billing.
413
The JSON body exceeds 256,000 UTF-8 bytes: reduce the context.
422
TypeSafe rejected the native evaluation: check the model and questions.
429
Request, token or concurrency limit reached: consult Retry-After when present.
502
Provider error or invalid evaluation response.
503
Jev is disabled or unconfigured, or evaluation is temporarily unavailable. For a self-hosted instance, configure JEV_ENABLED=true and TYPESAFE_API_KEY, then restart the server.

Integrations

Plug into the tools you already use.

Fantasy speaks OpenAI and Anthropic — anything built against either protocol works without modification.

Anthropic's official CLI

Claude Code

Override the Anthropic base URL and Claude Code talks to Fantasy instead. Every Claude model unlocked by your plan, with fair-use protection for automated loops.

bash
# PowerShell (Windows)
$env:ANTHROPIC_BASE_URL = "https://fantasyai.cloud/api"
$env:ANTHROPIC_AUTH_TOKEN = "fantasy-your-api-key-here"
claude

# macOS / Linux
export ANTHROPIC_BASE_URL="https://fantasyai.cloud/api"
export ANTHROPIC_AUTH_TOKEN="fantasy-your-api-key-here"
claude

Ready to ship?

Get your API key

Fantasy AI · API v1

HomeChatAccount