API Authentication

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_KEY

Every 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

  1. Go to API Keys
  2. Click Generate to create a new key
  3. 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 roleAPI key managementAPI access
OwnerView, create, rename, and delete any organization keyFull access, including model inference, organization balance, and organization-wide billing and usage
AdminView, create, rename, and delete any organization keyFull access, including model inference, organization balance, and organization-wide billing and usage
DeveloperView, create, rename, and delete only keys they createdRun models, read any prediction in the organization, and read the organization balance; cannot read itemized charges or usage statistics
BillingView, create, rename, and delete only keys they createdRead 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

PracticeWhy
Use environment variablesNever hardcode API keys in your source code
Keep keys secretDon’t commit keys to Git or share them publicly
Server-side onlyNever expose keys in frontend/browser code
Rotate regularlyGenerate new keys periodically and delete old ones
Use separate keysCreate different keys for different projects or environments
Restrict by IP addressLimit 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-key

The 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.7 or 198.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

CodeMessageSolution
401UnauthorizedCheck your API key is correct
403ForbiddenThe 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
429Too Many RequestsYou’ve hit rate limits — wait, or top up to unlock a higher account level

Common Issues

API key not working?

  1. Check for extra spaces when copying the key
  2. Verify the key hasn’t been deleted or disabled
  3. Ensure you’re using the correct header format: Authorization: Bearer YOUR_KEY
  4. In a team organization, verify that the key creator is still an active member whose current role permits the endpoint
  5. 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
  6. 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

© 2026 WaveSpeedAI. All rights reserved.