Your first app

Moth DocsTutorials

A small program in Python, TypeScript or curl that asks a model one question, prints the answer and says what the call cost.

  1. Get a key

    Make one in Moth Console under Keys, as the Quickstart shows. It starts with moth_, and the browser you made it in keeps a copy you can copy again.

  2. Put it in your shell

    Keep the key out of your code by setting it as MOTH_API_KEY, here for this shell only.

  3. Install the SDK

    Moth speaks the OpenAI API, so the official OpenAI SDK is all you need. Python needs version 3.8 or later and TypeScript needs Node 18 or later.

  4. Run the program

    Copy the file for your language below and run it. The answer prints first, then the cost.

shell
export MOTH_API_KEY=moth_your_key_here
pip install openai          # for Python
npm install openai tsx      # for TypeScript

Python

first.py
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.runmoth.si/v1", api_key=os.environ["MOTH_API_KEY"])

raw = client.chat.completions.with_raw_response.create(
    model="gemini-3.8-flash",
    messages=[{"role": "user", "content": "In one sentence, why do moths fly to lamps?"}],
)
reply = raw.parse()
print(reply.choices[0].message.content)
print("Cost in dollars", int(raw.headers["moth-charged-micros"]) / 1_000_000)

Run it with python first.py.

TypeScript

first.mts
import OpenAI from "openai";

const apiKey = process.env.MOTH_API_KEY;
if (!apiKey) throw new Error("Set MOTH_API_KEY");
const client = new OpenAI({ baseURL: "https://api.runmoth.si/v1", apiKey });

const { data: reply, response } = await client.chat.completions
  .create({
    model: "gemini-3.8-flash",
    messages: [{ role: "user", content: "In one sentence, why do moths fly to lamps?" }],
  })
  .withResponse();
console.log(reply.choices[0].message.content);
console.log("Cost in dollars", Number(response.headers.get("moth-charged-micros")) / 1_000_000);

Run it with npx tsx first.mts. The .mts ending lets the file use await at the top level.

curl

curl
curl -i https://api.runmoth.si/v1/chat/completions \
  -H "Authorization: Bearer $MOTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.8-flash", "messages": [{"role": "user", "content": "In one sentence, why do moths fly to lamps?"}]}'

The -i prints the reply's headers above its body, so you can see moth-charged-micros beside the answer.

What came back

The body is the usual chat completion, with the answer under choices and the token counts under usage. The moth-charged-micros header is what the call cost in millionths of a dollar, and Receipts and headers lists the other headers.

If it fails

StatusWhat it meansWhat to do
401The key is missing, mistyped, revoked or expiredCheck MOTH_API_KEY in this shell, or make a new key
402The balance or the key's cap can't cover the callAdd credit in Moth Console, or raise the key's cap
404The model ID isn't in the catalogCopy an ID from the catalog
429Too many calls at onceWait the seconds in retry-after, then try again

Errors and rate limits lists every error. Next, stream the answer into a web page.