One decision per request.

Send the current state, as text, JSON, an image or a short sampled video, plus the two to eight moves your application allows. Trio-Spark returns one choice and a probability for every choice from a single forward pass. Nothing is generated, so there is nothing to parse.

Quickstart

1. Get a key. Sign in and create an API key under API Keys. Every new account includes 100 free decisions. Keep the key on your server: the API is meant to be called from your backend, not from a browser.

2. Make a decision.

curl https://platform.machinefi.com/api/spark/v1/decisions \
  -H "Authorization: Bearer $TRIO_SPARK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "model": "trio-spark",
  "task": "The user asked to export the current report as CSV. Choose the next safe UI action from the available controls.",
  "state": {
    "app": "Reports",
    "screen": "Report details",
    "visible_controls": [
      "Export menu",
      "Filters",
      "Help"
    ]
  },
  "choices": [
    {
      "id": "open_export_menu",
      "description": "Open the Export menu"
    },
    {
      "id": "open_filters",
      "description": "Open report filters"
    },
    {
      "id": "wait",
      "description": "Wait for more information"
    }
  ]
}'

3. Read the answer.

{
  "request_id": "6f1c2a9e-3b7d-4f0a-9c55-2d8e41b7a013",
  "model": "trio-spark",
  "model_version": "trio-spark-2026-10-28",
  "choice_id": "open_export_menu",
  "probabilities": [
    {
      "choice_id": "open_export_menu",
      "probability": 0.894
    },
    {
      "choice_id": "open_filters",
      "probability": 0.041
    },
    {
      "choice_id": "wait",
      "probability": 0.065
    }
  ],
  "confidence": 0.894,
  "disposition": "decide",
  "usage": {
    "billed_input_tokens": 57
  },
  "billing": {
    "amount_nano_usd": "2394",
    "currency": "USD",
    "mode": "paid"
  },
  "latency_ms": 142
}

The same request in Python and in JavaScript (Node 18+):

import os, uuid, requests

resp = requests.post(
    "https://platform.machinefi.com/api/spark/v1/decisions",
    headers={
        "Authorization": f"Bearer {os.environ['TRIO_SPARK_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "model": "trio-spark",
        "task": "Is this support ticket urgent?",
        "state": {"ticket": "Our checkout is down for every customer."},
        "choices": [
            {"id": "urgent", "description": "Needs a response within the hour"},
            {"id": "normal", "description": "Can wait for the normal queue"},
        ],
    },
    timeout=30,
)
resp.raise_for_status()
decision = resp.json()
print(decision["choice_id"], decision["confidence"])

const res = await fetch("https://platform.machinefi.com/api/spark/v1/decisions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TRIO_SPARK_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    model: "trio-spark",
    task: "Is this support ticket urgent?",
    state: { ticket: "Our checkout is down for every customer." },
    choices: [
      { id: "urgent", description: "Needs a response within the hour" },
      { id: "normal", description: "Can wait for the normal queue" },
    ],
  }),
});
const decision = await res.json();

Request

POST https://platform.machinefi.com/api/spark/v1/decisions

The whole input, including task and every choice description, must fit in 1,024 tokens. Include a choice such as wait or ask for review whenever your application needs a safe default.

Response

Use the probabilities to rank choices and to decide when a person should look. Set any automation threshold on a sample of your own labelled cases.

Images and video

Add a media object to the same request. Frames are sent inline as base64 (no data: prefix); URLs are not fetched. A video answer describes only the frames you send.

Single image or camera frame

{
  "model": "trio-spark",
  "task": "Which hand gesture is clearly visible?",
  "state": "Inspect the supplied image only.",
  "choices": [
    {
      "id": "thumbs_up",
      "description": "The thumb points upward"
    },
    {
      "id": "other",
      "description": "A different gesture is visible"
    },
    {
      "id": "unclear",
      "description": "The hand is absent or unclear"
    }
  ],
  "media": {
    "type": "image",
    "frames": [
      {
        "mime_type": "image/jpeg",
        "data_base64": "<BASE64_JPEG>"
      }
    ]
  }
}

Sampled video window

{
  "model": "trio-spark",
  "task": "What happened in this sampled window?",
  "state": "Judge only the supplied frames and timestamps.",
  "choices": [
    {
      "id": "picked_up",
      "description": "The person picked up the cup"
    },
    {
      "id": "not_picked_up",
      "description": "The person did not pick up the cup"
    },
    {
      "id": "unclear",
      "description": "The frames are not enough to tell"
    }
  ],
  "media": {
    "type": "video",
    "frames": [
      {
        "mime_type": "image/jpeg",
        "data_base64": "<BASE64_JPEG_1>",
        "timestamp_ms": 0
      },
      {
        "mime_type": "image/jpeg",
        "data_base64": "<BASE64_JPEG_2>",
        "timestamp_ms": 500
      }
    ]
  }
}

Idempotency and retries

Every decision needs an Idempotency-Key. If a request times out or the connection drops, send the identical request with the same key: a completed decision is returned again, for 24 hours, without a second charge. Sending a different body with a used key returns 409 idempotency_conflict. When an error has retryable: true, retry with exponential backoff; when it also has new_request_required: true, retry with a new key.

Errors

Errors return a JSON body with a stable code, a human-readable message and a retryable flag.

{
  "error": {
    "code": "idempotency_conflict",
    "message": "This Idempotency-Key belongs to another input.",
    "retryable": false
  }
}

Failed and timed-out requests are never charged.

Limits

Need higher throughput? Talk to us.

Billing

$0.042 per million billed input tokens for text and visual input. Output is free. Your first 100 decisions are free and shared between the Playground and your API keys. After that, decisions draw on prepaid credit; top-ups start at $5 and there is no subscription. Replays and failed requests are not charged. See pricing.

Model names

Use trio-spark. It always points to the current release, so your integration improves without code changes; the exact release is reported in model_version. Earlier names (trio-spark-v1.2, trio-spark-v1.3) are still accepted and are served by the same current model. GET https://platform.machinefi.com/v1/models lists every accepted name.

Compatibility endpoints

If you already use a System One-style client, POST https://platform.machinefi.com/v1/systemone accepts the same API key and up to 16 named questions per request (choice, score and noul), including one image. POST https://platform.machinefi.com/v1/evaluate accepts boolean, choice and score questions for evaluation tooling. Each question is billed as one decision. On these endpoints the Idempotency-Key is optional, and errors use the { error: { type, message } } shape. New integrations should use the decisions endpoint above.