Iceburg opens soon. Join the waitlist to get in first. Free, no card.
Setup guide

Add Iceburg to your AI

Right now your app sends a prompt straight to your AI model (OpenAI, Claude, and so on) and pays for every token. Iceburg goes in the middle: you send the prompt to Iceburg, Iceburg shrinks it, runs it on your model for far fewer tokens, and hands you back the full answer. You change one line in your code — the line that calls your AI.

Before

full price
your app today
your app  →  OpenAI / Claude  →  answer
          (pays for the whole prompt + whole answer)

After

~half on real chats (our tests)
your app with Iceburg
your app  →  Iceburg  →  your model  →  answer
          (your model only sees a tiny prompt)

You still use your own model and your own model key — Iceburg never replaces them. Below is the complete walkthrough, from zero to a working call. Do it once; then it just runs.

Fastest way to test — free, no card

recommended

No AI key yet? A free key from Groq (console.groq.com/keys, starts with gsk_) is the quickest way to try it. Free tiers are great for a first call but can be slow, rate-limited, or occasionally return an empty response — so for anything real, point Iceburg at a cheap paid model (OpenAI gpt-4o-mini or Anthropic claude-haiku, pennies per call). Free config for a first test:

model_config — Groq (free)
{
  "invoke_url": "https://api.groq.com/openai/v1/chat/completions",
  "model": "llama-3.3-70b-versatile",
  "api_key": "gsk_your_groq_key"
}

Prefer OpenAI, Claude, or Gemini? The table in Step 3 has each one. A tip that trips people up: use the full URL from that table — if you paste just the base, Iceburg now completes it for you, but the exact URL is safest.

Full walkthrough

Set it up, step by step

Step 1

Get your Iceburg key

  1. Join the waitlist: Iceburg opens soon. Join the waitlist (free, no card) and we’ll email you when accounts open; then you create your account here.
  2. Verify your email: click the link we send you (this is required before your key works).
  3. Open your dashboard. This is where your key and your savings live.
Step 2

Sign the licence & create the key

  1. On the dashboard, find the API keys box. The first time, it asks you to accept the API Key License Agreement — tick the box and type your name to sign.
  2. Click New key. A key appears that starts with ig_.
  3. Click Copy and paste it somewhere safe. Treat it like a password — it’s yours, don’t share it. It’s shown only this once (Iceburg keeps just a fingerprint of it); if you lose it, revoke it and make a new one.

This is your Iceburg key. It’s different from your AI provider’s key (that comes next).

Step 3

Get your AI model’s 3 details

Iceburg runs on your model, so it needs three things about it. Find your provider in the table and copy the values. The key is the one you get from that provider’s own website.

Providerinvoke_urlexample modelkey looks like
OpenAIhttps://api.openai.com/v1/chat/completionsgpt-4osk-…
Anthropic (Claude)https://api.anthropic.com/v1/messagesclaude-sonnet-4-5sk-ant-…
Groq (fast + cheap)https://api.groq.com/openai/v1/chat/completionsllama-3.3-70b-versatilegsk_…
Google Geminihttps://generativelanguage.googleapis.com/v1beta/openai/chat/completionsgemini-1.5-proAIza…

Where to get the key: OpenAI → platform.openai.com/api-keys · Anthropic → console.anthropic.com · Groq → console.groq.com/keys · Google → aistudio.google.com/apikey. Don’t have one yet? Groq is free to start and the fastest way to test.

Step 4

Install the tool that makes web requests

Iceburg is just a web address you send data to, so you only need something that can make an HTTP request. In Python that’s requests:

terminal
pip install requests

Using JavaScript/Node instead? You don’t need to install anything — fetch is built in. (JS example is further down.)

Step 5

Write the code (explained line by line)

Paste this into a file called test.py. Fill in the two keys and pick your provider’s URL/model from Step 3.

test.py
import requests

# 1) Your Iceburg key (starts with ig_) from your dashboard.
ICEBERG_KEY = "ig_your_iceberg_key"

# 2) Your own model's 3 details from Step 3.
MODEL = {
    "invoke_url": "https://api.openai.com/v1/chat/completions",
    "model": "gpt-4o",
    "api_key": "sk-your-provider-key",
}

