Documentation

Overview

Phantm is an API gateway for AI requests. Your application keeps sending OpenAI-style or Anthropic-style requests; it just sends them to Phantm instead of straight to the provider. Phantm forwards each request to your provider, works to lower what it costs, and shows you what happened in the dashboard.

Two things change in your code: the base URL and the key. Streaming, tool use and the request shape you already use all stay the same. Phantm never moves a request to a different provider: OpenAI requests stay with OpenAI, Anthropic requests stay with Anthropic, DeepSeek requests stay with DeepSeek. DeepSeek models use the OpenAI SDK setup below, with a DeepSeek model name.

Getting started

Sign up at dashboard.getphantm.ai/signup with your GitHub account, your Google account, or an email address and password. With email, we send a 6-digit code to confirm the address. Then give your company's name, click Read and accept the Terms of Service, scroll to the end and click I agree. Click Create account and you are signed in as your account's admin. No card is needed to start. Signing up puts you on the Self-serve plan: a Free week, then 20% of Verified Savings, with Collaborative data terms. Our Pricing page compares the plans.

If your product handles legal, financial, health, regulated or otherwise confidential material, read Data and privacy first: on the Self-serve plan, Phantm keeps the text of prompts and responses for up to 90 days, and this cannot be turned off. If that does not suit you, or you need anything agreed in writing, see Enterprise.

Signing in

Sign in at dashboard.getphantm.ai/login the same way you signed up. You can connect GitHub or Google to an existing account under Settings › Sign-in. There is a forgot-password link on the sign-in screen, which also lets you add a password to an account you created with GitHub or Google.

Adding teammates

Admins invite teammates from the Team page, choosing a role: viewer, editor or admin. Each invite is an email titled "You've been invited to the Phantm dashboard", with a single-use link valid for 7 days. Admins can resend an invite or remove a teammate, which signs them out at once.

Enterprise

The Enterprise plan has custom pricing, set in a signed agreement, and includes:

• the Privacy option: Phantm doesn't keep your prompts or responses, and zero data retention, including the measurement sample, is available by contract (see Data and privacy);
• a Benchmark on your own traffic before anything changes (see Benchmarks);
• custom routing rules tuned to your workflows;
• data terms in writing, such as a data processing agreement and agreed retention periods.

To ask about it, book a call or email support@getphantm.ai. Our Pricing page compares the two plans.

First-time setup

After you sign up, the dashboard's home page walks you through three steps: your provider key, your Phantm gateway key with copy-paste setup for your code, and your first request. You can also do the first two any time under Settings.

1. Add your provider API key

Pick OpenAI, Anthropic or DeepSeek and paste the key (sk-... or sk-ant-...). We check it against the provider when you save, then store it encrypted. The key is write-only: the dashboard shows only the provider and the last four characters, and never the key itself.

Use a key created specifically for Phantm, so you can revoke or replace it without touching anything else. Your provider keeps billing your own account for model usage.

2. Create your gateway key

Choose Create your gateway key (later, Settings › Gateway Keys › Rotate key). Your new key starts with gw_ and is shown once, so copy it into your secrets store straight away. This is the key your application sends to Phantm. The setup page then shows the code for the OpenAI SDK, the Anthropic SDK and Claude Code, the same as in Connect your application, and the model names you can use.

3. Send your first request

The setup page waits for your first request and tells you when it arrives. Your Free week starts with it.

You can hold several active gateway keys and revoke any of them at any time. Rotating creates a new key; existing keys keep working until you revoke them, so you can switch your application over without downtime.

Connect your application

Change the base URL and the key. Phantm reads your gateway key from the Authorization: Bearer header and nowhere else. The OpenAI SDK sends it there automatically. The Anthropic SDK and Claude Code send it there only through their auth_token setting, shown below.

OpenAI SDK

from openai import OpenAI

client = OpenAI(
    base_url="https://api.getphantm.ai/v1",
    api_key="gw_YOUR_PHANTM_KEY",
)

response = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[{"role": "user", "content": "Summarize this document in three bullets."}],
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.getphantm.ai/v1",
  apiKey: "gw_YOUR_PHANTM_KEY",
});

Anthropic SDK

Pass the gateway key as auth_token, not api_key. The SDK sends api_key on the x-api-key header, which Phantm does not accept. Note that the Anthropic base URL has no /v1 suffix.

import anthropic

