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.

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

Setting Environment Variables

Linux / macOS

export WAVESPEED_API_KEY="your-api-key"

Windows (PowerShell)

$env:WAVESPEED_API_KEY="your-api-key"

Windows (CMD)

set WAVESPEED_API_KEY=your-api-key

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
• Rename — Update key names for easier identification
• Delete — Revoke keys that are no longer needed

Deleted keys stop working immediately.

Error Codes

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

Need more rate limits?

Upgrade your account by adding credits. 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