Endpoint#
POST https://evaesi.dev/api/v1/responsesThe older POST /api/v1/chat route remains mounted as a compatibility alias, but /api/v1/responses is the forward contract.
Request body#
| Field | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | Prompt text to dispatch through the inference gateway. |
level | string? | No | The effort level: "look", "focus", "duet", "high" or "hyper". If omitted, the server uses focus. |
max_output_rungs | u64? | No | Optional hard output cap. If omitted, budget reservation falls back to the level's output limit. |
include_regions | bool? | No | Expose region metadata in usage where available. |
studio_id | string? | No | Optional studio context. |
custom_instructions | string? | No | Optional instruction override. |
web_search | bool | No | Favor fresh retrieval where supported. |
code_mode | bool | No | Code and documentation mode. |
image_mode | bool | No | Image or visual mode. |
stream | bool? | No | Enable SSE streaming on the same route. |
Live validation rejects empty prompts and prompts over 100000 bytes. If include_regions is enabled today, the field is reserved in the response but currently reports 0 because the live gateway does not emit region activations yet.
Response#
{
"request_id": "uuid",
"content": "Generated text...",
"sources": [],
"sources_url": "/api/v1/sources/uuid",
"usage": {
"input_rungs": 29,
"output_rungs": 118,
"total_rungs": 147,
"regions_activated": null
},
"level": "focus"
}The live response payload emits sources_url as /api/v1/sources/{request_id}. The nested /api/v1/responses/{request_id}/sources path remains mounted as a compatible alias.
Streaming#
When stream: true, the same endpoint returns server-sent events. Current live event names are:
| Event | Meaning |
|---|---|
response.output_text.delta | Partial output chunk |
response.completed | Final completion payload |
response.error | Stream-level error payload |
At stream start, the response headers include input-rung and rate-limit metadata. Output and total rung counts are only known when generation completes and are delivered in the final completion payload. Each data: line is the JSON-serialized InferenceChunk, including index, content, done, request_id, and model.
event: response.output_text.delta
data: {"index":0,"content":"The ","done":false,"request_id":"req_abc","model":"evaesi-1.0"}
event: response.output_text.delta
data: {"index":1,"content":"answer ","done":false,"request_id":"req_abc","model":"evaesi-1.0"}
event: response.completed
data: {"index":42,"content":"","done":true,"request_id":"req_abc","model":"evaesi-1.0","sources":[]}Examples#
cURL
curl -X POST https://evaesi.dev/api/v1/responses \
-H "Authorization: Bearer esi_dev_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "What is the capital of France?",
"level": "focus",
"web_search": true
}'Python
import requests
response = requests.post(
"https://evaesi.dev/api/v1/responses",
headers={"Authorization": "Bearer esi_dev_YOUR_KEY"},
json={
"prompt": "What is the capital of France?",
"level": "focus",
"web_search": True,
},
)
data = response.json()
print(data["content"])
print(f"Used {data['usage']['input_rungs']} input rungs")JavaScript
const response = await fetch("https://evaesi.dev/api/v1/responses", {
method: "POST",
headers: {
"Authorization": "Bearer esi_dev_YOUR_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
prompt: "What is the capital of France?",
level: "focus",
web_search: true,
}),
});
const data = await response.json();
console.log(data.content);Streaming example#
const response = await fetch("https://evaesi.dev/api/v1/responses", {
method: "POST",
headers: {
"Authorization": "Bearer esi_dev_YOUR_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
prompt: "Explain gravity.",
level: "focus",
stream: true,
}),
});
const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
const text = decoder.decode(value, { stream: true });
for (const line of text.split("\n")) {
if (line.startsWith("data: ")) {
const chunk = JSON.parse(line.slice(6));
if (chunk.done) {
console.log("\nrequest_id:", chunk.request_id);
break;
}
process.stdout.write(chunk.content ?? "");
}
}
}