API optymalizacyjne NexOR

Pierwsze obliczenie w trzech krokach

Od zera do prawdziwej odpowiedzi w kilka minut. Miks produkcyjny dwóch wyrobów: maksymalizacja marży przy limitach maszynogodzin i materiałów. Optimum to 30 krzeseł i 5 stołów, funkcja celu 1750.

1. Skopiuj klucz API

   Dowolna nazwa i termin ważności, to cały formularz. Ten klucz identyfikuje konto przy każdym wywołaniu API. Sekret jest pokazywany raz, więc trzeba go od razu skopiować. To jedyny krok wykonywany w przeglądarce.

   Otwórz klucze API

2. Wyślij, zaczekaj, pobierz

   Wystarczy wkleić klucz do poniższego przykładu i go uruchomić: wysłać kopertę, utrzymać jedno żądanie otwarte aż do końca zadania, a potem pobrać rozwiązanie. To najkrótsza droga z laptopa, gdzie nic nie odbierze webhooka. Gdy masz już serwer, zarejestruj webhook i pomiń środkowy krok.

# Set these once. BASE is your NexOR host; the key comes from your portal.
export BASE="https://<your-nexor-host>/solve/v1"
export API_KEY="<your-api-key>"

# 1. Submit the envelope (saved as envelope.json).
curl -s -X POST "$BASE/problems" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d @envelope.json
# -> {"problem_id":"prb_9f3c...","status":"queued","time_limit_seconds":5,...}

# 2. Wait. The request stays open until the problem ends, and timeout_seconds
#    is capped at 60, so repeat the call while the status is queued or running.
#    A server registers a webhook instead and skips this step altogether.
curl -s -X POST "$BASE/problems/prb_9f3c.../wait?timeout_seconds=60" \
  -H "Authorization: Bearer $API_KEY"
# -> the snapshot, with "outcome" set once the solve has ended

# 3. Fetch the solution. Without inline=1 the route answers 302 to a presigned
#    object URL, so a plain curl prints nothing; pass -L to follow it instead.
curl -s "$BASE/problems/prb_9f3c.../result?inline=1" \
  -H "Authorization: Bearer $API_KEY"
# -> {"problem_id":"prb_9f3c...","outcome":"solved","solution":{
#     "outcome":"solved","termination_status":"OPTIMAL","objective_value":1750.0,
#     "result":{"values":{"chairs":30.0,"tables":5.0}}}}

import os, time, requests

BASE = os.environ["SOLVE_BASE"]      # https://<your-nexor-host>/solve/v1
HEAD = {"Authorization": f"Bearer {os.environ['SOLVE_API_KEY']}"}

envelope = {
    "api_version": "1",
    "problem": {
        "variables": [{"name": "chairs", "lower": 0}, {"name": "tables", "lower": 0}],
        "constraints": [
            {"expr": "4*chairs + 8*tables <= 160", "name": "machine_hours"},
            {"expr": "2*chairs + 3*tables <= 75", "name": "material"},
        ],
        "objective": {"sense": "max", "expr": "45*chairs + 80*tables"},
    },
    "solver": "highs",
    "options": {"compute_preset": "cpu-standard", "time_limit_seconds": 5},
}

# 1. Submit.
prb = requests.post(f"{BASE}/problems", json=envelope, headers=HEAD).json()
print("submitted", prb["problem_id"], prb["status"])

# 2. Wait. The request is held open until the problem ends; the 60 second cap
#    means a longer solve answers a snapshot that is not terminal yet, so the
#    call is repeated. For live progress open GET /problems/{id}/events instead.
RUNNING = {"queued", "running"}
while True:
    reply = requests.post(
        f"{BASE}/problems/{prb['problem_id']}/wait",
        params={"timeout_seconds": 60},
        headers=HEAD,
    )
    if reply.status_code == 429:                 # asked to slow down
        time.sleep(int(reply.headers.get("Retry-After", 5)))
        continue
    reply.raise_for_status()
    state = reply.json()
    if state["status"] not in RUNNING:
        break

# 3. Fetch the solution.
reply = requests.get(f"{BASE}/problems/{prb['problem_id']}/result", headers=HEAD)
while reply.status_code == 429:              # a burst of submits spent the budget
    time.sleep(int(reply.headers.get("Retry-After", 5)))
    reply = requests.get(f"{BASE}/problems/{prb['problem_id']}/result", headers=HEAD)
