Criar um plano de aula
Versão da API 2026-10-affable-towhee
Começa a gerar um plano de aula e transmite o seu progresso. started identifica o plano assim que ele existe, para que uma ligação interrompida possa voltar a ligar-se com GET /v1/lesson-plans/{id}/stream. O stream termina com result ou error. Um plano servido a partir da biblioteca chega como um único result.
Âmbitos lesson_plans:write
Parâmetros
Lingara-Versionheaderstringopcional- A versão da API com que responder a este pedido. Sem ela, um token de acesso recebe a versão a que o seu cliente está associado, e um pedido sem token recebe a versão atual. A versão ainda em desenvolvimento só é alcançada indicando-a aqui. Uma versão desconhecida responde
400com o códigoapi_version_unknown.GET /v1/versionslista as versões.
Corpo do pedido application/json
contextstringobrigatóriosource_langstringobrigatóriotarget_langstringobrigatóriolevelintegerobrigatório
Respostas
200 O progresso do plano e, depois, o plano
Eventos do fluxo text/event-stream
Envia um comentário keepalive a cada 15 segundos.
-
startedPlanStarted -
plan_idstringobrigatório
-
phasePlanPhase -
phasestringobrigatórioattemptintegerobrigatório
-
resultPlanResult Encerra o stream -
planLessonPlanobrigatórioidstringobrigatóriostatusPlanStatusobrigatóriotitlestring | nullopcionalsource_langstringobrigatóriotarget_langstringobrigatóriolevelintegerobrigatóriocreated_atstringobrigatóriocompleted_atstring | nullopcionalai_generatedbooleanobrigatóriocontentLessonPlanContent | nullopcionalintroductionstring | nullopcionallearning_objectivesarray of stringobrigatóriovocabularyarray of PlanWordobrigatóriowordstringobrigatóriopronunciationstring | nullopcionaltranslationstringobrigatório
setsarray of PlanSetobrigatórionumberintegerobrigatóriocontextstring | nullopcionalquestionsarray of PlanQuestionobrigatóriotypestringobrigatóriopromptstringobrigatóriooptionsarray of string | nullopcionalanswerstringobrigatórioexplanationstringobrigatóriohintstring | nullopcional
-
errorStreamError Encerra o stream -
Chega dentro da resposta 200. A linha de status já foi enviada, então uma falha depois que o stream é aberto é informada como este evento.
codestringobrigatóriomessagestringobrigatórioplan_idstring | nullopcional
Erros
402application/json- A chamada de um cliente com faturação por utilização foi recusada antes de gastar o que quer que fosse.
spend_cap_reached: o cliente ou a sua conta atingiu o limite de gastos mensal; aumente o limite na página Integrações.metered_billing_inactive: a faturação por utilização não está ativa para esta conta; configure-a ou atualize o método de pagamento na página Integrações. 410application/json- A versão da API com que este pedido é respondido foi descontinuada. Envie uma versão suportada em
Lingara-Version, ou associe o cliente a outra versão. 4XXapplication/json- O pedido foi recusado.
codeindica o motivo eerrordescreve-o por palavras. 503application/json · text/plain- O serviço está temporariamente indisponível; tente novamente após o número de segundos indicado em
Retry-After. Durante a manutenção, o corpo é texto simples em vez do envelope de erro. 5XXapplication/json- O pedido foi recusado.
codeindica o motivo eerrordescreve-o por palavras.
codestringobrigatórioO motivo pelo qual o pedido foi recusado, como um código estável para ramificar a lógica: por exemplo
insufficient_scope(403),rate_limited(429) e, para um cliente com faturação por utilização,spend_cap_reached(402) emetered_billing_inactive(402).errorstringobrigatório
Exemplo
Prefere uma biblioteca? Veja a secção Bibliotecas.
Exemplo de fluxo
event: started
data: {"plan_id":"3f1c2a9e-5b7d-4e21-9a0c-6d8e4f2b1a37"}
event: phase
data: {"phase":"selecting_vocabulary","attempt":1}
event: result
data: {"plan":{"id":"3f1c2a9e-5b7d-4e21-9a0c-6d8e4f2b1a37","status":"complete","title":"At the night market","source_lang":"en","target_lang":"zh","level":2,"created_at":"2026-09-23T10:00:00Z","completed_at":"2026-09-23T10:00:41Z","ai_generated":true,"content":{"introduction":"Order food and ask prices at a night market.","learning_objectives":["Ask how much something costs"],"vocabulary":[{"word":"多少钱","pronunciation":"duōshao qián","translation":"how much"}],"sets":[{"number":1,"questions":[{"type":"multiple_choice_word","prompt":"Which word asks for a price?","options":["多少钱","谢谢"],"answer":"多少钱","explanation":"多少钱 means how much money."}]}]}}}Se uma tradução e a referência em inglês divergirem, prevalece a referência em inglês.