client = anthropic.Anthropic(
    base_url="https://api.getphantm.ai",
    auth_token="gw_YOUR_PHANTM_KEY",
)

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Summarize this document in three bullets."}],
)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://api.getphantm.ai",
  authToken: "gw_YOUR_PHANTM_KEY",
});

Claude Code

Set two environment variables. Use ANTHROPIC_AUTH_TOKEN, not ANTHROPIC_API_KEY: the latter sends the key on x-api-key and every request is refused with a 401.

export ANTHROPIC_BASE_URL="https://api.getphantm.ai"
export ANTHROPIC_AUTH_TOKEN="gw_YOUR_PHANTM_KEY"

Claude Code prints a one-line notice that its claude.ai connectors are disabled while an auth token is set. That is expected.

Check that it works

curl https://api.getphantm.ai/v1/chat/completions \
  -H "Authorization: Bearer gw_YOUR_PHANTM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-5.4-mini", "messages": [{"role": "user", "content": "Say hello in one sentence."}]}'

Two more useful calls: GET /v1/models returns the models your account can request, and GET /healthz confirms the gateway is up. Your request appears in the dashboard under Requests within seconds.

Streaming works with the same flag you already use, such as stream=True.

OpenAI Responses API

Phantm also serves OpenAI's Responses API. Use the same base URL and gateway key as for chat completions, and call client.responses.create as you would with OpenAI directly. Phantm sends each request to OpenAI with the OpenAI key you added in setup, and optimizes, measures and bills it the same way as a chat completion.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.getphantm.ai/v1",
    api_key="gw_YOUR_PHANTM_KEY",
)

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Summarize this document in three bullets.",
)
print(response.output_text)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.getphantm.ai/v1",
  apiKey: "gw_YOUR_PHANTM_KEY",
});

const response = await client.responses.create({
  model: "gpt-5.6-terra",
  input: "Summarize this document in three bullets.",
});
console.log(response.output_text);

Endpoints

• POST /v1/responses creates a response: streaming, non-streaming, or in the background with background: true.
• POST /v1/responses/compact compacts a conversation.
• GET /v1/responses/{id} retrieves a stored response. With stream=true and starting_after, it resumes a background response's stream.
• DELETE /v1/responses/{id} deletes a stored response, and POST /v1/responses/{id}/cancel cancels a background one.
• GET /v1/responses/{id}/input_items lists a stored response's input items.
• POST /v1/responses/input_tokens counts a request's input tokens.
• /v1/conversations creates, retrieves, updates and deletes conversations, and lists, adds, retrieves and deletes their items.

Only creating and compacting run a model, so only those appear on the Requests page and count toward your savings. The other calls are not recorded as requests, but they do count toward your requests-per-minute limit. WebSocket mode and OpenAI's Files, Vector Stores and Containers APIs are not served through Phantm: call OpenAI directly for those, with a key from the same OpenAI project as the key you gave Phantm.

Streaming

Set stream=True. You get OpenAI's own Responses events, passed through as they arrive.

stream = client.responses.create(
    model="gpt-5.6-terra",
    input="Write a two-line poem about invoices.",
    stream=True,
)
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="")

