Model capabilities

An application tells GridNexa what it needs to accomplish: hold a conversation, create an image, or generate a video. capability expresses that task. Model names and providers are execution choices that the platform can resolve or the application can constrain.

Organize business code around capabilities so model upgrades and routing changes do not require changes to the application's business API.

The unified v1 API defines the capabilities below. Use the model catalog in the target environment for live models, versions, limits, and execution modes.

GET /v1/models returns aliases, versions, supported capabilities, execution modes, and parameter limits for the current environment. Applications can display or cache this information for request validation.

This guide describes the public contract; the catalog describes current supply and is authoritative when models are added or temporarily unavailable.

curl -H "Authorization: Bearer $GRIDNEXA_AI_API_KEY" \
  "$GRIDNEXA_AI_BASE_URL/v1/models"

capability is required and model is optional. Without model, GridNexa selects an online model that supports the capability. A model name selects that family's default version; a name and version request an exact published version.

Start with automatic routing. Add a server-side model preference only when output characteristics, compliance, or cost require it.

{
  "capability": "image.generate",
  "input": {"prompt": "A quiet harbor at sunrise"},
  "execution": {"mode": "async"}
}

// Optional: constrain routing to a model family or exact version.
{
  "capability": "image.generate",
  "model": {"name": "<model-alias>", "version": "<version>"},
  "input": {"prompt": "A quiet harbor at sunrise"},
  "execution": {"mode": "async"}
}

Every call uses the same /v1/invoke envelope, while input and parameters depend on capability. chat uses messages; media generation uses prompt; image editing uses role-labeled images; image-to-video uses image.

Place common options in parameters and model-specific options in a versioned parameters.extensions namespace.

Create an upload session, send the raw file to the presigned address, and complete verification. Once ready, reference the asset_id in the capability request.

The presigned upload uses only the headers returned by the session. Use the GridNexa API key for session creation, completion, and model invocation.

# 1. Create an upload session.
POST /v1/input-assets/upload-sessions

# 2. PUT the raw file to upload.url with upload.headers.
# Do not add the GridNexa Authorization header to this request.

# 3. Complete and verify the asset.
POST /v1/input-assets/{asset_id}/complete

# 4. Reference the ready asset in an invocation.
{
  "capability": "video.image_to_video",
  "input": {
    "prompt": "The subject turns toward the camera",
    "image": {"asset_id": "asset_01J...", "content_type": "image/png"}
  },
  "execution": {"mode": "async"}
}

Text capabilities normally return HTTP 200 with output. Media capabilities return HTTP 202 with task_id, status_url, result_url, and a recommended polling interval.

After completion, read output and artifacts from result_url. download_url is short-lived; request the result again for a fresh URL without repeating inference.

POST /v1/invoke
  -> HTTP 202 {task_id, status_url, result_url, retry_after_seconds}

GET {status_url}
  -> accepted | queued | running | completed | failed | cancelled | timed_out

GET {result_url}
  -> {output, artifacts[]}

artifacts[].download_url  # short-lived download URL
artifacts[].s3_uri        # stable artifact reference

The unified endpoint currently supports synchronous text and asynchronous media. Asynchronous text, synchronous media, and native Agent tool calls return CAPABILITY_NOT_SUPPORTED.

Video duration, resolution, aspect ratio, audio, and format support depend on the selected model and are declared by the model catalog.