reply.raise_for_status()                     # 410 once past retention
sol = reply.json()
print("outcome:", sol["outcome"])                              # "solved"
print("objective:", sol["solution"]["objective_value"])        # 1750.0
print("values:", sol["solution"]["result"]["values"])  # {"chairs": 30.0, ...}

{
  "api_version": "1",
  "problem": {
    "variables": [
      {
        "name": "chairs",
        "lower": 0
      },
      {
        "name": "tables",
        "lower": 0
      }
    ],
    "constraints": [
      {
        "expr": "4*chairs + 8*tables <= 160",
        "name": "machine_hours"
      },
      {
        "expr": "2*chairs + 3*tables <= 75",
        "name": "material"
      }
    ],
    "objective": {
      "sense": "max",
      "expr": "45*chairs + 80*tables"
    }
  },
  "solver": "highs",
  "options": {
    "compute_preset": "cpu-standard",
    "time_limit_seconds": 5,
    "tags": [
      "quickstart"
    ]
  }
}

Czas na szczegóły? Pełna dokumentacja API

Klucze bearer

Każde żądanie niesie klucz API jako token bearer. Klucze mają zakres ograniczony do API optymalizacji, więc wyciek klucza nie sięgnie niczego innego na koncie.

Authorization: Bearer <your-api-key>

Pierwszy klucz tworzy się w portalu. Później klucze można wypisywać, wydawać i unieważniać przez samo API (zob. Klucze API). Klucze trzymaj po stronie serwera i w razie potrzeby rotuj je bez przestoju.

Koperta zgłoszenia

Jedna wersjonowana koperta obejmująca cztery części. Koperta jest nasza i my ją walidujemy; problem w środku należy do Państwa.

api_version

Wersja protokołu. Dziś zawsze "1".

problem

Model klienta: zmienne, ograniczenia, funkcja celu. Nieprzezroczysty dla nas, walidowany przez solver.

solver

Silnik do uruchomienia: nazwa konkretnego solvera albo nazwa meta-solvera, czyli nazwanego zbioru silników członkowskich, z których każdy może przyjąć zadanie. Strojenie solvera podróżuje wewnątrz problem.

options

time_limit_seconds, compute_preset, webhook, idempotency_key i tags. Wszystkie opcjonalne.

options.compute_preset

Zasoby, które rezerwuje obliczenie, podane kodem (cpu-standard, gpu-standard). Pomiń je, a silnik uruchomi się na własnym profilu domyślnym. GET /solvers wymienia wszystkie profile i silniki, które je oferują.

{
  "api_version": "1",
  "problem": {
    "variables": [
      {
        "name": "chairs",
        "lower": 0
      },
      {
        "name": "tables",
        "lower": 0
      }
    ],
    "constraints": [
      {
        "expr": "4*chairs + 8*tables <= 160",
        "name": "machine_hours"
      },
      {
        "expr": "2*chairs + 3*tables <= 75",
        "name": "material"
      }
    ],
    "objective": {
      "sense": "max",
      "expr": "45*chairs + 80*tables"
    }
  },
  "solver": "highs",
  "options": {
    "compute_preset": "cpu-standard",
    "time_limit_seconds": 5,
    "tags": [
      "quickstart"
    ]
  }
}

Schematy JSON czytelne maszynowo: admission_request_v1.json

Schemat opisuje problem jako obiekt nieprzezroczysty, bo menedżer nigdy go nie czyta. Poniższa sekcja to postać, którą czytają solvery.

Opis modelu

Trzy klucze wewnątrz problem: zmienne decyzyjne, ograniczenia, które muszą spełniać, i jedna funkcja celu. Wyrażenia są łańcuchami znaków i są liniowe.

variables

Lista. Każdy wpis wymaga nazwy name z liter, cyfr i podkreśleń, niezaczynającej się od cyfry. type to continuous (domyślnie), integer albo binary. lower i upper to opcjonalne granice liczbowe; pominięcie jednej zostawia zmienną nieograniczoną z tej strony.

constraints

Lista łańcuchów expr, każdy z opcjonalną nazwą name, która wraca w diagnozie. expr to składniki po lewej, jedna liczba po prawej, połączone przez <=, >= albo ==.

objective

sense przyjmuje wartość min albo max; expr korzysta z tych samych składników, bez porównania i bez stałej. Stała jedynie przesuwa wartość, dlatego jest odrzucana, a nie po cichu pomijana.