Streams have the limits in What is supported, and limits. If Phantm has to end a stream early, it ends it with an error event (code stream_timeout, or stream_interrupted when OpenAI's connection broke) rather than dropping the connection. For long reasoning runs and gpt-5.5-pro, use background: true: the job keeps running whatever happens to your connection, you fetch it or resume its stream with GET /v1/responses/{id}, and Phantm bills it once, after it finishes.

Stored responses and conversations

store works as it does with OpenAI (on unless you send store: false), and so do previous_response_id, conversations, stored prompts and built-in tools.

first = client.responses.create(
    model="gpt-5.6-terra",
    input="Suggest a name for a budgeting app.",
)
second = client.responses.create(
    model="gpt-5.6-terra",
    previous_response_id=first.id,
    input="Now write a one-line tagline for it.",
)
print(second.output_text)

A response or conversation created through your account can be reached only with your account's gateway keys; any other account gets a 404. When OpenAI stores a request, it stores it as Phantm sent it, so input items you read back show the text the model saw, after any trimming.

Models

The OpenAI models listed by GET /v1/models work here, as far as OpenAI serves them on the Responses API. Four more are served only on this endpoint and are not listed by GET /v1/models: gpt-5.6-luna, gpt-5.6-terra, gpt-5.6-sol and gpt-5.5-pro. Anthropic and DeepSeek models are not available here. Model names must match exactly, so a dated snapshot name is refused unless it is listed. A model that is not served returns 400 with the code model_not_found.

Model routing

Routing works here as on chat completions (see Model choice and routing). On each turn, Phantm may answer with a cheaper OpenAI model it judges good enough for that turn, and never with a model priced above the one you asked for. GPT-5.6 requests step down within GPT-5.6 first: a gpt-5.6-sol request may be answered by gpt-5.6-terra or gpt-5.6-luna when the turn is simple, and stays on gpt-5.6-sol when it is hard. Phantm only picks a model that takes your request exactly as sent, including its reasoning effort and tools. In a running conversation, it moves to a cheaper model only when the switch pays for itself once OpenAI's prompt cache is taken into account. The response's model field names the model that answered.

These always stay on the model you asked for: gpt-5.5-pro (Phantm never routes to or from it), requests with reasoning.mode set to "pro", requests that use compaction, and requests carrying a program the model is running (programmatic tool calling).

What Phantm optimizes

Besides the model, Phantm changes only the text of your request:

• Tool results. Output from your own function and custom tools is shortened when it is shell output, test-run output, JSON or search results, and the shorter version is used only when it really is shorter. Source code is left as it is.
• Your messages. User messages lose a leading "please", trailing thanks, repeated politeness words and extra spaces. User and assistant messages may be compressed: code and JSON blocks are never rewritten, and compression backs off rather than drop an instruction such as a required format, a limit or a prohibition.
• An output hint. When your application sends the conversation itself, Phantm may end the request with a one-line instruction such as "Be concise and avoid unnecessary detail." It never adds one to a request with tools or a JSON schema output format, or when OpenAI keeps the conversation: previous_response_id, a conversation, a stored prompt, or a first turn that OpenAI stores.
• A cache point. On GPT-5.6 and later models, once your instructions, tools and opening system and developer messages reach 1,024 tokens, Phantm may mark where they end, so later conversations that open the same way read them from OpenAI's prompt cache. It doesn't when you manage caching yourself, with explicit cache mode or a prewarm.

Phantm never changes instructions, system or developer messages, reasoning items, function calls or their call IDs, images, files, built-in tool items, text that carries citations or logprobs, or a tool result that a program reads. Before a request is sent, Phantm checks it against yours: if anything else differs, your own request is sent instead.

Sent exactly as you send it

Phantm sends these requests to OpenAI untouched, with no trimming and no routing:

• requests with an OpenAI-Beta header, which Phantm forwards to OpenAI;
• requests that use moderation or multi-agent;
• requests with a field, input item type or content type that Phantm doesn't support yet, so newer OpenAI features still work through Phantm, without optimization;
• requests that name no model, such as a stored prompt that sets its own;
• every request while your account is paused or in Payment grace, as on chat completions.

Billing

Responses requests are measured and billed as described in Savings and billing: against the model you asked for, with your request as you sent it, at the same 20% of Verified Savings, and with no fee during your Free week. Text Phantm removes is counted with OpenAI's own token counter, or with a local count if that counter doesn't answer in time. The cost recorded for a request includes OpenAI's web search and file search call fees. It does not include code interpreter or hosted shell container time, which OpenAI bills by session.

If your account is Blocked

Every Responses and conversation endpoint returns 402 with the code payment_required, as on chat completions, except cancel and delete: those keep working for your own responses, conversations and conversation items, so you can stop running jobs and delete stored data. See Your Free week.

Request headers

These headers are optional, but we recommend all of them. They make the dashboard far more useful and let us set routing rules per workflow.

Use stable, descriptive feature names such as intake, document-summary, drafting or bulk-classification. Once they are in your analytics and routing rules, renaming them loses history.

What is supported, and limits

Endpoints

• POST /v1/chat/completions, OpenAI-compatible, streaming and non-streaming.
• POST /v1/messages, Anthropic-compatible, streaming and non-streaming.
• POST /v1/responses, OpenAI's Responses API, with stored responses and conversations. See OpenAI Responses API.
• GET /v1/models, the models your account can request.

Common parameters such as model, messages, temperature, top_p, max_tokens, stop, response_format, tools, tool_choice, seed, presence_penalty and frequency_penalty pass through, subject to what the provider and model accept. If a provider rejects a parameter for a given model, remove it or choose a model that accepts it.

Models

Phantm serves OpenAI, Anthropic and DeepSeek models. GET /v1/models lists exactly what your account can request at any time, apart from four OpenAI models served only on the Responses API. Requests are never routed across providers.

Default limits

These apply unless we have agreed different limits for your account.

When you hit a rate, concurrency or budget limit the gateway returns 429, usually with a Retry-After header. A body over the size limit returns 413. A non-streaming request that runs past the timeout returns 504.

Not provided

Phantm works at the model-API layer. It does not ingest files, so keep document handling in your own pipeline and send the resulting prompts through Phantm. Specifically, Phantm does not provide PDF or DOCX upload, OCR, document parsing, vector search or retrieval, or file storage. Embeddings, audio and content-moderation calls should go to the provider directly. Image inputs pass through but are not optimized. Chunk very long documents before they reach the gateway.

Errors

Errors use provider-compatible JSON, so your existing error handling usually works unchanged.

{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "param": null,
    "code": null
  }
}

