Set up your account

Create your account and verify your email

Open spicyapi.ai/register. There are three ways to sign up:

Tick the agreement to the Terms of Service and Privacy Policy, then choose Create account.

What you should see: for an email account, a page titled Check your inbox. Open the email and click the link. The page Email verified confirms it, and Go to the console takes you in.

What just happened: your account exists, but it can only call the API once the email is verified. Until then the console shows the banner Email not verified — API calls are blocked.

• The link works once and expires after 24 hours. If it has expired, open the link anyway and use Send a fresh verification link, or choose Verify on the console banner.
• Nothing arrived after a few minutes? Check your spam folder, then use Send it again.

Add funds

Open Billing in the console: spicyapi.ai/console/billing. Under Add funds:

1. Choose an amount. Pick one of the preset amounts (for example $10, $25, $50 or $100) or Custom and type your own. The console shows the smallest and largest amount you can add in one payment. Online payments take at most two decimal places.
2. Look for a bonus. Some amounts come with a promotional bonus, shown as +$… bonus before you pay. The bonus is added as a separate entry next to the amount you paid.
3. Choose a payment option and follow the tab below.

Other messages you may see:

• Top-up is unavailable or A top-up order cannot be created right now: top-ups are temporarily closed, or you have too many pending orders. Finish or cancel the old ones under Top-up orders, or try again later.
• The connection dropped, so the result is unknown: check Top-up orders before trying again, so you do not pay twice.

Optional: turn on auto top-up

Auto top-up charges a saved card for you when your balance runs low, so long jobs do not stop halfway with 40201. It only works with a card.

1. In Billing, find Auto top-up and choose Save payment method securely.
2. Enter your card on the secure page that opens. Your card details stay with the payment processor.
3. Back in Billing you see Checking your payment method, then Payment method saved. If you see That card can't be used here, nothing was saved; try a different card.
4. Fill in three fields:
   • Top up below: the balance that triggers a charge.
   • Amount per top-up: how much each charge adds. It has to be within the same range as a normal top-up.
   • Monthly cap: the most auto top-up may charge in one calendar month. It cannot be lower than the amount per top-up.
5. Tick the authorization and choose Turn on auto top-up.

What you should see: Auto top-up is now on, with these limits. The card shows the rule, for example "Tops up $50 when your balance drops below $10", and Used this month.

The rules, exactly:

• We check your balance about every 30 seconds to 2 minutes. When your available balance is at or below the threshold, we charge the saved card for the set amount.
• Each charge is a normal top-up order tagged Auto top-up. It receives the same bonus as a manual top-up of the same amount, and you can issue an invoice for it.
• The monthly cap counts calendar months in UTC. Once it is used up, auto top-up waits until the 1st of the next month. Failed charges do not count toward the cap.
• If a charge fails, we try again after 1 hour, and again after 6 hours. If the third attempt in a row also fails, auto top-up turns itself off. If the bank declines the card outright (for example a stolen or closed card), it turns off immediately. A successful charge resets the count.
• After it has turned itself off, fix the card (or save a new one) and turn it on again.
• Turn off auto top-up stops future charges at any time. It never changes your balance or top-ups that already went through.

Create an API key

Open API keys: spicyapi.ai/console/keys and choose Create key (or Create your first key).

In the dialog Create an API key, only the name is required. Everything under Advanced can be changed later.

Name. Name the key after whatever will use it, such as production backend or my laptop. You will need to recognize it when you revoke it. Up to 120 characters.

Spend caps (under Advanced, in US dollars). When a cap is reached, this key refuses new tasks with 40202 until the period rolls over. Your other keys keep working. Money set aside for tasks that are still running counts toward every cap.

Enter 0 in any cap for no limit; a blank field means the same.

Access.

• Allowed models. Leave it at All models (no restriction) and the key can call every model, including models added later. Choose specific models and the key refuses any other model with 40301.
• IP allowlist. Any address accepts calls from anywhere. Only these accepts calls only from the addresses you list: IPv4, IPv6 or CIDR ranges such as 203.0.113.10, 198.51.100.0/24, separated by commas, up to 64 entries. Use the public address your server calls from, not an address inside your office or home network. Calls from anywhere else are refused with 40302. Leave this at Any address for a laptop, whose address changes.
• Expiry. Choose 7, 30 or 90 days, 1 year, Never or an exact date. The key stops working at the end of that day, UTC, and from then on it gets the same 401 as a revoked key.

Choose Create.

What you should see: a dialog Key created showing the full key, which starts with sk-spicy-. Copy it with Copy the key, or choose Save as a file. Tick I've stored this key somewhere safe, then Done.

What just happened: this is the only time the full key is shown. We keep only a one-way hash of it, so nobody, including our support team, can show it to you again. If you lose it, revoke it and create a new one.

Later, on the same page:

• Edit changes the name, caps, allowed models, IP allowlist and expiry. Changes take effect straight away.
• Revoke stops the key immediately and cannot be undone. Tasks that were already accepted keep running and are still charged.
• You can hold up to 50 active keys in one scope. Use one key per app or environment, so you can revoke one without stopping the others.

Put the key in SPICY_API_KEY

An environment variable is a named value your terminal hands to the programs it starts. The official SDK, CLI and MCP server, and every example in these docs, read your key from one called SPICY_API_KEY. That way the key never has to be typed into a command or saved inside a project.

Open a terminal first: on macOS press Cmd + Space, type Terminal and press Enter. On Windows open the Start menu, type PowerShell and open Windows PowerShell.

export SPICY_API_KEY="sk-spicy-paste-your-key-here"

nano ~/.zshrc

echo "${SPICY_API_KEY:0:9}"

On a server, set SPICY_API_KEY in your hosting provider's secret or environment settings instead of a file in your project.

Make a free test call

This asks for your balance. It costs nothing, creates nothing, and proves three things at once: the key is set, the key is valid, and your account is allowed to call the API.

curl https://api.spicyapi.ai/api/v1/chat/credit \
  -H "Authorization: Bearer $SPICY_API_KEY"

Expected: a response like this (shortened):

{
  "code": 200,
  "msg": "success",
  "data": {
    "available": "25",
    "held": "0",
    "total": "25"
  },
  "request_id": "req_01k..."
}

What it means: "code": 200 is success. Amounts are US dollars written as text. available is what you can spend on new generations, held is set aside for generations still running, and total is the two together. The real response also contains a funding object that separates paid funds from any promotional grants; you can ignore it for now.

If you get something else:

Prefer not to use curl? The CLI does the same with spicyapi balance.