def ask(prompt):
    # 3) Send the prompt to Iceburg instead of straight to your model.
    r = requests.post(
        "https://projecticeburg.com/api/v1/process",
        json={
            "api_key": ICEBERG_KEY,   # who you are
            "prompt": prompt,        # the long prompt
            "model_config": MODEL,   # run it on YOUR model
        },
        timeout=120,
    )
    data = r.json()
    if "answer" not in data:          # something went wrong -- show why, don't crash
        print("Error:", data.get("error", data))
        if data.get("provider_said"): print("Your model said:", data["provider_said"])
        return None
    print(data["savings_message"])   # see the tokens you saved
    return data["answer"]          # the full answer to show your user

print(ask("Explain how photosynthesis works, in detail."))
  • ICEBERG_KEY tells Iceburg the request is yours (and counts your savings).
  • MODEL is your own AI. Iceburg only ever runs the billed step on this.
  • prompt is the exact same prompt you send today — nothing special.
  • answer is the finished reply. Use it exactly like your model’s reply.
Step 6

Run it & read the result

terminal
python test.py

You’ll see two things — the savings banner, then the answer:

output
+--------------------------------------------+
|     /\      ICEBURG                        |
|    /  \     saved 612 tokens this request  |
|  ~/~~~~\~   82% less  (742 -> 130 billed)  |
|  /      \   lifetime saved: 612 tokens     |
| /________\                                 |
+--------------------------------------------+
Photosynthesis is the process by which green plants…

If you see that, it works. Your dashboard’s Tokens saved and cost avoided will update too.

Step 7

Put it in your real app

In your app, find the line where you call your AI today and swap it for ask(...). That’s the whole change:

before → after
# before — you called your model directly:
answer = openai_client.chat.completions.create(...)

# after — same prompt, routed through Iceburg:
answer = ask("…your long prompt…")

Everything downstream stays the same — you still get a full answer, just billed for far fewer tokens.

If something goes wrong

You seeWhat it meansFix
401 Invalid API keyYour Iceburg key is wrong or the account isn’t verified.Re-copy the ig_ key; verify your email.
403 verify your emailAccount not confirmed yet.Click the verification link we emailed you.
400 model_config… public endpointYour invoke_url points somewhere internal/blocked.Use your provider’s real public URL from Step 3.
502 “Your model said: …”Your model provider rejected the call — usually a wrong/expired key, model name, or URL.Read the “Your model said” line (it’s your provider talking). Most often: make a fresh key. Google keys start with AIza, Groq gsk_, OpenAI sk-.
429 too many requestsYou hit your plan’s monthly cap or a rate limit.Wait for the reset, or upgrade on Pricing.
503 backend unavailableThe model couldn’t be reached right now.Check your provider key/URL; try again shortly.
Reference

The endpoint, in full

Send

POST
http
POST https://projecticeburg.com/api/v1/process
Content-Type: application/json
FieldTypeNotes
api_keystringRequired. Your Iceburg key (ig_…).
promptstringRequired. The prompt you’d otherwise send your model. Up to 100,000 characters.
model_configobjectYour model’s invoke_url, model, and api_key. Omit only for a quick demo on our model.

Claude uses the same three fields — just point invoke_url at https://api.anthropic.com/v1/messages with your sk-ant-… key.

Get back

json
{
  "answer": "The full-length reply, ready to show your user…",
  "original_tokens": 742,
  "billed_tokens": 130,
  "tokens_saved": 612,
  "savings_percent": 82.5,
  "lifetime_tokens_saved": 128540,
  "savings_message": "a ready-to-print ASCII iceberg banner (shown above)"
}

answer is what you show your user. savings_message is a ready-to-print line. tokens_saved is this call; lifetime_tokens_saved is your running total. Token counts are estimates for tracking trends, not an exact invoice.

Optional request fields

