Platform

Developers

API Documentation

Call Human AI from your own apps and scripts. Get a key on the API Keys page.

Authentication

Send your key on every request as the x-api-key header. Keys act as you and follow your plan limits. Never put a key in client-side code or a public repo.

Key scopes

When you create a key you pick what it may call: Chat only (text model Speed), Images only (image model humi.1 images), or Chat + Images (both). API keys only work with these two models — any other modelId is rejected with 403. Calling outside your key's scope also returns 403.

Base URL

production

https://usehuman.de

List models

GET /api/models

curl https://usehuman.de/api/models

Returns enabled models: id, display name, vision support and minimum plan. No auth required.

Chat completions (streaming)

POST /api/chat

curl https://usehuman.de/api/chat \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "humi1.1-speed",
    "messages": [
      { "role": "user", "content": "Hello" }
    ]
  }'

The response is a Server-Sent Events stream. Each event is data: {token}; the stream ends with data: [DONE]. Errors arrive as data: {error} or a JSON body with an error field.

JavaScript (fetch)

stream tokens in the browser (key must stay server-side!)

const res = await fetch("https://usehuman.de/api/chat", {
  method: "POST",
  headers: { "x-api-key": process.env.HUMANAI_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ modelId: "humi1.1-speed", messages: [{ role: "user", content: "Hello" }] }),
});
const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "", full = "";
for (;;) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split("\n");
  buffer = lines.pop();
  for (const line of lines) {
    const t = line.trim();
    if (!t.startsWith("data:")) continue;
    const data = t.slice(5).trim();
    if (data === "[DONE]") continue;
    const json = JSON.parse(data);
    if (json.error) throw new Error(json.error);
    if (json.token) full += json.token;
  }
}

Python (requests)

stream tokens with requests

import json, requests

resp = requests.post(
    "https://usehuman.de/api/chat",
    headers={"x-api-key": "YOUR_KEY", "Content-Type": "application/json"},
    json={"modelId": "humi1.1-speed", "messages": [{"role": "user", "content": "Hello"}]},
    stream=True,
)
full = ""
for line in resp.iter_lines():
    line = line.decode().strip()
    if not line.startswith("data:"):
        continue
    data = line[5:].strip()
    if data == "[DONE]":
        continue
    chunk = json.loads(data)
    if chunk.get("error"):
        raise RuntimeError(chunk["error"])
    full += chunk.get("token", "")
print(full)

Images

Attach images by adding an images array with {url} entries (data-URI or https) to a message. Only vision-capable models accept them — check the model list first.

message with image

{ "role": "user", "content": "What is this?", "images": [{ "url": "https://…" }] }

Generate an image (humi.1 images)

Text-to-image needs a key with the Images scope. The prompt is the last user message; the answer streams back as Markdown with the image. The reply ends with *Generated with humi.1 images*.

POST /api/chat (image)

curl https://usehuman.de/api/chat \
  -H "x-api-key: YOUR_IMAGES_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "humi.1-images",
    "messages": [
      { "role": "user", "content": "A red apple on a wooden table, morning light" }
    ]
  }'

Errors

401 invalid key · 403 model needs a higher plan · 400 bad request · 429 rate-limited, retry with backoff · 5xx provider issue, retry shortly.

Rate limits & plans

Usage counts against your account. Model availability follows your subscription — the allowed flag on GET /api/models (when logged in) tells you what you may use. Revoke a key any time on the API Keys page; apps using it stop immediately.