LAYA AI · API REFERENCE

Laya AI documentation

Run a short-text decision on the hosted English or multilingual Laya model. The examples below show the HTTP contract, model budgets, and how to read a typed answer.

Base URL https://laya-ai.pro/api · Decision endpoint POST /v1/systemone

API keys and headers

Generate a Laya AI key in the API guide. Send it as a Bearer token from your backend. Jev AI keys and Laya AI keys belong to different accounts and cannot be exchanged.

POST /api/v1/systemone HTTP/1.1
Host: laya-ai.pro
Authorization: Bearer <LAYA_AI_API_KEY>
Content-Type: application/json

Keep the key outside client-side code and source control. Content-Type: application/json identifies the request body.

Model selection

Choose the model in the model field. If omitted, this endpoint selects laya-english. All text models take the same request and return the same answer types. How to choose a model.

Jev-Omni, for images, audio and video, is available in the playground only. For Laya models the total includes state, instructions, and option labels for each question. Oversized input is rejected instead of silently shortened. GET /api/v1/models lists connected models for an authenticated key.

Decisions API compatibility

Send POST https://laya-ai.pro/api/alpha/decisions with your Laya AI Bearer key. This additional endpoint accepts the Decisions request and answer format: model, state, and questions, with noul, choice, and score answers. All three fields are required. The existing /api/v1/systemone endpoint keeps its current behavior.

curl --fail-with-body https://laya-ai.pro/api/alpha/decisions \
  -H "Authorization: Bearer $LAYA_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"laya-english","state":"My payment failed.","questions":{"billing":{"type":"noul","instructions":"Is this about billing?"}}}'

Choose laya-english or laya-multilingual for Laya, with a total per-question budget of 512 or 1024 tokens respectively, including state, instructions, and options. Oversized input receives 422 before a run or balance reservation is created. The endpoint also runs Jev and Mercury Decide: use ~typesafe/jev-latest, typesafe/jev-1.13 or inception/mercury-decide.

Response and billing

The response includes id, the resolved model, provider, answers, and usage.input_tokens / usage.output_tokens. The SDK reads token fields as inputTokens / outputTokens. provider identifies this hosted service, Laya AI.

Billing follows the existing API: paid input tokens first, then one credit for the whole request when tokens are insufficient; output tokens are free. Raw HTTP responses also include billing.mode, billing.input_tokens_charged, and billing.credits_charged. Existing billing headers remain available.

The optional usage.cost field is omitted because prepaid tokens, different plans, and gift credits do not have one per-call USD value. Treat missing cost as unavailable, never as zero. Code that requires a USD cost must use its own billing policy. The SDK may discard our additional billing field; use raw HTTP or the billing headers for these balance units.

Metadata and errors

session_id and user accept nonempty strings up to 256 characters. The body session_id takes precedence over x-session-id. trace accepts an object up to 64 fields and 8192 bytes; known trace labels are strings up to 256 characters. These fields are stored privately with the run and are not sent to inference providers or broadcast destinations. user is a client label and never changes the authenticated account.

Provider routing preferences are unsupported: a non-null provider receives 400. Unknown request fields are rejected. The complete JSON body limit remains 256000 bytes, with at most 64 questions.

Failures return their HTTP status with { "error": { "code": 401, "message": "…" } }. Validation remains 422, insufficient balance is 402, and rate limits are 429. Honor Retry-After when present. A confirmed failed run returns its reserved balance through the same refund flow as the existing endpoint.

Request format

Send POST https://laya-ai.pro/api/v1/systemone with one short state and a map of named questions. This example routes a Spanish message to one of three queues.

{
  "model": "laya-multilingual",
  "state": "El paquete llegó dañado y quiero un reembolso.",
  "questions": {
    "queue": {
      "type": "choice",
      "instructions": "Which queue should handle this message?",
      "criteria": {
        "returns": "Refunds and damaged items",
        "delivery": "Shipping status",
        "other": "Everything else"
      }
    }
  }
}

curl --fail-with-body https://laya-ai.pro/api/v1/systemone \
  -H "Authorization: Bearer $LAYA_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"laya-multilingual","state":"El paquete llegó dañado y quiero un reembolso.","questions":{"queue":{"type":"choice","instructions":"Which queue should handle this message?","criteria":{"returns":"Refunds and damaged items","delivery":"Shipping status","other":"Everything else"}}}}'

A question uses type and instructions. noul returns yes probability; choice requires 2–255 labeled options; score requires 2–10 ordered levels. The JSON body limit is 256000 bytes.

Question shapes

One call can ask several typed questions about the same short state. Give each question a stable ID; it becomes the key under answers. IDs accept letters, digits, underscores, dots, and dashes, up to 64 characters.

{
  "state": "The package is late, and I need a refund before Friday.",
  "questions": {
    "urgent": {
      "type": "noul",
      "instructions": "Does this customer need help today?",
      "criteria": {
        "true": "A same-day response is needed",
        "false": "Normal queue timing is enough"
      }
    },
    "queue": {
      "type": "choice",
      "instructions": "Which team should handle the request?",
      "criteria": {
        "returns": "Refunds and returns",
        "shipping": "Delivery and tracking",
        "other": "All other topics"
      }
    },
    "intensity": {
      "type": "score",
      "instructions": "How urgent is the message?",
      "criteria": [
        "Routine",
        "Soon",
        "Today",
        "Immediate"
      ]
    }
  }
}

The model budget applies to each question together with the state and that question’s instructions and criteria. Keep text concise when asking many questions.

Reading a result

The response maps each question ID to a typed answer. The sample values below show the response structure, not a promised model decision.

{
  "model": "laya-multilingual",
  "answers": {
    "queue": {
      "type": "choice",
      "choice": "returns",
      "probabilities": {
        "returns": 0.91,
        "delivery": 0.06,
        "other": 0.03
      },
      "confidence": 0.91
    }
  },
  "usage": {
    "input_tokens": 66,
    "output_tokens": 12
  }
}

Use answers.queue.choice for the selected queue and inspect probabilities before choosing a review threshold. usage.input_tokens and usage.output_tokens report model usage.

Usage response headers

The hosted API spends paid input tokens first. If the token balance cannot cover a call, it uses one credit for the whole request. It does not split one call across both balances; output tokens are free.

Pricing explains the current credit and token offers.

List connected models

GET /api/v1/models requires a Laya Bearer key and returns { "models": [...] }. Each item has name and description. Only connected Laya models appear, so an empty list means your client should wait before sending a decision request.

curl https://laya-ai.pro/api/v1/models \
  -H "Authorization: Bearer $LAYA_AI_API_KEY"

Use this response for model selection. The public status route below is suited to readiness checks; it does not authenticate a user or return account-specific model descriptions.

Error handling

The account limit is 1000 API requests per minute. When a response supplies Retry-After, wait at least that long.

Health and local setup

GET /api/laya/status is a public readiness check. It returns ready, connected models, and a reason string. Readiness requires account setup, database, and at least one model connection; this call does not run a decision.

curl https://laya-ai.pro/api/laya/status

For a deployment you manage yourself, use the local setup guide. Local model weights and runtime are separate from this hosted API and its account balances.