이벤트 보내기

매개변수

Lingara-Versionheaderstring선택

이 요청에 응답할 API 버전입니다. 지정하지 않으면 액세스 토큰은 해당 클라이언트에 고정된 버전을, 토큰이 없는 요청은 현재 버전을 받습니다. 개발 중인 버전은 여기에서 지정해야만 사용할 수 있습니다. 알 수 없는 버전에는 코드 api_version_unknown과 함께 400으로 응답합니다. GET /v1/versions에서 버전 목록을 확인할 수 있습니다.

Idempotency-Keyheaderstring필수

이벤트마다 정하고 재시도할 때 그대로 다시 보내는 값입니다. UUID처럼 보이는 ASCII 문자 1~255자로 지정합니다. 같은 키로 재시도하면 첫 응답을 돌려받고 본문이 달라도 다시 과금되지 않습니다. 유효한 키가 없으면 요청은 코드 idempotency_key_required와 함께 400으로 응답합니다.

요청 본문 application/json

typestring필수

dataWorldPracticeRequested필수

topicstring필수

source_langstring필수

target_langstring필수

levelinteger필수

tagsarray of string선택

generateboolean | null선택

응답

202 이벤트가 기록되었습니다

idstring필수

typestring필수

created_atstring필수

reactionReactionReport | null선택

statusReactionStatus필수

plan_idstring | null선택

plan_statusPlanStatus | null선택

이벤트가 수락된 시점의 플랜 상태입니다. lesson_plan.ready 또는 lesson_plan.failed가 온다고 약속하는 값은 generating뿐입니다. 다른 값은 라이브러리에서 제공된 플랜이며, 지금 바로 GET /v1/lesson-plans/{id}로 읽을 수 있습니다.

codestring | null선택

errorstring | null선택

오류

402application/json

사용량 기반 과금 클라이언트의 호출이 아무것도 소모하기 전에 거부되었습니다. spend_cap_reached: 클라이언트 또는 그 계정이 월 지출 한도에 도달했습니다. 연동 페이지에서 한도를 올리세요. metered_billing_inactive: 이 계정에서 사용량 기반 과금이 활성화되어 있지 않습니다. 연동 페이지에서 설정하거나 결제 수단을 업데이트하세요.

410application/json

이 요청에 응답하는 API 버전은 지원이 종료되었습니다. Lingara-Version에 지원되는 버전을 보내거나 클라이언트를 다른 버전에 다시 고정하세요.

4XXapplication/json

요청이 거부되었습니다. code는 이유를, error는 이를 문장으로 알려 줍니다.

503application/json · text/plain

서비스를 일시적으로 사용할 수 없습니다. Retry-After에 있는 초만큼 기다린 후 다시 시도하세요. 점검 중에는 본문이 오류 엔벨로프가 아닌 일반 텍스트입니다.

5XXapplication/json

요청이 거부되었습니다. code는 이유를, error는 이를 문장으로 알려 줍니다.

codestring필수

요청이 거부된 이유를 분기에 쓸 수 있는 안정적인 코드로 나타냅니다. 예: insufficient_scope(403), rate_limited(429), 사용량 기반 과금 클라이언트의 경우 spend_cap_reached(402)와 metered_billing_inactive(402).

errorstring필수

예시

curl -X POST "https://api.getlingara.com/v1/events" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"world.context_changed","data":{"scene":"A night market in Taipei, just after rain","npc":{"name":"Auntie Lin","persona":"a street-food vendor who likes to haggle"},"source_lang":"en","target_lang":"zh","level":3,"tags":["market","food","chapter-2"],"generate":true}}'

라이브러리가 더 편하신가요? 라이브러리 섹션을 보세요.