Quickstart.

A first /v1/read call, sessions for clips, and the small JSON reading the API returns.

1 · Install #install

Nothing to install: any HTTP client works. The TypeScript SDK comes with v1, then Python.

2 · Authenticate #auth

The API is in an invite-only beta while we finish v1. Invited developers create a test key in the Console and send it as a Bearer token. A Sandbox includes 10 media-minutes and 100,000 text tokens a month, then stops; it never bills.

POST https://feneri.xyz/api/v1/read

3 · Read a sentence or a short clip #read

Text returns synchronously. Media can be sent as base64 in JSON or as a multipart file. Analysis runs as a task: the request waits up to about 45 seconds, then returns the Reading (200) or a session (202) to poll.

curl https://feneri.xyz/api/v1/read \
  -H "Authorization: Bearer $FENERI_API_KEY" \
  -F "file=@clip.wav;type=audio/wav" \
  -F "language=en-US"

Request body

modalities.text string · optional

A sentence or a transcript, in English or Arabic.

modalities.video { data, mime } · optional

Base64 video (mp4 or webm). All media together up to 8 MB and 90 seconds; larger files go through sessions.

modalities.audio { data, mime } · optional

Base64 audio (wav or webm), inside the same limits.

language string · optional

One of en-US, en-GB, ar-AE, ar-SA, ar-EG. Defaults to en-US.

4 · Sessions for clips #sessions

For a clip, create a session, upload the file to the URL it returns, then ask for the reading. Completion returns 202; poll the session until it has a Reading or a safe error. The media is deleted after analysis.

# 1. Create a session; the answer has upload.url and the session id
curl https://feneri.xyz/api/v1/sessions \
  -H "Authorization: Bearer $FENERI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"clip","content_type":"video/mp4"}'

# 2. Upload the file with the headers it gives
curl -X PUT "$UPLOAD_URL" -H "Content-Type: video/mp4" --data-binary @clip.mp4

# 3. Ask for the reading
curl -X POST https://feneri.xyz/api/v1/sessions/$SESSION_ID/complete \
  -H "Authorization: Bearer $FENERI_API_KEY"

5 · The reading #response

The answer is a small JSON: mood, energy, stress, attention and balance, each scored 0 to 100 with a plain label. A field is missing when its signal was not in what you sent. This v1 contract is being finished in the beta.

6 · Errors #errors

Every error has the same shape. Branch on code, not on message. Rate limits include Retry-After and X-RateLimit-* headers.

{
  "error": {
    "type": "rate_limit_error",
    "code": "quota.exceeded",
    "message": "Sandbox media allotment exhausted (10 min / month).",
    "request_id": "req_08536f87de0d4d00"
  }
}

auth.missing · 401
auth.invalid_key · 401
validation.failed · 400
media.in_flight · 409
media.too_large · 413
rate.limit · 429
quota.exceeded · 429