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

# Run a single registered model directly via API

> Invoke any enabled registry model directly by internalName without a workflow — available to Business+ API keys with model:run capability.

Use this endpoint to run a single registry-defined model directly, without wrapping it in a workflow. You provide the model's `internalName` and a set of field inputs, and Knouds executes the model and returns the result.

This endpoint is designed for advanced automation where you want to call a specific model — such as a custom image generator or an LLM — without the overhead of deploying a full workflow.

<Note>
  This endpoint requires capability `model:run` (any model) or `model:<internalName>:run` (specific model only). Both are available to Business and Enterprise tiers. Pro and Free keys cannot grant these capabilities and receive `403 CAPABILITY_DENIED`. If you are on Pro, use [`POST /api/workflows/:slug/run`](/api/run-workflow) with a deployed workflow that wraps the model.
</Note>

## Endpoint

```
POST /api/models/:internalName/run
```

## Authentication

Capability `model:run` (any registry model) or `model:<internalName>:run` (specific model only). Pass your Business+ API key in the `x-api-key` header.

Business+ keys are subject to the 1,000 req/min rate limit (Enterprise unlimited). The same `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers returned by the workflow run endpoint are also present here.

## Path parameters

<ParamField path="internalName" type="string" required>
  The model's internal slug. You can find this in the Node Builder admin panel — it is the identifier shown under the model's name. For example: `seedance-2-0-full-access`, `gpt-image-2`, `nano-banana-2`, `kling-v3-i2v`. Slugs are lowercase letters, digits, and hyphens. The value must match an enabled registry model.
</ParamField>

## Request body

<ParamField body="inputs" type="object" required>
  Key/value pairs matching the model's field schema as configured in Node Builder. The accepted field names map directly to the parameters the underlying provider expects.
</ParamField>

```json theme={null}
{
  "inputs": {
    "<field-name>": "<value>"
  }
}
```

Omitting `inputs` entirely, or passing a non-object value, returns `400 INVALID_INPUTS`.

## Response (sync — 200)

<ResponseField name="success" type="boolean">
  Always `true` on a 200 response.
</ResponseField>

<ResponseField name="result" type="object">
  The model's output. The shape depends on the model type. Common structures include `images`, `videos`, `audios`, and `text` arrays or strings. Media URLs point to S3-hosted files on the `knouds-media` bucket.
</ResponseField>

<ResponseField name="cost" type="number">
  Credits deducted from your account balance for this run. If the run consumed a trial grant instead of your credit balance, this value is `0`.
</ResponseField>

<ResponseField name="ms" type="number">
  Execution time in milliseconds from request receipt to response.
</ResponseField>

## Async opt-in (`?async=true`)

Append `?async=true` to submit the model run without blocking. Response returns in under 500ms with an `executionId`. Supported on HTTP+polling defs (Seedance, Suno, gpt-image-2). Fal-backed and Anthropic-backed defs return `400 ASYNC_NOT_SUPPORTED`.

```bash theme={null}
curl -X POST "https://knouds.ai/api/models/seedance-2-0-full-access/run?async=true" \
  -H "x-api-key: $KNOUDS_KEY" -H "Content-Type: application/json" \
  -d '{"inputs":{"prompt":"...","duration":"5","type":"text-to-video"}}'
# → {"_async":true,"executionId":"<uuid>","requestId":"<provider-id>","status":"processing","pollUrl":"/api/executions/<uuid>"}
```

See [Async executions](/api/async-executions) for the full lifecycle (poll + cancel + webhook delivery).

## Registry coverage

Every enabled model in your Node Builder catalog is reachable here, **including the formerly-native ones**: nano-banana-2, seedream-v5, kling-v3-i2v, kling-o3-ref2v, kling-v3-motion, claude-sonnet. Phase 10 (v4.7.0) unified all execution behind the registry — no model is fenced off.

## Errors

| Status | Code                   | Meaning                                                                  |
| ------ | ---------------------- | ------------------------------------------------------------------------ |
| `400`  | `INVALID_INPUTS`       | `inputs` is missing, not an object, or contains invalid values.          |
| `400`  | `INVALID_SLUG`         | The `internalName` path parameter is not a valid slug.                   |
| `400`  | `ASYNC_NOT_SUPPORTED`  | `?async=true` on a provider that doesn't support polling. Use sync mode. |
| `402`  | `INSUFFICIENT_CREDITS` | Out of credits. Top up to continue.                                      |
| `402`  | `grant_exhausted`      | Trial grant exhausted. Upgrade your tier.                                |
| `403`  | `CAPABILITY_DENIED`    | Key lacks `model:run` (or the per-model `model:<id>:run`).               |
| `403`  | `MODEL_TIER_REQUIRED`  | The model requires a higher plan tier than your account holds.           |
| `404`  | `MODEL_NOT_FOUND`      | No enabled registry model exists with the given `internalName`.          |
| `429`  | `RATE_LIMIT_EXCEEDED`  | Per-minute limit exceeded. Check `Retry-After`.                          |
| `500`  | `EXECUTION_FAILED`     | The provider call failed. The `error` field describes the cause.         |

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://knouds.ai/api/models/seedance-2-0-full-access/run \
    -H "x-api-key: $KNOUDS_KEY" \
    -H "Content-Type: application/json" \
    -d '{"inputs":{"prompt":"midnight neon street","duration":"5","type":"text-to-video"}}'
  ```

  ```python Python theme={null}
  import os, requests

  response = requests.post(
      'https://knouds.ai/api/models/seedance-2-0-full-access/run',
      headers={
          'x-api-key': os.environ['KNOUDS_KEY'],
          'Content-Type': 'application/json',
      },
      json={'inputs': {'prompt': 'midnight neon street', 'duration': '5', 'type': 'text-to-video'}},
  )
  data = response.json()
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://knouds.ai/api/models/seedance-2-0-full-access/run',
    {
      method: 'POST',
      headers: {
        'x-api-key': process.env.KNOUDS_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        inputs: { prompt: 'midnight neon street', duration: '5', type: 'text-to-video' },
      }),
    }
  );
  const data = await response.json();
  ```
</CodeGroup>

Example response:

```json theme={null}
{
  "success": true,
  "result": {
    "videos": [
      { "url": "https://knouds-media.s3.amazonaws.com/media/xyz789.mp4" }
    ]
  },
  "cost": 48,
  "ms": 22310
}
```