Complete your first model call

This guide assumes that you can sign in to the Developer Console and unified model invocation is available in the target environment.

• Create a developer API key beginning with gnx_. The plaintext is shown once.
• Obtain the API base URL for the target environment.
• Install curl 8 or another JSON-capable HTTP client.
• Keep production keys in a secret store or server-side environment variable.

Store the raw gnx_ key in the environment. The HTTP header format is Authorization: Bearer <key>.

export GRIDNEXA_AI_BASE_URL="https://api.gridnexa.ai"
export GRIDNEXA_AI_API_KEY="gnx_your_key"

capability is required and determines validation and output shape. When model is omitted, GridNexa selects a published model that supports the capability.

Use a stable Idempotency-Key for requests that may be retried or billed.

curl -X POST "$GRIDNEXA_AI_BASE_URL/v1/invoke" \
  -H "Authorization: Bearer $GRIDNEXA_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-chat-001" \
  -d '{
    "capability": "chat",
    "input": {
      "messages": [
        {"role": "user", "content": "Explain GridNexa in one sentence."}
      ]
    },
    "execution": {"mode": "auto"}
  }'

Short chat calls normally return HTTP 200. Verify status=completed and output, and retain meta.requestId for diagnostics. routing.resolved_model identifies the model that ran.

HTTP/1.1 200 OK
{
  "data": {
    "invocation_id": "inv_01J...",
    "status": "completed",
    "capability": "chat",
    "output": {
      "type": "message",
      "message": {"role": "assistant", "content": "..."},
      "finish_reason": "stop"
    },
    "artifacts": [],
    "routing": {"resolved_model": {"name": "...", "version": "..."}}
  },
  "meta": {"requestId": "req_01J..."}
}

Video and other long jobs normally return HTTP 202. A 202 means accepted, not completed. Read task_id, status_url, result_url, and retry_after_seconds.

Poll status according to retry_after_seconds, then read the result only after completed.

• accepted: validated and recorded.
• queued: waiting for execution capacity.
• running: currently executing.
• completed, failed, cancelled, and timed_out are terminal states.

# The 202 response includes status_url and result_url.
curl -H "Authorization: Bearer $GRIDNEXA_AI_API_KEY" \
  "$GRIDNEXA_AI_BASE_URL/v1/tasks/{task_id}"

curl -H "Authorization: Bearer $GRIDNEXA_AI_API_KEY" \
  "$GRIDNEXA_AI_BASE_URL/v1/tasks/{task_id}/result"

Local images and videos use the input-asset upload flow. Create an upload session, PUT the raw file to the presigned URL, complete the upload, and use the ready asset_id in input.

• POST /v1/input-assets/upload-sessions.
• PUT the presigned URL. This request uses the URL signature rather than GridNexa Authorization.
• POST /v1/input-assets/:assetId/complete.
• Use asset_id in the capability-defined input field.

Record the HTTP status, platform error code, message, and meta.requestId.

• 401: verify Bearer plus the raw gnx_ key.
• 422 CAPABILITY_NOT_SUPPORTED: verify capability, model, and execution mode.
• 429: honor Retry-After.
• 410 RESULT_EXPIRED: submit a new task.