When you ask us to look into a request, include its X-Request-Id.

Your Free week

Your first request starts your Free week. For 7 days your traffic is optimized and Phantm charges no fee, so you see real savings on your own provider bill before you pay anything. A banner in the dashboard shows the days left, what you have saved so far, and the fee you are not paying.

Adding a card

Add a card any time from Billing › Add card. One page, hosted by our payment processor, takes the card, your billing email and your company's legal name. Phantm never sees the card number.

If there is no card when the Free week ends

• Payment grace, 7 days. Your requests go to your provider exactly as sent, so your application keeps working, but nothing is optimized and no fee is charged.
• Then Blocked. Phantm refuses requests with a 402 error that names the billing page.
• Adding a card fixes it at once. Requests are optimized again from the next one.

We email your admins and billing contact on days 5, 7, 10 and 13 after your first request, so none of this is a surprise.

Pausing

Any admin can pause optimization from Settings at any time, for example if something looks wrong. While paused, requests go to your provider exactly as sent and no fee applies. Resume from the same place. Pausing does not stop the Free week or Payment grace clock.

Benchmarks

On the Enterprise plan, our team can arrange a Benchmark in place of the Free week. During a Benchmark your requests go to your provider unchanged, while Phantm runs an optimized copy on its own provider account, at its own expense, to measure what it would save you. Its length, and any records kept to verify the comparison, are agreed with you in writing. Optimization and billing start only once a card is on file.

The dashboard

Everything about your account is at dashboard.getphantm.ai. Most pages have a date range selector (24 hours, 7 days, 30 days or custom).

During your first week, check the dashboard daily: are requests arriving, are there any 401, 400, 413, 429, 502 or 504 errors, which workflows cost the most, and are latency and output quality acceptable.

Model choice and routing

Once your traffic is optimized, Phantm may answer a request with a different model from the same provider when it judges that model can do the job at lower cost. It never crosses providers, and only ever picks from models we have approved. You can see the model requested and the model used on every request in the dashboard.

You set the guardrails. Tell us, per workflow (the X-Feature header), rules such as:

• always use the strongest model for a workflow;
• never go below a chosen model for customer-facing traffic;
• allow cheaper models only for low-risk extraction, classification or formatting;
• leave a workflow untouched entirely.

Use Routing › Dry run to see how a sample request would be handled before you send real traffic. For sensitive workflows we recommend starting conservatively and loosening the rules once you have seen the quality in your own data.

Data and privacy

Self-serve plan: Collaborative data terms

Every Self-serve account uses these terms, which you accept when you sign up. They cannot be turned off on the Self-serve plan. If you need Phantm not to keep your prompts and responses, see the Enterprise plan's Privacy option.

• Each request record holds the text of the prompt and the response, with the request's metadata: model, token counts, cost, latency, and your feature and End-user tags. Phantm keeps request records for up to 90 days, then deletes them.
• Phantm uses that text to run the service, for example to look into a request when you ask us to, and to improve its routing.
• Phantm never sells it and never uses it to train third-party or foundation models. It is shared only with the service providers that run the service.

Enterprise plan: the Privacy option

Phantm doesn't keep your prompts or responses. Request records keep metadata only (model, token counts, cost, latency, and your feature and End-user tags), for 30 days. Zero data retention, including the measurement sample below, is available by contract, and your data processing agreement and retention periods are agreed in writing. See Enterprise.

On both plans