Składniki. Składnik to współczynnik, gwiazdka i nazwa zmiennej: 4*chairs. Współczynnik równy jeden można zapisać samą nazwą. Składniki łączy plus albo minus ze spacją po obu stronach: 4*chairs + 8*tables - 2*offcuts. Nic, co nie jest liniowe, nie zostanie przyjęte: żadnych iloczynów dwóch zmiennych, żadnych funkcji, żadnych potęg.

Zadeklarowanie zmiennej jako integer albo binary zamienia program liniowy w mieszany całkowitoliczbowy. Nic innego w kopercie się nie zmienia, a cena to nadal opłata podstawowa plus sekundy. Gotowy przykład poniżej to pełny model z pięcioma zmiennymi binarnymi.

Status i wynik

Dwa zamrożone słowniki. status to cykl życia problemu; gdy osiągnie finished, outcome klasyfikuje odpowiedź.

Rozgałęziaj logikę wyłącznie na tych dwóch polach. Rozwiązanie niesie też dosłowny MOI termination_status solvera (np. OPTIMAL lub TIME_LIMIT) jako szczegół diagnostyczny; traktuj go jako tekst do wyświetlenia, nie jako kontrakt.

Idempotencja

Wystarczy ustawić options.idempotency_key na unikalny łańcuch znaków. Jeśli chwilowy problem z siecią wymusi ponowienie, drugie zgłoszenie zwróci pierwotny problem zamiast tworzyć duplikat (i drugą blokadę kredytów).

"options": { "idempotency_key": "order-4821-solve", "time_limit_seconds": 5 }

Klucze są przypisane do konta. Ponowne użycie tego samego klucza zawsze zwraca pierwszy problem z nim utworzony.

Błędy

Niepowodzenia wracają z pasującym statusem HTTP i treścią JSON. Dopasowuj po code, wyświetlaj message, a gdy winne jest konkretne pole, sięgnij do details.

{ "error": { "code": "invalid_envelope", "message": "...", "details": {...} } }

Limity i kredyty

Twoje użycie ograniczają dwie rzeczy: ile obliczeń działa naraz i jak długo każde może działać.

Współbieżność

concurrency_cap (zob. GET /account) to liczba problemów rozwiązywanych jednocześnie. Powyżej niego nowe zgłoszenia czekają w kolejce.

Kredyty

Obliczenie kosztuje opłatę podstawową swojego silnika plus jego stawkę na profilu obliczeniowym, na którym działa, za sekundę. Koszt maksymalny to ta stawka przez cały time_limit_seconds i jest rezerwowany w chwili przyjęcia problemu; GET /quote podaje tę samą liczbę jeszcze przed wysłaniem. Rozliczenie obciąża faktycznie zużyte sekundy, więc uruchomienie zakończone wcześniej kosztuje mniej, a anulowane obciąża tyle, ile trwało.

Rozwiązania

Pobieranie wyników pojedynczo albo zbiorczo.

# 302 to a presigned URL by default; inline=1 returns the body itself.
curl "$BASE/problems/prb_9f3c.../result?inline=1" \
  -H "Authorization: Bearer $API_KEY"

{
  "problem_id": "prb_9f3c...",
  "outcome": "solved",
  "solution": {
    "solver_used": "highs",
    "outcome": "solved",
    "termination_status": "OPTIMAL",
    "objective_value": 1750.0,
    "result": {"values": {"chairs": 30.0, "tables": 5.0}},
    "metering": {"wall_seconds": 0.4}
  }
}

Solvery i konto

Katalog silników i stan konta.

curl "$BASE/solvers" -H "Authorization: Bearer $API_KEY"

{
  "solvers": [
    {"name": "highs", "display_name": "HiGHS",
     "description": "LP, MIP", "availability": "ok",
     "pricing": {
       "base_fee": 1, "runtime_rate": 1.0,
       "default_preset": "cpu-standard",
       "presets": [
         {"code": "cpu-standard", "name": "CPU Standard",
          "multiplier": 1.0, "is_default": true,
          "effective_rate": 1.0},
         {"code": "cpu-performance", "name": "CPU Performance",
          "multiplier": 2.5, "is_default": false,
          "effective_rate": 2.5}
       ]}}
  ],
  "compute_presets": [
    {"code": "cpu-standard", "name": "CPU Standard",
     "description": "2 vCPU, 4 GiB memory", "is_gpu": false}
  ]
}

# what a 60 second solve on HiGHS would cost, on the larger CPU preset
curl "$BASE/quote?solver=highs&compute_preset=cpu-performance&time_limit_seconds=60" \
  -H "Authorization: Bearer $API_KEY"

