Quickstart — 5 minutes

De zéro à votre premier appel API.

Étape 1 — Créer un compte

Rendez-vous sur heberking.ai/register. Aucune CB requise pour l'essai gratuit.

Étape 2 — Déployer une instance

1. Allez dans Instances → Nouvelle instance
2. Choisissez un modèle : gemma3:4b (recommandé pour débuter)
3. Cliquez Créer — l'instance est prête en ~30 secondes
4. Notez l'ID de l'instance (affiché dans la liste)

Étape 3 — Obtenir une clé API

1. Allez dans Paramètres → Clés API
2. Cliquez Nouvelle clé, donnez-lui un nom
3. Copiez la clé hk_live_... — elle n'est affichée qu'une fois

Étape 4 — Premier appel

curl https://heberking.ai/api/instances/123/ollama/v1/chat/completions \
  -H "Authorization: Bearer hk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma3:4b",
    "messages": [{"role": "user", "content": "Bonjour !"}]
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://heberking.ai/api/instances/123/ollama/v1",
    api_key="hk_live_..."
)

response = client.chat.completions.create(
    model="gemma3:4b",
    messages=[{"role": "user", "content": "Bonjour !"}]
)
print(response.choices[0].message.content)

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://heberking.ai/api/instances/123/ollama/v1',
  apiKey: 'hk_live_...',
});

const response = await client.chat.completions.create({
  model: 'gemma3:4b',
  messages: [{ role: 'user', content: 'Bonjour !' }],
});
console.log(response.choices[0].message.content);

Authentification

Heberking AI accepte deux méthodes d'authentification pour l'API :

Clé API (recommandé pour la production)

Authorization: Bearer hk_live_<votre_clé>

Les clés API commencent toujours par hk_live_. Elles sont générées dans Paramètres → Clés API et stockées sous forme de hash SHA-256 côté serveur (non récupérables).

Bonnes pratiques

• Ne committez jamais une clé dans Git — utilisez des variables d'environnement
• Créez une clé par application / environnement
• Révoquez immédiatement les clés compromises

# .env
HEBERKING_API_KEY=hk_live_...
HEBERKING_INSTANCE_ID=123

import os
from openai import OpenAI

client = OpenAI(
    base_url=f"https://heberking.ai/api/instances/{os.environ['HEBERKING_INSTANCE_ID']}/ollama/v1",
    api_key=os.environ["HEBERKING_API_KEY"]
)

JWT (sessions web)

Pour le dashboard et le chat intégré, un JWT est utilisé. Il est obtenu via POST /api/auth/login et a une durée de vie de 7 jours. Non recommandé pour l'intégration API.

Sécurité des requêtes

Instances

Une instance est un conteneur Docker avec Ollama, dédié à votre compte. Chaque instance a son propre port Ollama et son modèle configuré.

États d'une instance

Endpoint de l'API

Une fois l'instance en état running, son endpoint est :

https://heberking.ai/api/instances/{instance_id}/ollama/v1/

C'est un proxy compatible OpenAI qui supporte tous les endpoints Ollama :

Modèles disponibles

Heberking AI supporte tous les modèles du catalogue Ollama. Voici les modèles recommandés :

Lister les modèles installés

curl https://heberking.ai/api/instances/123/ollama/v1/models \
  -H "Authorization: Bearer hk_live_..."

Chat completions

L'endpoint principal, 100% compatible avec l'API OpenAI /v1/chat/completions.

Endpoint

POST /api/instances/{instance_id}/ollama/v1/chat/completions

Body de la requête

Exemple complet

curl https://heberking.ai/api/instances/123/ollama/v1/chat/completions \
  -H "Authorization: Bearer hk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma3:4b",
    "temperature": 0.7,
    "messages": [
      {"role": "system", "content": "Tu es un assistant expert en droit français."},
      {"role": "user", "content": "Qu'\''est-ce qu'\''un KBIS ?"}
    ]
  }'

Réponse

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "gemma3:4b",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Le KBIS est un document officiel..."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 128,
    "total_tokens": 170
  }
}