Add any of these to the /process body:

  • "reference": "…text…" — ground the answer on your own text (a policy, a doc). Iceburg retrieves the relevant passage so the model answers from it instead of guessing — best for questions about your facts.
  • "no_ai": true — answer only from the knowledge base and any reference, with zero model calls (100% saved, instant). If it doesn’t have the answer it says so or asks you to rephrase — it never makes one up.
  • "stream": true — stream the answer back as Server-Sent Events.
  • "followup": "…" — send back the more (or followup) value from the last response, with the same prompt, to get the next part (see below).
  • "slow": true beta, Anthropic and OpenAI models — for long writing that can wait: Iceburg queues it on your provider’s batch service at half price and returns a slow_ticket. Send the same prompt with "slow_ticket": "…" to collect it (usually minutes, at most a day; until then the answer says it’s still being written). "slow": "all" does this for every question your model answers. With a model on OpenAI’s own API there is no ticket: the answer comes back in the same request at about half price (OpenAI’s flex tier), only slower — allow up to 10 minutes; if OpenAI has no room it is answered right away at the normal price. Other providers answer right away as usual.

Short first, more on request. To keep your bill down, answers come brief, and long writing (essays, articles, reports, 600+ word jobs) comes one part at a time, about 250 words each. When there’s more to give, the response includes a "more" value: show a More button, and when it’s pressed send the same prompt with "followup": <that value>. Each part continues the last one without repeating it. Ask for the “full” or “complete” piece and it comes in one go. Using the OpenAI/Anthropic-compatible endpoints instead? A long piece ends with (Reply “more” for the next part.) and replying “more” continues it.

Every response also includes confidence (0–1) and confidence_band (high/medium/low) so you can flag or review low-confidence answers.

Train a no-AI knowledge base

zero-AI serving

Load answers once; serve them forever with no model calls. Feed it (offline, from any source or your own model), then query with "no_ai": true.

train
POST https://projecticeburg.com/api/v1/kb/ingest   {"api_key":"ig_…","text":"<an answer>"}
POST https://projecticeburg.com/api/v1/kb/learn    {"api_key":"ig_…","query":"<a way to ask>","answer":"<that answer>"}

learn teaches which phrasings map to an answer, so it matches questions that share no keywords with the text. Answers you never trained → an honest “I don’t have that,” not a hallucination.

Copy-paste for your language

Same request, three ways. Open the one you use.

› Python
python
import requests
KEY = "ig_your_iceberg_key"
MODEL = {"invoke_url": "https://api.openai.com/v1/chat/completions",
         "model": "gpt-4o", "api_key": "sk-your-provider-key"}

def ask(prompt):
    r = requests.post("https://projecticeburg.com/api/v1/process",
        json={"api_key": KEY, "prompt": prompt, "model_config": MODEL}, timeout=120)
    return r.json()["answer"]
› JavaScript / Node
javascript
const KEY = "ig_your_iceberg_key";
const MODEL = { invoke_url: "https://api.openai.com/v1/chat/completions",
                model: "gpt-4o", api_key: "sk-your-provider-key" };

async function ask(prompt) {
  const res = await fetch("https://projecticeburg.com/api/v1/process", {
    method: "POST", headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ api_key: KEY, prompt, model_config: MODEL }),
  });
  return (await res.json()).answer;
}
› Command line (cURL)
bash
curl -X POST https://projecticeburg.com/api/v1/process \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "ig_your_iceberg_key",
    "prompt": "…your long prompt…",
    "model_config": {
      "invoke_url": "https://api.openai.com/v1/chat/completions",
      "model": "gpt-4o",
      "api_key": "sk-your-provider-key"
    }
  }'
› Claude Code / Cursor / an AI agent

There’s an even easier way for agents — no code at all, just two settings. Jump to Add Iceburg to Claude Code & coding agents below.

The easy way

Add Iceburg to Claude Code & coding agents

Iceburg also speaks the standard AI APIs, so you can point Claude Code, Cursor, Cline, Aider, or any OpenAI/Anthropic app straight at it — no code to write. You change one setting (the base URL) and use your Iceburg key. Everything else keeps working.

First: connect your model (once)

Your agent only sends us your Iceburg key, so we need to know which model to use. Register it once — Iceburg then uses it for every agent request:

bash
curl -X POST https://projecticeburg.com/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "ig_your_iceberg_key",
    "config": {
      "invoke_url": "https://api.openai.com/v1/chat/completions",
      "model": "gpt-4o",
      "api_key": "sk-your-provider-key"
    }
  }'

