Send a line to an NPC

Parameters

Lingara-Versionheaderstringoptional

The API version to answer this request under. Without it, an access token gets the version its client is pinned to, and a request with no token gets the current version. The version still in development is reached only by naming it here. An unknown version answers 400 with code api_version_unknown. GET /v1/versions lists the versions.

Request body application/json

npcNpcrequired

namestringrequired

personastring | nulloptional

scenestring | nulloptional

source_langstringrequired

target_langstringrequired

levelintegerrequired

linestringrequired

historyarray of DialogueEntryoptional

The conversation so far, oldest first, at most 12 lines. You keep the window: Lingara stores nothing between turns. Send each NPC reply back cut to its first 500 characters.

speakerSpeakerrequired

textstringrequired

Responses

200 The character's reply, piece by piece

Stream events text/event-stream

Sends no keepalive comments.

delta TurnDelta

textstringrequired

notice Notice

codestringrequired

messagestringrequired

done Done Ends the stream

error StreamError Ends the stream

Arrives inside the 200 response. The status line has already been sent, so a failure after the stream opens is reported as this event.

codestringrequired

messagestringrequired

plan_idstring | nulloptional

Errors

402application/json

A metered client's call was refused before it spent anything. spend_cap_reached: the client or its account has reached its monthly spending limit; raise the limit on the Integrations page. metered_billing_inactive: usage billing is not active for this account; set it up, or update the payment method, on the Integrations page.

410application/json

The API version this request is answered under has been discontinued. Send a supported version in Lingara-Version, or re-pin the client.

4XXapplication/json

The request was refused. code says why, and error says it in words.

503application/json · text/plain

The service is temporarily unavailable; retry after the number of seconds in Retry-After. During maintenance the body is plain text rather than the error envelope.

5XXapplication/json

The request was refused. code says why, and error says it in words.

codestringrequired

Why the request was refused, as a stable code to branch on: for example insufficient_scope (403), rate_limited (429) and, for a metered client, spend_cap_reached (402) and metered_billing_inactive (402).

errorstringrequired

Example

curl -N -X POST "https://api.getlingara.com/v1/embed/dialogue/turns" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"npc":{"name":"Auntie Lin","persona":"a street-food vendor who likes to haggle"},"scene":"A night market in Taipei, just after rain","source_lang":"en","target_lang":"zh","level":3,"line":"How much are the dumplings?","history":[{"speaker":"npc","text":"来来来，刚出锅的饺子！"},{"speaker":"player","text":"你好！"}]}'

Prefer a library? See the Libraries section.

Example stream

event: delta
data: {"text":"饺子十块钱一盘，"}

event: delta
data: {"text":"要几盘？"}

event: done
data: {}