API Authentication
WaveSpeedAI requests that run models or access account data require authentication using an API key. Public discovery endpoints, such as the LLM model catalog, are documented separately when authentication is optional.
How It Works
Include your API key in the Authorization header as a Bearer token:
Authorization: Bearer YOUR_API_KEYEvery request that runs models or accesses account data must include this header. Those requests return 401 Unauthorized without a valid API key.
Get Your API Key
- Go to API Keys
- Click Generate to create a new key
- Copy and store it securely — you won’t be able to see it again
Note: API keys are active as soon as they are generated, provided the key, organization, and key creator remain active and the creator’s current role permits the endpoint. A top-up is not required to activate a key. Some models require a paid organization, and every billable request still requires sufficient credits.
Team Organization Permissions
In a team organization, an API key inherits the current role of the member who created it. Role changes apply to existing keys: if the creator is moved to a role that cannot use API keys, becomes inactive, or leaves the organization, those keys stop working.
The account balance endpoint is open to every valid API key regardless of the creator’s role. Keys are scoped by capability, not by which key started a task. Any key that can read predictions reads every prediction in its own organization, regardless of which key submitted them.
| Current role | API key management | API access |
|---|---|---|
| Owner | View, create, rename, and delete any organization key | Full access, including model inference, organization balance, and organization-wide billing and usage |
| Admin | View, create, rename, and delete any organization key | Full access, including model inference, organization balance, and organization-wide billing and usage |
| Developer | View, create, rename, and delete only keys they created | Run models, read any prediction in the organization, and read the organization balance; cannot read itemized charges or usage statistics |
| Billing | View, create, rename, and delete only keys they created | Read organization balance, billing records, and usage; cannot run models or read predictions |
These team-role restrictions do not apply to personal organizations.
Permission Errors
When a key reaches an endpoint its role does not cover, the API returns 403 and names both the role that created the key and a role whose key would work:
{
"code": 403,
"message": "This API key was created by a Billing member, which cannot run models or read predictions. Use a key created by an Owner, an Admin, or a Developer instead. See https://wavespeed.ai/docs/api-authentication",
"error_code": "API_KEY_PERMISSION_FORBIDDEN",
"required_scope": "inference",
"key_scope": "billing"
}key_scope is what the calling key currently has (inference, billing, or full) and required_scope lists the scopes the endpoint accepts. Both are derived from the creator’s role at request time, so a role change can turn a working key into a 403 without the key itself changing.
Retrying will not clear this error — create a key under a role that covers the endpoint, or ask an Owner or Admin for a full-access key. Itemized billing and usage endpoints require a key created by a current Owner, Admin, or Billing member.
Code Examples
cURL
curl --fail-with-body --connect-timeout 10 --max-time 60 \
-X POST "https://api.wavespeed.ai/api/v3/wavespeed-ai/z-image/turbo" \
-H "Authorization: Bearer $WAVESPEED_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "A cat in space", "size": "1024*1024"}'Python
import os
import requests
api_key = os.environ["WAVESPEED_API_KEY"]
response = requests.post(
"https://api.wavespeed.ai/api/v3/wavespeed-ai/z-image/turbo",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
},
json={"prompt": "A cat in space", "size": "1024*1024"},
timeout=(10, 60),
)
response.raise_for_status()
body = response.json()
if body.get("code") != 200:
raise RuntimeError(body.get("message", "Task submission failed"))
print(body["data"])JavaScript
const apiKey = process.env.WAVESPEED_API_KEY;
if (!apiKey) throw new Error("Set WAVESPEED_API_KEY");
const response = await fetch("https://api.wavespeed.ai/api/v3/wavespeed-ai/z-image/turbo", {
method: "POST",
headers: {
"Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json"
},
body: JSON.stringify({ prompt: "A cat in space", size: "1024*1024" }),
signal: AbortSignal.timeout(60_000)
});
const body = await response.json();
if (!response.ok || body.code !== 200) {
throw new Error(body.message || `HTTP ${response.status}`);
}
console.log(body.data);Security Best Practices
| Practice | Why |
|---|---|
| Use environment variables | Never hardcode API keys in your source code |
| Keep keys secret | Don’t commit keys to Git or share them publicly |
| Server-side only | Never expose keys in frontend/browser code |
| Rotate regularly | Generate new keys periodically and delete old ones |
| Use separate keys | Create different keys for different projects or environments |
| Restrict by IP address | Limit a key to your own servers so a leaked key cannot be used from other addresses (see Restrict a Key to IP Addresses) |
Setting Environment Variables
Linux / macOS
export WAVESPEED_API_KEY="your-api-key"Windows (PowerShell)
$env:WAVESPEED_API_KEY="your-api-key"This value is available only in the current PowerShell session. Run your command in the same window. To save it for future terminals and desktop applications, set a user environment variable, then completely restart the application that needs it:
[Environment]::SetEnvironmentVariable(
"WAVESPEED_API_KEY",
"your-api-key",
"User"
)Windows (CMD)
set WAVESPEED_API_KEY=your-api-keyThe set command is also limited to the current Command Prompt session.
Managing API Keys
If your organization role permits API key management, you can create multiple API keys from wavespeed.ai/accesskey:
- Create — Generate new keys for different projects
- Edit — Rename a key for easier identification, or change which IP addresses can use it
- Delete — Revoke keys that are no longer needed
Deleted keys stop working immediately.
Restrict a Key to IP Addresses
By default a key works from any address. To limit a key to your own servers, turn on Restrict by IP address when you create the key, or later in Edit, and list the addresses that may use it:
- Enter one IP address or CIDR range per line, for example
203.0.113.7or198.51.100.0/24. A key can list up to 50 entries. - Only public IPv4 addresses and ranges are supported. IPv6 addresses, private (internal) addresses, and ranges that match every address are not accepted.
- While the restriction is on, a request from any other address is rejected with
403 Forbidden. The response names the address the request came from, so you can see which one to add. The restriction applies to both model API requests and LLM requests. - In Edit, the Recently used IP addresses list shows where the key has been used from lately, with a button to add each address to the list. Make sure your server’s outbound IP address is on the list before you turn the restriction on, or its requests will be rejected.
- The list is kept when you turn the restriction off, so you can turn it back on without typing it again.
Error Codes
| Code | Message | Solution |
|---|---|---|
401 | Unauthorized | Check your API key is correct |
403 | Forbidden | The key creator’s current role cannot use API keys, this endpoint requires broader access, or the request came from an IP address that is not on the key’s IP allowlist |
429 | Too Many Requests | You’ve hit rate limits — wait, or top up to unlock a higher account level |
Common Issues
API key not working?
- Check for extra spaces when copying the key
- Verify the key hasn’t been deleted or disabled
- Ensure you’re using the correct header format:
Authorization: Bearer YOUR_KEY - In a team organization, verify that the key creator is still an active member whose current role permits the endpoint
- If authentication succeeds but a model request asks for payment, top up the organization or choose a model that does not require a paid organization
- If the key is restricted by IP address, check that your server’s outbound IP address is on its allowlist. A request from another address returns
403, and the response says which address it came from
Need more rate limits?
Top up to unlock a higher level. A single top-up unlocks a higher level: any amount for Silver, $1,000 or more for Gold, $5,000 or more for Ultra. The new level raises both prediction and LLM limits. See Account Levels for tier details.
Next Steps
- Get Started with API — Make your first API call
- How to Submit Task — API request details
- Account Levels — Rate limits and tiers