Skip to main content
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

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

​
inputs
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)

​
success
boolean
Always true on a 200 response.
​
result
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.
​
cost
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.
​
ms
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

StatusCodeMeaning
400INVALID_INPUTSinputs is missing, not an object, or contains invalid values.
400INVALID_SLUGThe internalName path parameter is not a valid slug.
400ASYNC_NOT_SUPPORTED?async=true on a provider that doesn’t support polling. Use sync mode.
402INSUFFICIENT_CREDITSOut of credits. Top up to continue.
402grant_exhaustedTrial grant exhausted. Upgrade your tier.
403CAPABILITY_DENIEDKey lacks model:run (or the per-model model:<id>:run).
403MODEL_TIER_REQUIREDThe model requires a higher plan tier than your account holds.
404MODEL_NOT_FOUNDNo enabled registry model exists with the given internalName.
429RATE_LIMIT_EXCEEDEDPer-minute limit exceeded. Check Retry-After.
500EXECUTION_FAILEDThe 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"}}'
Example response: 
{
  "success": true,
  "result": {
    "videos": [
      { "url": "https://knouds-media.s3.amazonaws.com/media/xyz789.mp4" }
    ]
  },
  "cost": 48,
  "ms": 22310
}