Conversation multi-tours

messages = [
    {"role": "system", "content": "Tu es un assistant utile."},
    {"role": "user", "content": "Qu'est-ce que Python ?"},
    {"role": "assistant", "content": "Python est un langage de programmation..."},
    {"role": "user", "content": "Et ses principaux avantages ?"}
]

Streaming SSE

Activez le streaming pour recevoir les tokens au fur et à mesure, réduisant la latence perçue.

Activer le streaming

Ajoutez "stream": true à votre requête. La réponse sera un flux SSE (Server-Sent Events).

from openai import OpenAI

client = OpenAI(
    base_url="https://heberking.ai/api/instances/123/ollama/v1",
    api_key="hk_live_..."
)

stream = client.chat.completions.create(
    model="gemma3:4b",
    messages=[{"role": "user", "content": "Raconte-moi une blague."}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://heberking.ai/api/instances/123/ollama/v1',
  apiKey: 'hk_live_...',
});

const stream = await client.chat.completions.create({
  model: 'gemma3:4b',
  messages: [{ role: 'user', content: 'Raconte-moi une blague.' }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

curl https://heberking.ai/api/instances/123/ollama/v1/chat/completions \
  -H "Authorization: Bearer hk_live_..." \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "model": "gemma3:4b",
    "stream": true,
    "messages": [{"role": "user", "content": "Raconte-moi une blague."}]
  }'

Format des chunks SSE

data: {"id":"chatcmpl-...","choices":[{"delta":{"content":"La"},"index":0}]}
data: {"id":"chatcmpl-...","choices":[{"delta":{"content":" blague"},"index":0}]}
data: {"id":"chatcmpl-...","choices":[{"delta":{"content":"..."},"index":0}]}
data: [DONE]

Migration depuis OpenAI

L'API Heberking AI est un drop-in replacement pour l'API OpenAI. Dans la plupart des cas, 2 lignes suffisent.

Python (openai SDK)

# Avant
from openai import OpenAI
client = OpenAI(api_key="sk-...")

# Après
from openai import OpenAI
client = OpenAI(
    base_url="https://heberking.ai/api/instances/123/ollama/v1",
    api_key="hk_live_..."
)

Node.js / TypeScript

// Avant
const client = new OpenAI({ apiKey: 'sk-...' });

// Après
const client = new OpenAI({
  baseURL: 'https://heberking.ai/api/instances/123/ollama/v1',
  apiKey: 'hk_live_...',
});

Variables d'environnement

# .env
OPENAI_API_BASE=https://heberking.ai/api/instances/123/ollama/v1
OPENAI_API_KEY=hk_live_...

from openai import OpenAI
import os

# Lit OPENAI_API_BASE et OPENAI_API_KEY automatiquement
client = OpenAI(
    base_url=os.environ.get("OPENAI_API_BASE"),
    api_key=os.environ.get("OPENAI_API_KEY")
)

Correspondance des noms de modèles

Intégration Python

Installation

pip install openai

Client de base

from openai import OpenAI
import os

client = OpenAI(
    base_url=f"https://heberking.ai/api/instances/{os.environ['HK_INSTANCE_ID']}/ollama/v1",
    api_key=os.environ["HK_API_KEY"]
)

Chat simple

response = client.chat.completions.create(
    model="gemma3:4b",
    messages=[{"role": "user", "content": "Explique la récursivité en 3 phrases."}]
)
print(response.choices[0].message.content)

Streaming

with client.chat.completions.create(
    model="gemma3:4b",
    messages=[{"role": "user", "content": "Génère un poème sur la mer."}],
    stream=True
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Avec system prompt

def ask_assistant(question: str, system: str = "Tu es un assistant utile.") -> str:
    response = client.chat.completions.create(
        model="gemma3:4b",
        messages=[
            {"role": "system", "content": system},
            {"role": "user", "content": question}
        ],
        temperature=0.7,
        max_tokens=1000
    )
    return response.choices[0].message.content

# Usage
answer = ask_assistant(
    "Rédige un email professionnel pour reporter une réunion.",
    system="Tu es un assistant en communication professionnelle."
)
print(answer)

Embeddings (RAG)

# Assurez-vous que nomic-embed-text est installé sur l'instance
embedding = client.embeddings.create(
    model="nomic-embed-text",
    input="Texte à vectoriser"
)
vector = embedding.data[0].embedding  # Liste de floats

Async avec asyncio

import asyncio
from openai import AsyncOpenAI

async_client = AsyncOpenAI(
    base_url="https://heberking.ai/api/instances/123/ollama/v1",
    api_key="hk_live_..."
)

async def main():
    response = await async_client.chat.completions.create(
        model="gemma3:4b",
        messages=[{"role": "user", "content": "Bonjour async !"}]
    )
    print(response.choices[0].message.content)

asyncio.run(main())

Node.js / TypeScript

Installation

npm install openai

Client de base (ES Modules)

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: `https://heberking.ai/api/instances/${process.env.HK_INSTANCE_ID}/ollama/v1`,
  apiKey: process.env.HK_API_KEY,
});

Chat simple

const response = await client.chat.completions.create({
  model: 'gemma3:4b',
  messages: [{ role: 'user', content: 'Explique les closures JavaScript.' }],
});
console.log(response.choices[0].message.content);

Streaming

const stream = client.chat.completions.stream({
  model: 'gemma3:4b',
  messages: [{ role: 'user', content: 'Génère 5 idées de startup.' }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}

const finalMessage = await stream.finalMessage();
console.log('\nTokens utilisés:', finalMessage.usage?.total_tokens);

Avec TypeScript

import OpenAI from 'openai';
import { ChatCompletionMessageParam } from 'openai/resources/chat';

const client = new OpenAI({
  baseURL: 'https://heberking.ai/api/instances/123/ollama/v1',
  apiKey: process.env.HK_API_KEY!,
});

async function chat(messages: ChatCompletionMessageParam[]): Promise<string> {
  const response = await client.chat.completions.create({
    model: 'gemma3:4b',
    messages,
    temperature: 0.7,
  });
  return response.choices[0].message.content ?? '';
}

Intégration Next.js (API Route)

// app/api/chat/route.ts
import { NextRequest } from 'next/server';
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: `https://heberking.ai/api/instances/${process.env.HK_INSTANCE_ID}/ollama/v1`,
  apiKey: process.env.HK_API_KEY,
});

export async function POST(req: NextRequest) {
  const { messages } = await req.json();

  const stream = await client.chat.completions.create({
    model: 'gemma3:4b',
    messages,
    stream: true,
  });

  const encoder = new TextEncoder();
  const readable = new ReadableStream({
    async start(controller) {
      for await (const chunk of stream) {
        const text = chunk.choices[0]?.delta?.content ?? '';
        if (text) controller.enqueue(encoder.encode(text));
      }
      controller.close();
    },
  });

  return new Response(readable, {
    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
  });
}

cURL & HTTP

Chat completion

curl https://heberking.ai/api/instances/123/ollama/v1/chat/completions \
  -H "Authorization: Bearer hk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma3:4b",
    "messages": [
      {"role": "system", "content": "Réponds toujours en français."},
      {"role": "user", "content": "Quelle est la capitale de la France ?"}
    ],
    "temperature": 0.3
  }'