• To verify savings, Phantm sends a small sample of requests from its own accounts to the AI provider's batch service, and keeps those copies in those accounts so the measurement can be audited.
• Phantm stores your current provider key encrypted and uses it only to send your requests. A replaced key is kept encrypted, and never used again, until your account closes.
• Gateway keys are stored only as hashes, never in the clear. Revoked keys keep their hash too, so past requests can still be traced to the key that sent them.
• Each account's dashboard shows only that account's data.
• Usage and billing records, including per-request savings figures, are kept as long as needed to bill you, support you and meet legal obligations.
• Do not send protected health information, payment card data or other specially regulated data unless we have agreed to it in writing.

Your data goes to your AI provider under your own provider agreement, and is processed by Phantm on infrastructure in the United States. Our Trust Center lists our security controls, our Privacy Policy lists the service providers that process data for us, and our Terms of Service, which Self-serve customers accept at sign-up, cover the rest. For a copy of the Terms, email support@getphantm.ai. A data processing agreement is available on request. To have your data deleted, or to report a security issue, email support@getphantm.ai.

Savings and billing

What it costs

On the Self-serve plan, Phantm charges 20% of Verified Savings, and nothing else. There are no platform or seat fees, no cap and no minimum, and if Phantm saves you nothing in a month, you pay nothing. Your Free week is never billed.

The Self-serve plan comes with Collaborative data terms: Phantm keeps your prompts and responses for up to 90 days to run the service and improve its routing, and this cannot be turned off. Enterprise pricing is custom, set in a signed agreement, and Enterprise adds the Privacy option. Our Pricing page compares the two plans, and the full terms are in our Terms of Service, which you accept at sign-up.

How savings are measured

For each request we compare what you would have paid at the model you asked for, with your original token counts, against the cost of the request Phantm actually sent, from the token usage your provider reported. Both sides are priced at the provider's published prices. Where the requested model's response length can't be observed, Phantm estimates it. A request whose cost cannot be measured or priced is left out and carries no fee, and a request where Phantm's choice cost more counts against your savings.

Where your provider would have discounted cached prompt tokens on the request as you sent it (for example because of your own cache markers or the provider's automatic caching), the baseline includes that discount; it belongs to you and is not a Phantm saving. A cache discount that results from Phantm's changes to the request counts toward the saving, and any extra cache-write cost Phantm causes counts against it.

Every savings figure can be traced to an individual request. Each statement on the Statements page has a per-request CSV and JSON export you can verify yourself, and shows the methodology version it was calculated with.

Invoices

• Invoices cover one calendar month and are usually issued on the 10th of the following month. Your first one starts when your Free week ends.
• The card on file is charged automatically through Stripe. Invoices and statements are in the dashboard.
• If a month's fee is under $10, Phantm may carry it into a later invoice instead of charging it that month.
• Fees do not include taxes.
• Your provider bills your own account for model usage, as before; Phantm never bills you for that.

Disputes

You can dispute a month's statement from its page under Statements, from when it appears until it is invoiced. While a dispute is open, that statement is not invoiced or charged. Phantm resolves disputes within 30 days.

If a payment fails

Stripe may retry the charge. If the invoice is still unpaid 7 days after the failure, Phantm may send your requests to your provider unchanged until it is paid, and after 14 days may block requests (402). A successful payment restores everything at once. You can replace your card any time in Billing, and remove it while nothing is owed.

Going to production

A rollout that has worked well for other customers:

1. Connect staging first and send one test request.
2. Confirm GET /v1/models returns the models you expect.
3. Add the X-Feature, X-User-Id, X-Env and X-Request-Id headers.
4. Run one low-risk workflow through Phantm and check the Requests page for errors.
5. Agree any routing rules for sensitive workflows with us.
6. Set or confirm your monthly budget cap in Governance.
7. Move a small share of production traffic, then watch savings, latency and quality daily during your Free week.
8. Keep a direct-to-provider fallback in your own configuration during the first weeks.

A good first workflow is usually low-risk extraction, classification or summarization. Keep research, drafting and customer-facing advice on conservative rules until you have seen the quality on your own traffic.

Support

Email support@getphantm.ai. During onboarding you also get a direct channel to the team. For live status and incidents, see the status page.

When you report a problem, include what you can of:

• your company name and the environment (staging or production);
• the time it happened and the X-Request-Id;
• the provider and the model you requested, and the feature tag if you send one;
• whether the request was streaming;
• the error status and body, if any;
• whether it affects one workflow or all traffic.

Questions and answers