1StopTek
← Zurück zur Entwicklerdokumentation

1st AI Platform API-Referenz

Generiert aus dem API-Vertrag (OpenAPI 3.1), gegen den der Server getestet wird. Der Entwicklerzugang befindet sich in Erprobung: Die Endpunkte sind implementiert, aber noch nicht öffentlich verfügbar.

Eingeschränkter Test

Zugang nur für eingeladene Tester. Der geplante Staging-Host ist noch nicht online, und es ist kein Modell angebunden: Inferenz-Anfragen beantworten 503 inference_unavailable. Nichts wird berechnet.

Vertrag: API v1 · Quelle: 0b847d90d132

Data Plane

Authentifiziert mit einem Projekt-API-Schlüssel.

GET/api/v1/openapi.json

This OpenAPI document

Anfrage-Body

Kein Anfrage-Body.

Antworten

  • 200 OpenAPI 3.1 document

GET/api/v1/models

List the models this key may use

Scope `models:read`. Only models that are policy-eligible for the organization and currently servable are listed.

Anfrage-Body

Kein Anfrage-Body.

Antworten

  • 200 OK
  • 401 Missing or invalid credential (`authentication_error`)
  • 403 Not allowed / insufficient scope (`permission_error`)
  • 429 Rate limited (`rate_limit_error`); see `Retry-After`

GET/api/v1/models/{model_id}

Get one model

Parameter

FeldTypBeschreibung
model_id (path) · erforderlichstringModel id

Anfrage-Body

Kein Anfrage-Body.

Antworten

  • 200 OK
  • 401 Missing or invalid credential (`authentication_error`)
  • 403 Not allowed / insufficient scope (`permission_error`)
  • 404 Not found (`not_found_error`)

POST/api/v1/chat/completions

Create a chat completion

Scope `chat:write`. With `stream: true` the response is `text/event-stream`: `data: <ChatCompletionChunk>` events, ending with `data: [DONE]`. A failure after the stream started is sent as `data: {"error": {...}}` before `[DONE]`. Everything that can be refused (validation, safety, limits, model selection) is refused with an HTTP status BEFORE the stream starts.

Anfrage-Body

FeldTypBeschreibung
modelstringA model id from /api/v1/models; omit or `auto` for the environment's default model; if it is unavailable, the request may fail over only to a deployment declared equivalent to it. An explicit model is never substituted.
messages · erforderlichobject[]
max_tokensintegerCapped at the model's and the tier's output limit
max_completion_tokensintegerAlias of max_tokens
temperaturenumber
streamboolean
response_formatobjectStructured output on models with `structured_output`. Not combinable with stream in v1.
userstringAccepted for compatibility; NOT stored

Antworten

  • 200 Completion (or event stream when `stream: true`)
  • 400 Invalid request (`invalid_request_error`)
  • 401 Missing or invalid credential (`authentication_error`)
  • 402 Monthly token allowance used up (`quota_exceeded_error`, code `monthly_quota_exceeded`) or the organization's spending limit would be exceeded (code `spending_limit_reached`; `currency`, `hard_limit_micros`, exact `month_to_date_cost_pico`, `held_cost_pico` (open reservations), `request_worst_case_pico`, and their rounded `*_micros` display values)
  • 403 Not allowed / insufficient scope (`permission_error`)
  • 404 Not found (`not_found_error`)
  • 413 Input too large
  • 422 Refused by the Safety Layer before any model call (`safety_error`, code `safety_refused`)
  • 429 Rate limited (`rate_limit_error`); see `Retry-After`
  • 500 Internal error (`api_error`)
  • 502 Model failure or invalid structured output (`model_error`)
  • 503 No model available (`service_unavailable_error`); retry; or usage/spend limits cannot be checked (code `billing_unavailable`, `service_unavailable_error`; fail closed, nothing was run); retry after `Retry-After`
  • 504 Model timeout (`model_error`)
Beispiele · chat
curl -sS "$FIRSTAI_BASE_URL/api/v1/chat/completions" \
  -H "Authorization: Bearer $FIRSTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "system", "content": "You answer in one sentence."},
      {"role": "user", "content": "What is an API key?"}
    ],
    "max_tokens": 120
  }'
Beispiele · stream
curl -sS -N "$FIRSTAI_BASE_URL/api/v1/chat/completions" \
  -H "Authorization: Bearer $FIRSTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Count from one to five."}],
    "max_tokens": 60,
    "stream": true
  }'
# data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"One"},...}]}
# ...
# data: [DONE]
Beispiele · structured
curl -sS "$FIRSTAI_BASE_URL/api/v1/chat/completions" \
  -H "Authorization: Bearer $FIRSTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Extract: Berlin is the capital of Germany."}],
    "max_tokens": 120,
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "fact",
        "schema": {
          "type": "object",
          "properties": {"city": {"type": "string"}, "country": {"type": "string"}},
          "required": ["city", "country"]
        }
      }
    }
  }'

POST/api/v1/embeddings

Create embeddings

Scope `embeddings:write`. L2-normalized float vectors.

Anfrage-Body

FeldTypBeschreibung
modelstring
input · erforderlichstring | string[]
encoding_formatany

Antworten

  • 200 OK
  • 400 Invalid request (`invalid_request_error`)
  • 401 Missing or invalid credential (`authentication_error`)
  • 402 Monthly token allowance used up (`quota_exceeded_error`, code `monthly_quota_exceeded`) or the organization's spending limit would be exceeded (code `spending_limit_reached`; `currency`, `hard_limit_micros`, exact `month_to_date_cost_pico`, `held_cost_pico` (open reservations), `request_worst_case_pico`, and their rounded `*_micros` display values)
  • 403 Not allowed / insufficient scope (`permission_error`)
  • 404 Not found (`not_found_error`)
  • 413 Input too large
  • 429 Rate limited (`rate_limit_error`); see `Retry-After`
  • 503 Embeddings unavailable; or usage/spend limits cannot be checked (code `billing_unavailable`, `service_unavailable_error`; fail closed, nothing was run); retry after `Retry-After`
Beispiele · embeddings
curl -sS "$FIRSTAI_BASE_URL/api/v1/embeddings" \
  -H "Authorization: Bearer $FIRSTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": ["first document", "second document"]}'

GET/api/v1/usage

Usage of this key's project

Scope `usage:read`.

Parameter

FeldTypBeschreibung
from (query)stringStart date YYYY-MM-DD (default: first of the month)
to (query)stringEnd date YYYY-MM-DD (default: today, UTC)

Anfrage-Body

Kein Anfrage-Body.

Antworten

  • 200 OK
  • 400 Invalid request (`invalid_request_error`)
  • 401 Missing or invalid credential (`authentication_error`)
  • 403 Not allowed / insufficient scope (`permission_error`)
Beispiele · usage
curl -sS "$FIRSTAI_BASE_URL/api/v1/usage" \
  -H "Authorization: Bearer $FIRSTAI_API_KEY"