> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nunchux.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Authenticate every request with your API key in the `X-API-Key` header or `Authorization: Bearer`. Keys start with `sk-nunchux-`.
> Image generation is synchronous: the image is in the response.
> Video generation is asynchronous: submit the job, poll its task until it reaches a terminal status, then download the output promptly, because output URLs expire.

# Authentication

> Learn how to authenticate with the Nunchux API using API keys.

# Authentication

### How to authenticate your API requests

## Requirements for API calls

All API requests to call any model on [Model APIs](/nunchux-optimized/overview) require authentication with your API key. Pass it in either the `X-API-Key` header or the `Authorization: Bearer` header. Both are accepted on every endpoint, and the same key works for both.

<Note>
  Which header should I use?

  Either one. The examples in these docs use `X-API-Key`. The [OpenAI SDK](/nunchux-optimized/openai-compatibility) sends `Authorization: Bearer` automatically. If you send both headers, `Authorization: Bearer` takes precedence.
</Note>

<Steps>
  <Step title="Create an Account">
    [Sign up](https://nunchux.ai/sign-up) for a Nunchux account.
  </Step>

  <Step title="Generate an API Key">
    Go to your [Dashboard](https://nunchux.ai/dashboard) and navigate to the API Keys section. Click "Create New Key" to generate a new API key, which you'll use to securely [access the API Reference](/nunchux-optimized/overview).

    <Warning>
      Store your key securely — your API key is shown only once when created. Copy and store it in a secure location. If you lose it, you'll need to generate a new one.
    </Warning>
  </Step>

  <Step title="Set your API Key">
    Once you've generated an API key, set it as an [environment variable](https://en.wikipedia.org/wiki/Environment_variable).

    ```bash Shell theme={"system"}
    export NUNCHUX_API_KEY=xxxxx
    ```
  </Step>

  <Step title="Use the API Key">
    Include your API key in every request using the `X-API-Key` header.

    ```text Header format theme={"system"}
    X-API-Key: YOUR_API_KEY
    ```
  </Step>
</Steps>

## Example Request

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -X POST https://api.nunchux.ai/v1/images/generations \
    -H "X-API-Key: $NUNCHUX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "nunchux-flux.2-klein-4b",
      "prompt": "a serene landscape",
      "width": 1024,
      "height": 1024
    }'
  ```

  ```python Python theme={"system"}
  import os
  import requests

  api_key = os.environ.get('NUNCHUX_API_KEY')
  headers = {
      'X-API-Key': api_key,
      'Content-Type': 'application/json'
  }

  response = requests.post(
      'https://api.nunchux.ai/v1/images/generations',
      headers=headers,
      json={
          'model': 'nunchux-flux.2-klein-4b',
          'prompt': 'a serene landscape',
          'width': 1024,
          'height': 1024
      }
  )
  ```

  ```javascript JavaScript theme={"system"}
  const apiKey = process.env.NUNCHUX_API_KEY;

  const response = await fetch("https://api.nunchux.ai/v1/images/generations", {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "nunchux-flux.2-klein-4b",
      prompt: "a serene landscape",
      width: 1024,
      height: 1024,
    }),
  });

  const data = await response.json();
  ```
</CodeGroup>

## Best Practices

### Store API keys securely

* Use environment variables to store API keys
* Never hardcode keys in your source code
* Use secret management systems in production
* Rotate keys periodically

```bash theme={"system"}
# Store in environment variable
export NUNCHUX_API_KEY="your-api-key-here"

# Use in requests
curl -X POST https://api.nunchux.ai/v1/images/generations \
  -H "X-API-Key: $NUNCHUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nunchux-flux.2-klein-4b", "prompt": "test", "width": 1024, "height": 1024}'
```

### Use environment-specific keys

Maintain separate API keys for different environments:

* Development key for testing
* Staging key for pre-production
* Production key for live applications

### Rotate a key

You can rotate a key from the dashboard without downtime. Open API Keys and select the rotate icon next to the key:

* A new key is created with the same name and shown one time
* The old key continues to work for 24 hours, then it stops
* Update your applications to the new key in that window

### Monitor API usage

Track your API usage to:

* Detect unauthorized access
* Optimize costs
* Identify usage patterns
* Plan capacity needs

### Rate Limiting

Every key is limited per plan on requests per minute and simultaneous jobs; over a cap you receive a 429. The numbers and how to back off are on the [Rate limits](https://nunchux.ai/docs/rate-limits) page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.