Streaming

curl https://heberking.ai/api/instances/123/ollama/v1/chat/completions \
  -H "Authorization: Bearer hk_live_..." \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{"model":"gemma3:4b","stream":true,"messages":[{"role":"user","content":"Compte jusqu'\''à 10 lentement."}]}'

Lister les modèles

curl https://heberking.ai/api/instances/123/ollama/v1/models \
  -H "Authorization: Bearer hk_live_..."

Embeddings

curl https://heberking.ai/api/instances/123/ollama/v1/embeddings \
  -H "Authorization: Bearer hk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"model":"nomic-embed-text","input":"Texte à vectoriser"}'

Completions (legacy)

curl https://heberking.ai/api/instances/123/ollama/v1/completions \
  -H "Authorization: Bearer hk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"model":"gemma3:4b","prompt":"La photosynthèse est","max_tokens":200}'

LangChain & LlamaIndex

LangChain (Python)

pip install langchain-openai

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gemma3:4b",
    openai_api_base="https://heberking.ai/api/instances/123/ollama/v1",
    openai_api_key="hk_live_...",
    temperature=0.7
)

# Utilisation directe
from langchain.schema import HumanMessage
response = llm([HumanMessage(content="Explique le RAG en 3 phrases.")])
print(response.content)

LangChain + RAG