{
  "solver": "highs",
  "compute_preset": "cpu-performance",
  "max_runtime_seconds": 60,
  "max_cost": 151,
  "rates": {"highs": {"base_fee": 1, "effective_rate": 2.5}}
}

curl "$BASE/account" -H "Authorization: Bearer $API_KEY"

{
  "name": "Acme Corp",
  "status": "active",
  "concurrency_cap": 4,
  "credit_balance": 4820,
  "credit_available": 4770
}

Webhooki

Konfiguracja i podgląd wychodzących wywołań zwrotnych. Podpisy opisuje przewodnik Webhooki.

curl "$BASE/account/webhook" -H "Authorization: Bearer $API_KEY"

{
  "url": "https://acme.example/hook",
  "events": ["terminal"],
  "secret_prefix": "whsec_<first 8>"
}

curl -X PUT "$BASE/account/webhook" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://acme.example/hook", "events": ["terminal", "progress"]}'

{
  "url": "https://acme.example/hook",
  "events": ["terminal", "progress"],
  "secret_prefix": "whsec_<first 8>"
}

curl -X POST "$BASE/account/webhook/rotate" \
  -H "Authorization: Bearer $API_KEY"

{
  "url": "https://acme.example/hook",
  "events": ["terminal"],
  "secret_prefix": "whsec_<first 8>",
  "secret": "whsec_<the full secret, shown once>"
}

curl -X POST "$BASE/account/webhook/test" \
  -H "Authorization: Bearer $API_KEY"

{
  "id": "dlv_4c1e...",
  "event_id": "evt_8a02...",
  "type": "test",
  "status": "delivered",
  "attempts": [{"at": "2026-09-18T09:12:04Z", "http_status": 200, "error": null}]
}

curl "$BASE/account/webhook/deliveries" \
  -H "Authorization: Bearer $API_KEY"

{
  "deliveries": [
    {"id": "dlv_4c1e...", "event_id": "evt_8a02...",
     "type": "problem.updated", "problem_id": "prb_a",
     "subscriber": "account", "url": "https://acme.example/hook",
     "status": "dead", "attempts": [{"at": "2026-09-18T09:12:04Z",
       "http_status": 500, "error": "server error"}]}
  ],
  "next_cursor": null
}

curl -X POST "$BASE/account/webhook/deliveries/dlv_4c1e.../retry" \
  -H "Authorization: Bearer $API_KEY"

{"id": "dlv_4c1e...", "status": "pending", "attempts": [...]}

Klucze API

Zarządzanie kluczami programowo. Pierwszy klucz tworzy się w portalu.

curl "$BASE/account/keys" -H "Authorization: Bearer $API_KEY"

{
  "keys": [
    {"id": 41, "name": "prod", "prefix": "3f9c1a2b",
     "created_at": "2026-07-01T09:00:00Z", "expires_at": null}
  ]
}

curl -X POST "$BASE/account/keys" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "prod-2026", "expires_days": 365}'

{"id": 42, "name": "prod-2026", "prefix": "7b2e4f9d",
 "key": "<full key, shown once>"}

curl -X DELETE "$BASE/account/keys/41" \
  -H "Authorization: Bearer $API_KEY"

{"revoked": 41}

Zarządzanie kluczami API

Pierwszy klucz tworzysz w portalu (klucz jest potrzebny, aby wywołać API). Później zarządzaj kluczami przez API, aby rotację dało się zautomatyzować.

Rotacja bez przestoju. Utwórz następcę, wdróż go, a potem unieważnij stary klucz. Unieważnienie jedynego klucza jest odrzucane, więc nie odetniesz sobie dostępu.

# Rotate with no downtime: mint the successor, switch over, then revoke.
# 1. Create the replacement (the secret is shown exactly once).
curl -s -X POST "$BASE/account/keys" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "prod-2026"}'
# -> {"id":42,"name":"prod-2026","prefix":"7b2e4f9d","key":"<full key, shown once>"}

# 2. Deploy the new key everywhere, then revoke the old one by id.
curl -s -X DELETE "$BASE/account/keys/41" -H "Authorization: Bearer $NEW_KEY"
# -> {"revoked": 41}

SDK w Pythonie

Koperta jest kontraktem, więc SDK pozostaje tylko cienką warstwą wygody nad nią. Wszystko, co robi jumpy, własny klient może zrobić sam.