Hazeloft AI Gateway | Documentație Hazeloft

Hazeloft AI Gateway îți dă acces la modele AI printr-un endpoint compatibil cu API-ul OpenAI. Folosești o singură cheie hzx_, iar consumul se scade din cota contului tău Hazeloft. Îl poți folosi în două feluri: cu pachetul nostru @hazeloft/ai sau direct, cu orice client HTTP.

Ce primești

O cheie API hzx_… (secretă, afișată o singură dată).
Un endpoint compatibil OpenAI: POST /v1/chat/completions și GET /v1/models.
Cota de tokeni a planului tău — consumul fiecărei cereri se scade din contul tău.

Autentificare

Toate cererile trec prin header-ul Authorization:

Header

Authorization: Bearer hzx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Pune cheia în mediu:

.env

HAZELOFT_API_KEY=hzx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Endpoint-ul gateway-ului este https://gateway.hazeloft.com/v1.

Varianta 1 — cu pachetul `@hazeloft/ai`

Cel mai scurt mod. Pachetul are zero dependențe și rulează în Node, edge și browser (server-side).

Terminal

npm i @hazeloft/ai

ai.ts

import { Hazeloft } from "@hazeloft/ai";
 
const hz = new Hazeloft(); // citește HAZELOFT_API_KEY
 
// Răspuns complet
const res = await hz.chat({
  messages: [{ role: "user", content: "Scrie un haiku despre mare." }],
});
console.log(res.content, res.usage);

Streaming — primești fragmentele pe măsură ce sunt generate:

stream.ts

for await (const delta of hz.stream({
  messages: [{ role: "user", content: "Numără de la 1 la 5." }],
})) {
  process.stdout.write(delta);
}

Listează modelele activate pe contul tău:

models.ts

const models = await hz.models();
console.log(models);

Erorile sunt tipate (HazeloftAuthError, HazeloftRateLimitError, …), toate moștenind din HazeloftError cu status, code și requestId:

errors.ts

import { HazeloftRateLimitError } from "@hazeloft/ai";
 
try {
  await hz.chat({ messages });
} catch (err) {
  if (err instanceof HazeloftRateLimitError && err.isQuota) {
    // cota lunară epuizată
  }
}

Varianta 2 — direct în cod (fără pachet)

Endpoint-ul fiind compatibil OpenAI, îl apelezi cu orice client HTTP, din orice limbaj.

Terminal

curl "https://gateway.hazeloft.com/v1/chat/completions" \
  -H "Authorization: Bearer $HAZELOFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "Salut" }]
  }'

Același apel din Node, cu fetch:

chat.ts

const response = await fetch("https://gateway.hazeloft.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HAZELOFT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    messages: [{ role: "user", content: "Salut" }],
  }),
});
 
const data = await response.json();
console.log(data.choices[0].message.content);

Răspuns (non-streaming):

200 OK

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "<model>",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Salut!" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 8, "completion_tokens": 3, "total_tokens": 11 }
}

Pentru streaming, trimite "stream": true și citește răspunsul ca Server-Sent Events (data: {…}, terminat cu data: [DONE]):

stream-raw.ts

const response = await fetch("https://gateway.hazeloft.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HAZELOFT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    messages: [{ role: "user", content: "Numără de la 1 la 5." }],
    stream: true,
  }),
});
 
const reader = response.body.getReader();
const decoder = new TextDecoder();
for (;;) {
  const { done, value } = await reader.read();
  if (done) break;
  for (const line of decoder.decode(value).split("\n")) {
    if (!line.startsWith("data:")) continue;
    const data = line.slice(5).trim();
    if (data === "[DONE]") break;
    const chunk = JSON.parse(data);
    process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
  }
}

Modele disponibile

Lista modelelor și ID-urile lor sunt configurate pe contul tău. La runtime le poți descoperi oricând cu GET /v1/models (sau hz.models()). Dacă omiți model din cerere, gateway-ul folosește modelul implicit al contului.

Parametri

Câmp	Tip	Note
`messages`	`Message[]`	Obligatoriu. 1–64 mesaje, roluri `system` / `user` / `assistant`.
`model`	`string`	Opțional. Implicit: modelul contului.
`temperature`	`number`	Opțional, 0–2.
`max_tokens`	`number`	Opțional. Limita de tokeni de ieșire (`maxTokens` în pachet).
`stream`	`boolean`	Opțional. `true` pentru Server-Sent Events.

Erori

Formatul erorilor e compatibil OpenAI: { "error": { "message", "type", "code" } }.

Status	Cod	Când
400 / 413	`invalid_request_error`, `model_not_found`, `request_too_large`	cerere invalidă
401 / 403	`invalid_api_key`, `integration_inactive`, `insufficient_plan`	autentificare / acces
429	`rate_limited`	prea multe cereri pe minut
429	`usage_limit_exceeded`	cota lunară epuizată
502 / 503	`upstream_error`	furnizorul upstream a eșuat

Limite

Regulă	Valoare
Mesaje / cerere	1–64
Lungime conținut / mesaj	24.000 caractere
Dimensiune maximă a cererii	256 KB
Rate limit	120 cereri / minut (per cheie și per IP)

Referință rapidă

Operație	Metodă	Cale
Chat (sincron / streaming)	`POST`	`/v1/chat/completions`
Listă modele	`GET`	`/v1/models`

Ce primești

O cheie API hzx_… (secretă, afișată o singură dată).
Un endpoint compatibil OpenAI: POST /v1/chat/completions și GET /v1/models.
Cota de tokeni a planului tău — consumul fiecărei cereri se scade din contul tău.

