1StopTek
← Volver a la documentación para desarrolladores

Referencia de la API de 1st AI Platform

Generada a partir del contrato de la API (OpenAPI 3.1) con el que se prueba el servidor. El acceso para desarrolladores está en fase de pruebas: los endpoints están implementados, pero aún no están disponibles públicamente.

Pruebas restringidas

El acceso está limitado a testers invitados. El host de staging previsto aún no está en línea y no hay ningún modelo conectado: las solicitudes de inferencia devuelven 503 inference_unavailable. No se cobra nada.

Contrato: API v1 · Fuente: 0b847d90d132

Plano de datos

Autenticado con una clave de API de proyecto.

GET/api/v1/openapi.json

This OpenAPI document

Cuerpo de la solicitud

Sin cuerpo de solicitud.

Respuestas

  • 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.

Cuerpo de la solicitud

Sin cuerpo de solicitud.

Respuestas

  • 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

Parámetros

CampoTipoDescripción
model_id (path) · obligatoriostringModel id

Cuerpo de la solicitud

Sin cuerpo de solicitud.

Respuestas

  • 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.

Cuerpo de la solicitud

CampoTipoDescripción
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 · obligatorioobject[]
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

Respuestas

  • 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`)
Ejemplos · 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
  }'
Ejemplos · 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]
Ejemplos · 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.

Cuerpo de la solicitud

CampoTipoDescripción
modelstring
input · obligatoriostring | string[]
encoding_formatany

Respuestas

  • 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`
Ejemplos · 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`.

Parámetros

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

Cuerpo de la solicitud

Sin cuerpo de solicitud.

Respuestas

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