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

# AI Providers

> AI providers are external AI services that NekoHub connects to for automated asset enrichment such as image captioning.

An AI provider is an external AI service that NekoHub calls when running Asset Skills. Skills use AI providers to automatically generate metadata for your images — for example, producing a caption or descriptive alt text from an uploaded photo.

<Info>
  AI providers are optional. If no active AI provider is configured, Asset Skills that require AI will not run. You can use NekoHub fully without setting up an AI provider — skills simply won't produce AI-generated enrichments until one is active.
</Info>

## AI provider profiles

An **AI provider profile** stores the connection details for one AI service. You create and manage profiles from the `/ai-providers` page in the admin console or via the `/api/v1/system/ai/providers` API.

Each profile contains:

| Field                 | Description                                                                           |
| --------------------- | ------------------------------------------------------------------------------------- |
| `name`                | A label for this profile (e.g. `OpenAI GPT-4o`).                                      |
| `apiBaseUrl`          | The base URL of the AI service's API (e.g. `https://api.openai.com`).                 |
| `apiKey`              | The API key used to authenticate with the AI service.                                 |
| `modelName`           | The specific model to use for skill requests (e.g. `gpt-4o`).                         |
| `defaultSystemPrompt` | An optional system prompt prepended to every skill request sent through this profile. |
| `isActive`            | Whether this profile is the currently active provider.                                |

## Active provider

Only one AI provider profile can be **active** at a time. When a skill runs, it uses whichever profile is currently marked active. You can switch the active profile at any time — the change takes effect on the next skill execution.

If no profile is active, skill runs that require AI will fail gracefully without affecting the asset itself.

## Testing a profile

Before marking a profile active, you can test it from the admin console. The test sends a small request to the configured AI service and confirms that the credentials, model name, and endpoint are working correctly. A successful test returns a sample caption generated by the model.

## AI providers and Asset Skills

AI provider profiles power the [Asset Skills](/concepts/assets#asset-derivatives) feature. When you run a skill on an asset — either manually from the admin console or automatically on upload — NekoHub sends the image to the active AI provider and stores the result as a derivative or structured result on the asset.

Common skill outputs include:

* **Image captions** stored as structured results with `kind: caption`
* **Processed image variants** stored as asset derivatives

You can view all available skills and their descriptions from the admin console's asset detail page or via `GET /api/v1/assets/skills`.