Run a single registered model directly via API

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.

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 with a deployed workflow that wraps the model.

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

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.

Request body

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.

{
  "inputs": {
    "<field-name>": "<value>"
  }
}

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

Response (sync — 200)

boolean

Always true on a 200 response.

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.

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.

number

Execution time in milliseconds from request receipt to response.

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.

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 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

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"}}'

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()

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();

Example response:

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

Overview

Identity & Usage

Endpoints

Async & Webhooks

Run a single registered model directly via API

Endpoint

Authentication

Path parameters

Request body

Response (sync — 200)

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

Registry coverage

Errors

Example

​Endpoint

​Authentication

​Path parameters

​Request body

​Response (sync — 200)

​Async opt-in (?async=true)

​Registry coverage

​Errors

​Example

Endpoint

Authentication

Path parameters

Request body

Response (sync — 200)

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

Registry coverage

Errors

Example