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.