from langchain_openai import ChatOpenAI, OpenAIEmbeddings
from langchain.vectorstores import FAISS
from langchain.chains import RetrievalQA

# LLM
llm = ChatOpenAI(
    model="gemma3:27b",
    openai_api_base="https://heberking.ai/api/instances/123/ollama/v1",
    openai_api_key="hk_live_..."
)

# Embeddings locaux
embeddings = OpenAIEmbeddings(
    model="nomic-embed-text",
    openai_api_base="https://heberking.ai/api/instances/123/ollama/v1",
    openai_api_key="hk_live_..."
)

# Vectorstore
texts = ["Document 1 sur le RGPD...", "Document 2 sur la conformité..."]
vectorstore = FAISS.from_texts(texts, embeddings)

# Chain RAG
qa = RetrievalQA.from_chain_type(
    llm=llm,
    chain_type="stuff",
    retriever=vectorstore.as_retriever()
)

result = qa.run("Qu'est-ce que le RGPD impose aux entreprises ?")
print(result)

LlamaIndex

pip install llama-index-llms-openai

from llama_index.llms.openai import OpenAI
from llama_index.core import Settings

Settings.llm = OpenAI(
    model="gemma3:4b",
    api_base="https://heberking.ai/api/instances/123/ollama/v1",
    api_key="hk_live_..."
)

Gestion des clés API

Créer une clé

1. Allez dans Paramètres → Clés API
2. Cliquez Nouvelle clé
3. Donnez un nom descriptif (ex: "Prod", "Dev local", "CI/CD")
4. Copiez la clé — elle commence par hk_live_ et n'est affichée qu'une seule fois

Rotation des clés

Bonne pratique : effectuez une rotation des clés tous les 90 jours.

1. Créez une nouvelle clé
2. Mettez à jour vos variables d'environnement
3. Vérifiez que tout fonctionne
4. Révoquez l'ancienne clé

Limites

Maximum 10 clés API actives par compte. Vous pouvez en créer autant que nécessaire en révoquant les anciennes.

Webhooks

Recevez des notifications HTTP lors d'événements sur vos instances.

Événements disponibles

Format du payload

POST https://votre-serveur.com/webhook
Content-Type: application/json
X-HK-Signature: sha256=<hmac_hex>

{
  "event": "instance.started",
  "instance_id": 42,
  "instance_name": "mon-llm-prod",
  "timestamp": "2026-05-08T14:30:00Z"
}

Vérifier la signature

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Configurer un webhook

Allez dans Paramètres → Webhooks pour créer et gérer vos webhooks.

Codes d'erreur

Format d'erreur

{
  "detail": "Instance non démarrée"
}

Gestion des erreurs en Python

from openai import OpenAI, APIStatusError

try:
    response = client.chat.completions.create(...)
except APIStatusError as e:
    if e.status_code == 503:
        print("Instance arrêtée — démarrez-la depuis le dashboard")
    elif e.status_code == 401:
        print("Clé API invalide")
    else:
        print(f"Erreur {e.status_code}: {e.message}")

Limites & quotas

Par plan

Timeouts

Concurrence

Chaque instance dédiée peut traiter plusieurs requêtes en parallèle — Ollama gère la file d'attente en interne. Sur les plans Pro et Enterprise, il n'y a pas de limite de concurrence côté Heberking AI.