# How to use WaveSpeed AI: playground, API and your bill How to use WaveSpeed AI: sign in, run a model in the playground, call the API with your key, check the price and balance first, and fix the common errors. - Canonical: https://aiofmcity.com/blog/how-to-use-wavespeed-ai - Topic: Getting started (https://aiofmcity.com/topics/getting-started) - Author: Gus - Published: 2026-10-15 - Updated: 2026-10-21 --- ## Key points - To use WaveSpeed AI, run a model once in the playground, then copy the ready-made code from the API tab of the same model page. - New WaveSpeed accounts run 2 tasks at the same time and start 5 per minute. Any successful top-up below $1,000 raises that to 300 and 500. - WaveSpeed has no usage spending limit. The monthly limit in its settings only caps automatic top-ups, so keep your prepaid balance small while you test. - Never resend a WaveSpeed submission automatically. If the connection drops after the server accepted it, a second POST creates and bills a second job. - Generated files on WaveSpeed generally expire after 7 days, so download them as soon as a job completes. --- To use WaveSpeed AI, sign in with Google or GitHub, pick a model and run it once in the playground. Then open the API tab on the same page, copy the code, and run it with your API key from an environment variable. Check the price before each batch and your balance after it, and download your files within seven days. This guide is the hands-on part. What WaveSpeed costs, which models it has and who should pick it is in the [WaveSpeedAI review](https://aiofmcity.com/tools/wavespeed). ## How to use WaveSpeed AI in seven steps 1. **Sign in** with Google or GitHub and check whether you got the $1 trial credit. 2. **Run one model in the playground** with a cheap setting. 3. **Open the API tab** of that model and look at the code it gives you. 4. **Generate an API key** and store it in an environment variable. 5. **Send your first request** with the Python SDK. 6. **Check the price before a batch** and your balance after it. 7. **Download the outputs** before the links expire. **What you need before you start** - [ ] A Google or GitHub account to sign in with. — WaveSpeed has no separate email sign-up. - [ ] Python 3 for the API steps. — The playground needs nothing but a browser. - [ ] A terminal: PowerShell on Windows, Terminal on macOS or Linux. — You type two or three commands into it. - [ ] A prompt for your own invented persona. — Strictly safe for work, and never a real person. ## Create an account and get the free credit You sign in with Google or GitHub. There is no separate email registration, and the $1 trial credit is not guaranteed. > Login options: Google, GitHub, and AWS login for "qualified users after review". "Eligible new users may receive $1 in trial credit for supported models. Registering a new email address alone does not guarantee eligibility." Each model page has four tabs: Playground, JSON ("view your current input as JSON format"), API ("ready-to-use API code (cURL, Python, JavaScript) based on your settings") and History. "The Run button displays an estimated cost before you click. The final charge may vary slightly." "Generated media URLs are temporary and generally expire after 7 days, so download files you want to keep." > > — Source: WaveSpeedAI docs — Get Started with Web, read 2026-10-05 — https://wavespeed.ai/docs/get-started-web > Credits are purchased via top-up, "never expire", and "are non-refundable but remain in your account". "Minimum top-up amounts vary by payment method." > > — Source: WaveSpeedAI docs — How Pricing Works, read 2026-10-05 — https://wavespeed.ai/docs/how-pricing-works If the $1 is in your balance, you can test cheap models without a card. Credits never expire but are not refunded, so top up only what you will use in the next weeks. ## Run your first model in the WaveSpeed playground Every model page has a playground, so you see a result before you write any code. For a first run, pick a cheap image model such as Z-Image-Turbo. Use a prompt for your own invented persona and keep it SFW: ```text Photorealistic smartphone photo of a woman in her late twenties with shoulder-length dark brown hair, sitting at a café window, soft overcast daylight, natural skin texture. ``` Look at the price on the Run button, run the model once and download the image. Now click the **JSON** tab. It shows your settings as the exact input your code will send. The **API** tab shows the same input as ready code. ## Get a WaveSpeed API key and keep it out of your code Generate the key in the dashboard, copy it once and put it in an environment variable. Never paste it into a script. > Requests send the key as `Authorization: Bearer YOUR_API_KEY`. Go to API Keys, click Generate, and copy and store the key securely, because you will not be able to see it again. "A top-up is not required to activate a key." "Every billable request still requires sufficient credits." Use environment variables, do not commit keys to Git, never expose keys in browser code, and use separate keys for different projects. "Deleted keys stop working immediately." > > — Source: WaveSpeedAI docs — API Authentication, read 2026-10-05 — https://wavespeed.ai/docs/api-authentication Set the variable in the terminal you run your script from. On Windows PowerShell: ```powershell $env:WAVESPEED_API_KEY = "your-api-key" ``` On macOS or Linux: ```bash export WAVESPEED_API_KEY="your-api-key" ``` Both last only for the current terminal window. Make one key per project. If a key ends up in a screenshot or a shared file, delete it and make a new one. ## Your first WaveSpeed API request with the Python SDK The Python SDK sends the job, waits for it and returns the output links in one call. It reads your key from `WAVESPEED_API_KEY`. > Install with `pip install wavespeed`. `wavespeed.run` takes a model ID, an input object, `timeout` and `poll_interval`, and the generated files are in `output["outputs"]`. "Use poll_interval=2.0 as a practical default." "Submission POSTs are sent at most once because a disconnect can occur after the server has already created the task." `wavespeed.upload` uploads a local file and returns a URL to use as model input. > > — Source: WaveSpeedAI docs — Python SDK, read 2026-10-05 — https://wavespeed.ai/docs/python-sdk ```python import urllib.request import wavespeed # pip install wavespeed; reads WAVESPEED_API_KEY by itself output = wavespeed.run( "wavespeed-ai/z-image/turbo", { "prompt": "Photorealistic smartphone photo of a woman in her late twenties, " "café window, soft overcast daylight, natural skin texture", "size": "1024*1024", }, timeout=3600.0, poll_interval=2.0, ) # Save every result next to the script, under its original file name. for url in output["outputs"]: name = url.split("?")[0].rsplit("/", 1)[-1] urllib.request.urlretrieve(url, name) print("Saved", name) ``` The model ID is the part of the model page's address after `/models/`. The input is exactly what the JSON tab showed you. For a reference image of your persona, upload it with `wavespeed.upload()` first and pass the returned URL in the field the model asks for. Without the SDK, you send the job and then ask for its result until it is `completed`. Only one of these calls costs money: _Diagram: Only the submission is billed, and it must never be sent twice. Every other call is free and safe to repeat._ 1. **Your script:** Ask the price — POST /api/v3/model/price. Free 2. **Your script:** Check your balance — GET /api/v3/balance. Free 3. **You (checkpoint):** Decide: is the batch worth it? — Price times jobs, against your balance 4. **Your script:** Submit the job — POST /api/v3/ plus the model ID. Billed. Send once, never resend on its own 5. **Your script:** Ask for the result every 2 seconds — GET /api/v3/predictions/ID/result. Safe to repeat 6. **Your script:** Download the outputs — Within 7 days, unchanged > "Start with a 2-second polling interval. For long-running tasks, gradually increase it to 5–10 seconds." "If the connection drops after the server accepts a request, blindly retrying can create and bill a duplicate prediction. Safe GET result queries can be retried." > > — Source: WaveSpeedAI docs — Get Started with API, read 2026-10-05 — https://wavespeed.ai/docs/get-started-api So one network hiccup plus an automatic resend can mean two paid videos. Before you resend a job, look for its task ID in History. ### WaveSpeed webhooks instead of polling A webhook is your own HTTPS address. You add it to the request, and WaveSpeed posts the result there when the job ends. > "Add the webhook query parameter to your API request URL. The webhook URL must be a publicly accessible HTTPS endpoint that can receive POST requests." It must answer within 10 seconds with a 2xx code. WaveSpeedAI makes up to 3 retries when delivery fails. > > — Source: WaveSpeedAI docs — How to Use Webhooks, read 2026-10-05 — https://wavespeed.ai/docs/how-to-use-webhooks You need a public server for this. For a first script on your own computer, polling is simpler. ## Check the price before you run, and your balance after Ask WaveSpeed what a job will cost before you send it. The price check uses the same inputs as the real job and costs nothing. > `POST /api/v3/model/price` with a `model_id` and `inputs`. `price` is the original price in USD and `discounted_price` the amount payable after the effective discount. "Pricing can depend on input parameters such as duration, aspect ratio, and sound." "Submitting an inference request calculates its price again." > > — Source: WaveSpeedAI docs — Pricing API, read 2026-10-05 — https://wavespeed.ai/docs/pricing-api ```bash curl --request POST "https://api.wavespeed.ai/api/v3/model/price" \ --header "Authorization: Bearer ${WAVESPEED_API_KEY}" \ --header "Content-Type: application/json" \ --data-raw '{ "model_id": "wavespeed-ai/z-image/turbo", "inputs": { "prompt": "a test prompt", "size": "1024*1024" } }' ``` This works in macOS, Linux and Git Bash. On Windows, the CLI below is easier. Multiply `discounted_price` by the number of jobs in your batch. Your balance comes from `GET /api/v3/balance` as `data.balance` in US dollars. Stop your script when the balance falls under the cost of the next job. > `wavespeed price` "calculates the estimated cost for the given inputs. It does not generate output and does not charge for a prediction." `wavespeed balance` shows the current account balance. > > — Source: WaveSpeedAI docs — WaveSpeed CLI, read 2026-10-05 — https://wavespeed.ai/docs/wavespeed-cli If you prefer the terminal, the CLI (`npm install -g @wavespeed/cli`) does both checks without code. The price on a model page comes in different units. Read the unit before you compare two models: | Model on WaveSpeed, 5 Oct 2026 | Listed price | What you pay for | | --- | --- | --- | | Z-Image-Turbo | $0.005 | one image | | Nano Banana 2 Edit | $0.07 | one image at 1K; 2K and 4K cost more | | Kling v3.0 Std Image-to-Video | $0.42 | 5 seconds without sound; with sound, 1.5 times | > "Base rate: $0.42 per 5 seconds ($0.084 per second)". "Sound surcharge: ×1.5 when sound is enabled". > > — Source: WaveSpeedAI — Kling v3.0 Std Image-to-Video, read 2026-10-21 — https://wavespeed.ai/models/kwaivgi/kling-v3.0-std/image-to-video > Pricing by resolution: 0.5k $0.045, 1k $0.07, 2k $0.105, 4k $0.14. > > — Source: WaveSpeedAI — Nano Banana 2 Edit, read 2026-10-05 — https://wavespeed.ai/models/google/nano-banana-2/edit On 5 October 2026 some model pages also showed a discount badge, and the per-run price at the top of the page was lower than the price table. Plan with the table price and treat a discount as a bonus. Dated prices for many models are on [what generation costs](https://aiofmcity.com/model-prices). ### What the sources do not say: Finding a spending limit for a WaveSpeed account We looked for a way to cap what one account or one API key can spend in a day or a month. WaveSpeed's docs do not describe one. The Pricing & Billing pages cover prices, payment methods, account levels, refunds and a "Monthly Auto-Recharge Limit". That limit only caps automatic top-ups, and the page says so: "This is not a usage or consumption limit." The API key page lets you create, rename and delete keys, with no budget per key. The balance API returns one number for the whole account. You can check this yourself. Open wavespeed.ai/docs, go through every page under "Pricing & Billing" and "API Reference", and search for "limit", "budget" and "cap". You find rate limits and the auto-recharge cap. Until that changes, your prepaid balance is your spending limit, so keep it small while you test and leave auto top-up off. ## WaveSpeed rate limits: why only two jobs run at once New accounts run two tasks at the same time. If you send twenty video jobs at once, eighteen of them wait. > "Bronze users can only have 2 tasks processing simultaneously — if you submit a 3rd, it will wait until one finishes." Levels upgrade automatically after a successful top-up, based on that single top-up amount. On a 429 error: wait (limits reset every minute), upgrade, or reduce concurrent requests. > > — Source: WaveSpeedAI docs — Account Levels & Rate Limits, read 2026-10-05 — https://wavespeed.ai/docs/account-levels | Level | Starts per minute | Running at once | How you get it | | --- | --- | --- | --- | | Bronze | 5 | 2 | New account | | Silver | 500 | 300 | Any successful top-up below $1,000 | | Gold | 3,000 | 3,000 | One top-up of $1,000 to $4,999 | | Ultra | 5,000 | 10,000 | One top-up of $5,000 or more | For a persona, the jump from Bronze to Silver is the one that counts. It needs a successful top-up, not a big one. On the free credit alone, plan your batches for two jobs at a time. > "There is no dedicated batch-submission endpoint. You can submit individual requests concurrently within your account's rate and concurrency limits, then track each prediction by polling or webhook." > > — Source: WaveSpeedAI docs — FAQ, read 2026-10-05 — https://wavespeed.ai/docs/faq ## Common WaveSpeed errors and what they mean Most failed jobs come from a key, a limit or an input. The code tells you which. > 1200 Content Moderation, 1401 Invalid Parameter, 1402 Media Access Failed, 1407 insufficient_credits, 5000 Internal Error, 5004 Timeout ("In sync mode, the prediction may still be processing"). > > — Source: WaveSpeedAI docs — Error Codes, read 2026-10-05 — https://wavespeed.ai/docs/error-codes | You see | What it means | What to do | | --- | --- | --- | | 401 Unauthorized | The key is wrong or missing | Check for spaces and the `Bearer` header | | 403 Forbidden | The key's role cannot use this endpoint | In a team, use a key made by an Owner, Admin or Developer | | 429 Too Many Requests | You hit your level's limit | Wait a minute, or send fewer jobs at once | | 1200 Content Moderation | The filter blocked the input or output | Rewrite the prompt in plainer, clearly SFW words | | 1402 Media Access Failed | WaveSpeed cannot open your image URL | Upload the file with the SDK or CLI and use that URL | | 1407 insufficient_credits | Your balance is too low | Top up, or check the price before the batch | | 5004 Timeout | The wait ran out, not always the job | Ask for the result with the task ID before you resend | > Failed requests, system errors and system timeouts get an automatic credit reversal. If a Sync Mode request times out on your side and the prediction still completes, "the request is not automatically refundable." To report a charge, send the Task ID from History to support@wavespeed.ai. > > — Source: WaveSpeedAI docs — Refund Policy, read 2026-10-05 — https://wavespeed.ai/docs/refund-policy So you do not pay for a job that fails on WaveSpeed's side. You do pay for a job that finished while your script had stopped waiting. ## Save your files and keep your persona's rules Download every output you want to keep as soon as the job completes. Save each URL in `outputs` to a folder named by date and model, and keep the task ID in the file name. If a charge looks wrong later, support asks for that ID. > Prohibited content includes "Non-consensual intimate imagery — Deepfakes or intimate images created without consent". "Violation of these policies may result in immediate account termination." > > — Source: WaveSpeedAI docs — Content Policy, read 2026-10-05 — https://wavespeed.ai/docs/content-policy > "Most models on WaveSpeedAI support commercial use. Each model may have its own requirements or restrictions based on the terms that apply to that model." > > — Source: WaveSpeedAI docs — Commercial Use Policy, read 2026-10-05 — https://wavespeed.ai/docs/commercial-use-policy For persona work, that means three things: - **Only your own invented persona goes in as a reference.** Never a real person's photo. - **Check the model's own licence before you earn with it.** [Make an AI influencer for free](https://aiofmcity.com/blog/make-an-ai-influencer-for-free) shows how a free-looking model can still need a licence. - **Keep the provenance data in the file.** [Don't strip your watermarks](https://aiofmcity.com/blog/dont-strip-your-watermarks-provenance) explains why platforms need it. Your next step: run Z-Image-Turbo once in the playground, copy the API tab into a script, and make the same image from your terminal. When that works, test your persona on video with [which AI video models hold a face](https://aiofmcity.com/blog/ai-video-models-for-personas), and put the prices into your budget with [what an AI persona costs to start](https://aiofmcity.com/blog/what-an-ai-persona-costs-to-start). ## Frequently asked ### Is WaveSpeed AI free to use? You can start for free. Eligible new accounts get $1 of trial credit with no credit card, but WaveSpeed says a new email address alone does not guarantee it. After that you top up credits and pay per image, per second of video or per run. ### How do I get a WaveSpeed API key? Sign in, open API Keys at wavespeed.ai/accesskey and click Generate. Copy the key straight away, because WaveSpeed shows it only once. It works at once, and you do not need to top up first. ### Why does WaveSpeed only run two of my jobs at a time? New accounts start at the Bronze level: 5 predictions per minute and 2 tasks at the same time. A third task waits until one finishes. Any successful top-up below $1,000 moves you to Silver, with 500 per minute and 300 at the same time. ### Can I set a spending limit on WaveSpeed? Not on usage. WaveSpeed has a monthly limit for automatic top-ups only, and its docs say this is not a usage limit. Your prepaid balance is the real limit, so keep it small and leave auto top-up off while you test. ### How long does WaveSpeed keep my generated files? Generated media URLs are temporary and generally expire after 7 days. Download every image or clip you want to keep as soon as the job completes.