Autentificare

Toate cererile trec prin header-ul Authorization:

Header

Authorization: Bearer hzx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Pune cheia în mediu:

.env

HAZELOFT_API_KEY=hzx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Endpoint-ul gateway-ului este https://gateway.hazeloft.com/v1.

Varianta 1 — cu pachetul `@hazeloft/ai`

Cel mai scurt mod. Pachetul are zero dependențe și rulează în Node, edge și browser (server-side).

Terminal

npm i @hazeloft/ai

ai.ts

import { Hazeloft } from "@hazeloft/ai";
 
const hz = new Hazeloft(); // citește HAZELOFT_API_KEY
 
// Răspuns complet
const res = await hz.chat({
  messages: [{ role: "user", content: "Scrie un haiku despre mare." }],
});
console.log(res.content, res.usage);

Streaming — primești fragmentele pe măsură ce sunt generate:

stream.ts

for await (const delta of hz.stream({
  messages: [{ role: "user", content: "Numără de la 1 la 5." }],
})) {
  process.stdout.write(delta);
}

Listează modelele activate pe contul tău:

models.ts

const models = await hz.models();
console.log(models);

Erorile sunt tipate (HazeloftAuthError, HazeloftRateLimitError, …), toate moștenind din HazeloftError cu status, code și requestId:

errors.ts

import { HazeloftRateLimitError } from "@hazeloft/ai";
 
try {
  await hz.chat({ messages });
} catch (err) {
  if (err instanceof HazeloftRateLimitError && err.isQuota) {
    // cota lunară epuizată
  }
}

Varianta 2 — direct în cod (fără pachet)

Endpoint-ul fiind compatibil OpenAI, îl apelezi cu orice client HTTP, din orice limbaj.

Terminal

curl "https://gateway.hazeloft.com/v1/chat/completions" \
  -H "Authorization: Bearer $HAZELOFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "Salut" }]
  }'

Același apel din Node, cu fetch:

chat.ts

const response = await fetch("https://gateway.hazeloft.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HAZELOFT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    messages: [{ role: "user", content: "Salut" }],
  }),
});
 
const data = await response.json();
console.log(data.choices[0].message.content);

Răspuns (non-streaming):

200 OK

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "<model>",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Salut!" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 8, "completion_tokens": 3, "total_tokens": 11 }
}

Pentru streaming, trimite "stream": true și citește răspunsul ca Server-Sent Events (data: {…}, terminat cu data: [DONE]):

stream-raw.ts

const response = await fetch("https://gateway.hazeloft.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HAZELOFT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    messages: [{ role: "user", content: "Numără de la 1 la 5." }],
    stream: true,
  }),
});
 
const reader = response.body.getReader();
const decoder = new TextDecoder();
for (;;) {
  const { done, value } = await reader.read();
  if (done) break;
  for (const line of decoder.decode(value).split("\n")) {
    if (!line.startsWith("data:")) continue;
    const data = line.slice(5).trim();
    if (data === "[DONE]") break;
    const chunk = JSON.parse(data);
    process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
  }
}

Modele disponibile

Parametri

Câmp	Tip	Note
`messages`	`Message[]`	Obligatoriu. 1–64 mesaje, roluri `system` / `user` / `assistant`.
`model`	`string`	Opțional. Implicit: modelul contului.
`temperature`	`number`	Opțional, 0–2.
`max_tokens`	`number`	Opțional. Limita de tokeni de ieșire (`maxTokens` în pachet).
`stream`	`boolean`	Opțional. `true` pentru Server-Sent Events.

Erori

Formatul erorilor e compatibil OpenAI: { "error": { "message", "type", "code" } }.

Status	Cod	Când
400 / 413	`invalid_request_error`, `model_not_found`, `request_too_large`	cerere invalidă
401 / 403	`invalid_api_key`, `integration_inactive`, `insufficient_plan`	autentificare / acces
429	`rate_limited`	prea multe cereri pe minut
429	`usage_limit_exceeded`	cota lunară epuizată
502 / 503	`upstream_error`	furnizorul upstream a eșuat

Limite

Regulă	Valoare
Mesaje / cerere	1–64
Lungime conținut / mesaj	24.000 caractere
Dimensiune maximă a cererii	256 KB
Rate limit	120 cereri / minut (per cheie și per IP)

Referință rapidă

Operație	Metodă	Cale
Chat (sincron / streaming)	`POST`	`/v1/chat/completions`
Listă modele	`GET`	`/v1/models`

#Ce primești

#Autentificare

#Varianta 1 — cu pachetul @hazeloft/ai

#Varianta 2 — direct în cod (fără pachet)

#Modele disponibile

#Parametri

#Erori

#Limite

#Referință rapidă

#Ce primești

#Autentificare

#Varianta 1 — cu pachetul @hazeloft/ai

#Varianta 2 — direct în cod (fără pachet)

#Modele disponibile

#Parametri

#Erori

#Limite

#Referință rapidă

Ce primești

Autentificare

Varianta 1 — cu pachetul `@hazeloft/ai`

Varianta 2 — direct în cod (fără pachet)

Modele disponibile

Parametri

Erori

Limite

Referință rapidă

Ce primești

Autentificare

Varianta 1 — cu pachetul `@hazeloft/ai`

Varianta 2 — direct în cod (fără pachet)

Modele disponibile

Parametri

Erori

Limite

Referință rapidă