Skip to main content
POST
Run a model
Use this endpoint to execute one model directly. The response returns a runId; poll GET /v1/nodes/runs/{runId} for status and output. For multi-mode models, pass subModelId in the JSON body. Discover valid model and sub-model IDs with GET /v1/models, GET /v1/models/search, and GET /v1/models/{modelId}/schema. Audio controls are model-specific: fetch the schema for supported model choices, voice settings, noise removal, and whether duration can be omitted. When the pricing response specifies actual-output-duration billing, an automatic-duration estimate reserves credits up to the stated fallback duration. The completed run reports the charge based on the generated audio length, and unused reserved credits are released. An explicit duration is a generation target, not a guarantee of the final audio length.
This endpoint is asynchronous. A 202 Accepted response means the run was queued or started. It does not mean the output is ready.

When to use this

Use standalone model runs when your product needs one model call with one validated input payload.
Router, selector, and concatenator utilities are graph primitives, not standalone models. They cannot be submitted to this endpoint.

Before you call it

1

Find the nodeType

Use GET /v1/models. The nodeType becomes the {nodeType} path parameter.
2

Find the subModelId when needed

Multi-mode models list valid subModels[].subModelId values. Pass the chosen one as subModelId in the request body.
3

Fetch the input schema

Use GET /v1/models/{modelId}/schema to discover required input fields, defaults, enum options, and limits.
4

Estimate credits

Use POST /v1/nodes/estimate-credits when you want to show cost before submission.

Authorizations

string
required
Bearer API key. Format: Bearer gx_your_api_key.

Path parameters

string
required
Node type from GET /v1/models, such as gpt_5_6_luna. Graph utilities are excluded. This is not always the same string as a subModelId.

Body

object
required
Model-specific input object. Field names, required fields, enum options, and limits come from GET /v1/models/{modelId} /schema.
string
Required for many multi-mode models when you need a specific mode, such as text-to-image versus image-to-image. Use subModels[].subModelId from GET /v1/models.
object
Optional webhook delivery configuration for model-run lifecycle updates.

Response

The response status is 202 Accepted. Save the runId; it is the ID used for polling.
string
Standalone model run ID. Pass this to GET /v1/nodes/runs/{runId} .

Request

Response example

Handling the response

Save the returned runId. Poll GET /v1/nodes/runs/{runId} until the status is COMPLETED, FAILED, or CANCELED.

Errors

Most caller errors use the standard REST error envelope:

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

nodeType
string
required

Node type from GET /v1/models. This is the path identifier for the executable model.

Body

application/json
input
object
required

Model-specific input fields from GET /v1/models/{modelId}/schema.

subModelId
string

Sub-model ID for multi-mode models. Omit for single-mode models or when using the default mode.

webhook
object

Optional webhook delivery configuration.

Response

Run accepted; poll with the returned runId. When a webhook is configured, the response also includes webhook.signingSecret for Svix signature verification.

runId
string
required
webhook
object