# Key Hosting

**Beta: Key Hosting is currently available to Beta users only.**

Key Hosting (BYOK, Bring Your Own Key) lets you host your own provider API keys on AstraFlow. Without changing your existing invocation code, you can access and manage multiple providers through AstraFlow's unified entry, and benefit from intelligent routing, failover, and AstraFlow resource fallback.

Your provider keys are used first; when none of your own keys are available, the system automatically switches to AstraFlow resources to keep your business running.

## Benefits

- **Unified API access**: Call through AstraFlow's unified API entry and model names without changing your existing code.
- **Intelligent scheduling and switching**: Configure multiple keys with invocation priorities. Keys are switched automatically on failure, with no need to maintain your own retry logic.
- **AstraFlow resource fallback**: When none of your own keys are available, requests automatically fall back to AstraFlow resources, billed at AstraFlow's model list price.
- **Unified provider management**: Centrally manage multiple providers and API keys while continuing to use each provider's original pricing and quota.
- **Traceable invocation records**: View audit logs to track key invocations and operations in one place.

## Entry Point

Go to **Model Service Platform > Workbench > Third-Party Key Management**.

## Limitations

- Only **text models** are supported.
- Only provider APIs using the **OpenAI-compatible protocol** are supported.
- Each account (Company ID) can add up to **20 providers**, with no limit on the number of keys.

## Quick Start

### Step 1: Add a provider

1. Log in to the AstraFlow console and open the **Key Hosting** page from the sidebar.
2. Click **Add Provider**, then select a platform-predefined provider, or choose **Custom** and fill in the provider name and endpoint.
3. For overseas providers, you can select a proxy point: **Ulanqab, Los Angeles, Singapore, Frankfurt, or Shanghai**. Skip this if you have no special needs.
4. Click **OK** to finish creating the provider.

### Step 2: Configure model mapping

Model mapping specifies the **correspondence between AstraFlow models and provider models**.

1. In the provider list, click **Host Key** for the provider to open its detail page.
2. In the **Provider–AstraFlow Model Mapping** section, click **Configure Mapping**.
3. Enter the **provider model ID** and select the corresponding **AstraFlow model ID**.

> An AstraFlow model can be mapped to only one provider. A model already mapped by another provider is marked **Already mapped by another provider**.

### Step 3: Host a key

1. On the detail page, click **Host Key** in the **Key List**.
2. Enter the **API key** and a **display name**, and set the range of models that can be invoked.
3. Click **Start Test**: the system checks **endpoint reachability, key validity, and account balance**.

Note: The test makes a real call using the first mapped model under the provider, which may incur a small charge.

#### Adjust key priority

Simply **drag to reorder** keys in the key list. Keys higher in the list are used first; on a failed call, the system automatically switches to the next key. Changes take effect immediately.

## Billing

- **Own-key invocations**: Model invocation costs are borne by your provider account. No AstraFlow platform service fee is charged during the Beta phase.
- **AstraFlow resource fallback**: Billed at AstraFlow's model list price.
- **Cross-border invocations**: The corresponding unit price applies based on the actual invocation path.

## FAQ

### The test fails and the key cannot be saved. What should I do?

Check the **endpoint, API key, and account balance** in turn. For overseas providers, also confirm that the proxy point is configured correctly.

### I have multiple keys. How should I set them up?

Put keys with larger quotas and better pricing first, and backup keys last. Select the model range according to the models actually enabled for each key. This way you use your best resources first, and if one key has a problem, requests roll over automatically.

### Why does an invocation use AstraFlow fallback instead of my key?

Possible causes include:

- No corresponding model mapping is configured;
- The key status is **Unavailable**;
- The key is not configured for the model;
- All eligible own keys failed to invoke.