For Claude, use "invoke_url": "https://api.anthropic.com/v1/messages", a claude-… model, and your sk-ant-… key. You only do this once.

› Claude Code

Set two environment variables before you start Claude Code:

bash
# macOS / Linux
export ANTHROPIC_BASE_URL="https://projecticeburg.com"
export ANTHROPIC_API_KEY="ig_your_iceberg_key"
claude
powershell
# Windows PowerShell
$env:ANTHROPIC_BASE_URL = "https://projecticeburg.com"
$env:ANTHROPIC_API_KEY  = "ig_your_iceberg_key"
claude

Uses the Claude model you connected in your dashboard. Coding stays exact; plain questions get compressed.

› Cursor / Cline / Continue / Aider (and most tools)

These accept an OpenAI-compatible endpoint. In the tool’s model settings, set:

Base URLhttps://projecticeburg.com/v1
API keyig_your_iceberg_key
Modelanything (Iceburg uses the model you connected)
› OpenAI SDK (Python)
python
from openai import OpenAI
client = OpenAI(base_url="https://projecticeburg.com/v1", api_key="ig_your_iceberg_key")

r = client.chat.completions.create(
    model="gpt-4o",  # ignored -- uses your connected model
    messages=[{"role": "user", "content": "Explain vector databases."}])
print(r.choices[0].message.content)

Streaming (stream=True) works too. Anthropic SDK works the same way — point base_url at https://projecticeburg.com.

› Chat apps (Open WebUI, LibreChat, NextChat…): the calls you don’t see

A chat app doesn’t only send what the person typed. After each answer it also asks your model to title the chat, tag it and suggest follow-up questions — and each of those calls re-reads the chat under a long instruction sheet. On real chats with Open WebUI’s default settings those hidden calls were close to half of the tokens paid for.

Point the app’s base URL at https://projecticeburg.com/v1 and Iceburg recognises these calls. Your model still writes the title, tags and suggestions, but from a three-line request and only the part of the chat the job needs. Expect 3 short follow-up suggestions instead of 3–5. Requests that carry tools are never changed.

Running your own Iceburg server? ICEBERG_SIDECALLS sets each kind: slim (default), code (title and tags made without a model — rougher), off (no tags or suggestions) or pass (untouched), e.g. title=slim,tags=off,followups=slim.

New

Generate files & PDFs

Ask Iceburg to write a whole document or code file and hand it back as a ready-to-save file — a PDF, Markdown, a .py, and more. Post to /api/v1/document with a format.

Send

POST
http
POST https://projecticeburg.com/api/v1/document
Content-Type: application/json
FieldTypeNotes
api_keystringRequired. Your ig_… key.
promptstringRequired. What to write (“A one-page guide to composting”, “a Python script that renames files by date”).
formatstringpdf, md, txt, html, or a code type: py, js, ts, sh, css, sql, json. Default md.
titlestringOptional. Document title / filename.
downloadboolOptional. true returns the raw file instead of JSON.
model_configobjectOptional. Same shape as /process; omit to use your connected model.

Save a PDF in Python

python
import requests, base64
r = requests.post("https://projecticeburg.com/api/v1/document", json={
    "api_key": "ig_your_iceberg_key",
    "prompt": "A one-page beginner's guide to composting.",
    "format": "pdf", "title": "Composting 101"})
data = r.json()
with open(data["filename"], "wb") as f:
    f.write(base64.b64decode(data["file_base64"]))
print("saved", data["filename"])

Prefer a direct download? Add "download": true and the response body is the file. Code files are lossless — they come back exactly, never a paraphrase.

Getting the most out of it

  • Iceburg shines on long, context-heavy prompts — the more context you send, the more it saves.
  • Route the boilerplate you repeat every turn (a big system prompt, a context block) — it pays back on every call.
  • Watch savings_percent in each response — it shows exactly how much that call saved, and it climbs as your prompts get longer.
  • Iceburg keeps the meaning, not the exact wording. If a task needs the precise original text back, send that one straight to your model.

Just want to see it work first?

Demo

Leave model_config out entirely and Iceburg runs on a small built-in model, so you can watch the whole flow without any provider key. It’s for trying it out — the real savings only show up once you connect your own model, because that’s the bill Iceburg cuts.