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 priceyour app → OpenAI / Claude → answer
(pays for the whole prompt + whole answer)After
~half on real chats (our tests)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:
{
"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.
Set it up, step by step
Get your Iceburg key
- 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.
- Verify your email: click the link we send you (this is required before your key works).
- Open your dashboard. This is where your key and your savings live.
Sign the licence & create the key
- 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.
- Click New key. A key appears that starts with
ig_. - 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).
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.
| Provider | invoke_url | example model | key looks like |
|---|---|---|---|
| OpenAI | https://api.openai.com/v1/chat/completions | gpt-4o | sk-… |
| Anthropic (Claude) | https://api.anthropic.com/v1/messages | claude-sonnet-4-5 | sk-ant-… |
| Groq (fast + cheap) | https://api.groq.com/openai/v1/chat/completions | llama-3.3-70b-versatile | gsk_… |
| Google Gemini | https://generativelanguage.googleapis.com/v1beta/openai/chat/completions | gemini-1.5-pro | AIza… |
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.
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:
pip install requestsUsing JavaScript/Node instead? You don’t need to install anything — fetch is built in. (JS example is further down.)
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.
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_KEYtells Iceburg the request is yours (and counts your savings).MODELis your own AI. Iceburg only ever runs the billed step on this.promptis the exact same prompt you send today — nothing special.answeris the finished reply. Use it exactly like your model’s reply.
Run it & read the result
python test.pyYou’ll see two things — the savings banner, then the answer:
+--------------------------------------------+
| /\ 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.
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 — 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 see | What it means | Fix |
|---|---|---|
401 Invalid API key | Your Iceburg key is wrong or the account isn’t verified. | Re-copy the ig_ key; verify your email. |
403 verify your email | Account not confirmed yet. | Click the verification link we emailed you. |
400 model_config… public endpoint | Your 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 requests | You hit your plan’s monthly cap or a rate limit. | Wait for the reset, or upgrade on Pricing. |
503 backend unavailable | The model couldn’t be reached right now. | Check your provider key/URL; try again shortly. |
The endpoint, in full
Send
POSTPOST https://projecticeburg.com/api/v1/process
Content-Type: application/json| Field | Type | Notes |
|---|---|---|
api_key | string | Required. Your Iceburg key (ig_…). |
prompt | string | Required. The prompt you’d otherwise send your model. Up to 100,000 characters. |
model_config | object | Your 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
{
"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 anyreference, 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 themore(orfollowup) value from the last response, with the sameprompt, to get the next part (see below)."slow": truebeta, Anthropic and OpenAI models — for long writing that can wait: Iceburg queues it on your provider’s batch service at half price and returns aslow_ticket. Send the samepromptwith"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 servingLoad 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.
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.
Same request, three ways. Open the one you use.
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
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)
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.
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:
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:
# macOS / Linux
export ANTHROPIC_BASE_URL="https://projecticeburg.com"
export ANTHROPIC_API_KEY="ig_your_iceberg_key"
claude# Windows PowerShell
$env:ANTHROPIC_BASE_URL = "https://projecticeburg.com"
$env:ANTHROPIC_API_KEY = "ig_your_iceberg_key"
claudeUses 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 URL | https://projecticeburg.com/v1 |
| API key | ig_your_iceberg_key |
| Model | anything (Iceburg uses the model you connected) |
OpenAI SDK (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.
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
POSTPOST https://projecticeburg.com/api/v1/document
Content-Type: application/json| Field | Type | Notes |
|---|---|---|
api_key | string | Required. Your ig_… key. |
prompt | string | Required. What to write (“A one-page guide to composting”, “a Python script that renames files by date”). |
format | string | pdf, md, txt, html, or a code type: py, js, ts, sh, css, sql, json. Default md. |
title | string | Optional. Document title / filename. |
download | bool | Optional. true returns the raw file instead of JSON. |
model_config | object | Optional. Same shape as /process; omit to use your connected model. |
Save a PDF in 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_percentin 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.