Je eerste aanroep¶

Stuur met je Core-API-sleutel een verzoek naar een taalmodel. Controleer daarna het antwoord en de rechten van je sleutel. Je hebt het API-adres van je installatie en een beschikbaar model-id nodig.

Een API-sleutel aanvragen¶

Vraag je beheerder om een API-sleutel, het Core-adres en de model-id's die je kunt gebruiken. De beheerder maakt de sleutel aan in de console. De secret heeft deze vorm:

ack_Zr7mQ1x9t0LpB3vK8sN2wY6cH4dF5gJ

Core toont de secret alleen bij het aanmaken van de sleutel. Bewaar hem bij je andere inloggegevens. Is de secret uitgelekt? Vraag je beheerder dan om de sleutel te roteren. De oude secret werkt direct niet meer. Het id en de geschiedenis van de sleutel blijven behouden.

Stel deze omgevingsvariabelen in voor de voorbeelden in deze handleiding:

export CORE_URL=https://core.example.com/api/v1
export CORE_KEY='ack_...'

Vervang https://core.example.com door het adres van je installatie en ack_... door je secret.

Een verzoek versturen¶

Vervang <een model-id> door een model dat beschikbaar is voor je organisatie:

curl -s -X POST "$CORE_URL/responses" \
    -H "Authorization: Bearer $CORE_KEY" \
    -H "Content-Type: application/json" \
    -d '{"model": "<een model-id>", "input": "Geef me drie namen voor een koffiebar."}'

Gebruik de secret van de API-sleutel direct als bearer-token. Je hoeft niet in te loggen of de secret om te wisselen voor een ander token.

Het antwoord lezen¶

Het antwoord bevat de uitvoer van het model en het tokenverbruik:

{
  "id": "resp_0KQ2mR...",
  "object": "response",
  "status": "completed",
  "model": "<een model-id>",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Bonenbar, Dagelijks Maalsel, Zet & Schenk" }]
    }
  ],
  "usage": { "input_tokens": 14, "output_tokens": 12, "total_tokens": 26 }
}

Controleer status voordat je de uitvoer gebruikt:

Deze statussen kunnen terugkomen met HTTP 200 of 201. De HTTP-code geeft aan of Core het verzoek heeft geaccepteerd en opgeslagen. Het veld status geeft aan hoe de beurt is geëindigd.

Bewaar de antwoordheader X-Request-Id wanneer je een verzoek logt of een probleem meldt. Daarmee zijn de bijbehorende gegevens in Core terug te vinden.

Je capabilities controleren¶

curl -s "$CORE_URL/key" -H "Authorization: Bearer $CORE_KEY"

GET /key geeft de organisatie, de ingeschakelde capabilities en het beleid van je sleutel terug. Een capability is een functie die voor je sleutel beschikbaar is. Het beleid is een lijst rules en een paar settings. Elke regel staat één soort ding toe of verbiedt het: een model, een tool, een host die een tool mag benaderen, een prompt, een skill, een bestand, een gesprek. Een sleutel bereikt iets als een permit het matcht en geen forbid dat doet. Het voorbeeld toont twee van de regels die een sleutel zonder eigen beleid draagt; de volledige lijst en wat elk onderdeel betekent staan in Je eerste regel schrijven.

{
  "id": "key_7Hn2...",
  "tenant_id": "ten_4Kd9...",
  "secret_prefix": "ack_Zr7mQ1x9",
  "name": "Checkout-service",
  "capabilities": { "threads": {}, "files": { "max_bytes": 10485760 } },
  "policy": {
    "rules": [
      { "id": "model", "effect": "permit", "kind": "model",
        "match": { "names": null, "labels": {} }, "when": [] },
      { "id": "thread-own", "effect": "permit", "kind": "thread",
        "match": { "names": null, "labels": {} },
        "when": [{ "atom": "label_is_subject", "label": "subject" }] }
    ],
    "settings": {
      "subjects_required": false,
      "agents_required": false,
      "writable_labels": {},
      "regions_allow": null,
      "region_exceptions": [],
      "host_regions": {}
    }
  }
}

Rechten kunnen veranderen nadat een sleutel is aangemaakt. Gebruik dit endpoint om de huidige instellingen te controleren.

Een 404 oplossen¶

Een 404 betekent dat de resource niet beschikbaar is voor je sleutel. De resource kan ontbreken, bij een andere organisatie horen of een uitgeschakelde capability vereisen.

Controleer eerst GET /key. Vraag je beheerder om een ontbrekende capability in te schakelen. Staat die al aan, controleer dan het resource-id en de organisatie. Core gebruikt voor deze gevallen dezelfde status om geen informatie over resources van andere organisaties prijs te geven.

Volgende stappen¶