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

# Library usage

> Use @carrothub/core to embed CarrotHub calls directly in a TypeScript program

The CLI is a thin layer over [`@carrothub/core`](https://www.npmjs.com/package/@carrothub/core).
The same package is published independently — install it when you want to call
CarrotHub from a Node.js, Bun, or TypeScript application without shelling out.

```bash theme={null}
npm install @carrothub/core
```

The package has zero runtime dependencies and ships with full TypeScript
types.

## Minimal example

```ts theme={null}
import {
  APIClient,
  createAndPollTask,
  loadConfig,
  processImageParams,
  registry,
} from "@carrothub/core";

const config = loadConfig({ site: "carrothub" });
const client = new APIClient(config);

const endpoint = registry.get("alibaba/wan2.6-t2i", "generation");
if (!endpoint) throw new Error("endpoint not registered");

const body = processImageParams({
  prompt: "A blooming cherry tree at dusk",
  size: "1280*1280",
});

const result = await createAndPollTask({
  client,
  endpointPath: endpoint.apiPath,
  requestBody: body,
  resultKey: endpoint.resultKey,
});

if (result.status === "succeeded") {
  console.log(result.results); // string[] of asset URLs
} else {
  console.error(result.status, result.error);
}
```

## Public API surface

```ts theme={null}
import {
  // Config
  loadConfig,
  getConfigHelp,
  loadEnvFile,

  // HTTP client
  APIClient,

  // Model registry
  registry,
  ModelRegistry,
  registerEndpoint,

  // Tasks
  createAndPollTask,
  pollTask,
  parseTaskResponse,
  isSuccessStatus,
  isTerminalStatus,

  // Image helpers
  processImageParams,
  isImageParam,
  validateImagePath,

  // Utilities
  toCliFlag,
  VERSION,
} from "@carrothub/core";

import type {
  Site,           // "carrothub" | "mulerun"
  InputType,      // "text" | "image" | "video" | "audio"
  OutputType,     // "image" | "video" | "text" | "audio"
  ModelParameter,
  ModelEndpoint,
  Config,
  APIResponse,
  TaskStatus,
  TaskResult,
} from "@carrothub/core";
```

## Key functions

### `loadConfig(options?)`

Resolves `apiKey`, `baseUrl`, `site`, plus default timeout (`120_000` ms) and
retry budget (`3`). Same priority chain as the CLI:
arguments → environment variables → `.env`.

### `new APIClient(config)`

A small `fetch`-based client with:

* Bearer-token auth via the configured API key
* Automatic JSON encoding
* Exponential-backoff retry on transient failures (5xx, network errors)
* `post(path, body)` and `get(path)` returning `APIResponse`

### `createAndPollTask({...})`

Submits a `POST` to `endpointPath` and polls every `interval` ms (default
20 000) until the task reaches a terminal state or `maxWait` (default
900 000 ms) elapses. Set `verbose: true` to log per-poll status lines to
stderr.

### `pollTask({...})`

Same poller, against an already-created task identified by `taskPath` and
`taskId`.

### `processImageParams(body)`

Walks a request body, finds any image-shaped parameter, and converts local
file paths to base64 data URIs. Idempotent for URLs and `data:` URIs.

### `registry`

Singleton catalog of every endpoint that has been imported. The registry is
populated as a side effect of importing `@carrothub/core` (which loads
`models/index.ts` and every provider module). Useful methods:

| Method | Returns |
| - | - |
| `registry.get(modelId, action)` | A single `ModelEndpoint` or `undefined` |
| `registry.findByModelId(modelId)` | Every action registered under that model |
| `registry.listAll()` | Everything |
| `registry.listForSite("mulerun")` | Filtered by site |
| `registry.listByProvider("alibaba")` | Filtered by provider |
| `registry.listByOutputType("video")` | Filtered by output type |
| `registry.listByTag("SOTA")` | Filtered by tag |
| `registry.getProviders()` | Sorted unique provider names |

## Status helpers

```ts theme={null}
import { isSuccessStatus, isTerminalStatus } from "@carrothub/core";

isSuccessStatus(result.status);   // succeeded | completed
isTerminalStatus(result.status);  // success states + failed
```

## Naming convention

In code, model parameter names use `snake_case` (matching the wire format).
The CLI converts to `kebab-case` for flags via `toCliFlag(name)` — useful if
you are building tooling that mirrors the CLI's UX.

```ts theme={null}
import { toCliFlag } from "@carrothub/core";

toCliFlag("negative_prompt");  // "negative-prompt"
toCliFlag("aspect_ratio");     // "aspect-ratio"
```

## Versioning

The CLI and core packages are released in lockstep. The version string is
exported as `VERSION` and is what the CLI prints for `carrothub --version`.


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