Felo APIs

PPT Task API

Crie tarefas de geração de PPT, liste temas e consulte endpoints de tarefas compartilhadas.

POST/v2/ppts

Autenticação

Bearer API key

Tipo de conteúdo

application/json

Notas de limite

Podem se aplicar limites específicos do endpoint.

LiveDoc API Landing Page Task API

A PPT Task API oferece recursos assíncronos de geração de PPT. Você pode criar uma tarefa e depois consultar o status por task_id. Também pode navegar pelos temas de PPT disponíveis e aplicá-los ao criar tarefas.

Esta é uma API assíncrona. Para o padrão compartilhado de envio, consulta e recuperação, consulte Tarefas assíncronas.

Autenticação

Todas as requisições exigem uma chave de API no cabeçalho Authorization:

Authorization: Bearer YOUR_API_KEY

Uso com agentes de IA

Para criar slides a partir de um agente, instale o pacote completo felo-ai em vez de um subconjunto fixo de Skills. O instalador descobre dinamicamente todos os diretórios de pacote que contêm SKILL.md, incluindo o Skill de PPT e adições futuras. Instale todos os Skills descobertos no diretório nativo do seu agente: ~/.codex/skills para o Codex, ~/.claude/skills para o Claude Code, ~/.agents/skills para o OpenClaw ou ~/.hermes/skills para o Hermes Agent. Siga o guia de configuração manual de agentes de IA para ver a configuração da chave de API e a verificação de cada plataforma.

1. Listar temas de PPT

Consulte os temas de PPT disponíveis com paginação, busca por palavra-chave e filtros de idioma e tipo.

Endpoint

GET https://openapi.felo.ai/v2/ppt-themes

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`lang`	string	Não	Código de idioma para conteúdo localizado (por exemplo, `en`, `zh-Hans`). Padrão: `en`
`type`	string	Não	Filtra por tipo de tema (por exemplo, `default`, `custom`)
`keyword`	string	Não	Palavra-chave de busca, corresponde aos títulos dos temas
`page`	integer	Não	Número da página, começando em 1. Padrão: `1`
`size`	integer	Não	Tamanho da página, máximo de 100. Padrão: `20`

Exemplo

curl -X GET 'https://openapi.felo.ai/v2/ppt-themes?lang=en&page=1&size=10' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Resposta de sucesso (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 8,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": "43122897-0d3c-4c9e-ae19-20527ad36c04",
        "title": "Inspiration Themes",
        "subtitle": "AI-tailored visual solutions",
        "description": "Style and layout, both crafted by AI from your content in real time"
      }
    ]
  }
}

Campos da resposta de temas

Campo	Tipo	Descrição
`total`	integer	Número total de temas que correspondem ao filtro
`page`	integer	Número da página atual
`size`	integer	Tamanho da página
`items`	array	Lista de objetos de tema
`items[].id`	string	ID do tema; use-o como `ai_theme_id` ao criar o PPT
`items[].title`	string	Título do tema (localizado)
`items[].subtitle`	string	Subtítulo do tema (localizado)
`items[].description`	string	Descrição do tema (localizada)

2. Criar uma tarefa de PPT

Endpoint

POST https://openapi.felo.ai/v2/ppts

Cabeçalhos da requisição

Cabeçalho	Obrigatório	Descrição
`Authorization`	Sim	Sua chave de API no formato `Bearer YOUR_API_KEY`
`Content-Type`	Sim	`application/json` ou `multipart/form-data`

Corpo da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`query`	string	Sim	Prompt de geração do PPT
`livedoc_short_id`	string	Não	Short ID de um LiveDoc existente a ser associado à sessão de PPT. Se omitido, um novo LiveDoc é criado automaticamente.
`resource_ids`	array de strings	Não	Lista de IDs de recursos do LiveDoc a serem usados como contexto para a geração do PPT
`ppt_config`	object	Não	Opções de configuração do PPT
`ppt_config.ai_theme_id`	string	Não	ID do tema do endpoint Listar temas de PPT

Exemplo

curl -X POST 'https://openapi.felo.ai/v2/ppts' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Felo, 2 pages",
    "ppt_config": {
      "ai_theme_id": "02968979-a69f-42c4-b136-de02c40ab2d7"
    }
  }'

Criar a partir de um arquivo enviado

Use multipart/form-data para enviar um arquivo e criar uma tarefa de PPT em uma única requisição. A plataforma envia o arquivo primeiro como recurso do LiveDoc e depois passa seu ID de recurso para a tarefa de PPT.

Parte	Tipo	Obrigatório	Descrição
`query`	string	Sim	Prompt de geração do PPT
`file`	file	Sim	Arquivo de origem usado como contexto do PPT
`stream_protocol`	string	Não	Protocolo de streaming; o padrão é `message_center_v1`
`livedoc_short_id`	string	Não	LiveDoc existente que deve receber o arquivo. Um novo LiveDoc é criado quando omitido.
`ppt_config`	JSON	Não	Configuração do PPT com a mesma estrutura do corpo JSON da requisição. Envie esta parte como `application/json`.

curl -X POST 'https://openapi.felo.ai/v2/ppts' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'query=Create a 10-page presentation based on this report' \
  -F 'ppt_config={"ai_theme_id":"02968979-a69f-42c4-b136-de02c40ab2d7"};type=application/json' \
  -F '[email protected]'

A resposta usa o mesmo esquema da requisição JSON. O livedoc_short_id retornado identifica o LiveDoc que contém o recurso enviado.

Resposta de sucesso (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "livedoc_short_id": "PvyKouzJirXjFdst4uKRK3",
    "ppt_business_id": "BfLPuQKmChk9SPmyQawxgr",
    "task_id": "019cad6d-e874-55ef-d577-686344b5a7e9"
  }
}

3. Consultar o status da tarefa

Endpoint

GET https://openapi.felo.ai/v2/tasks/{task_id}/status

Exemplo

curl -X GET 'https://openapi.felo.ai/v2/tasks/019cad6d-e874-55ef-d577-686344b5a7e9/status' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Resposta de sucesso (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "status": "RUNNING"
  }
}

4. Consultar o histórico da tarefa

Endpoint

GET https://openapi.felo.ai/v2/tasks/{task_id}/historical

Exemplo

curl -X GET 'https://openapi.felo.ai/v2/tasks/019cb17e-9e23-3d40-4447-48a651249460/historical' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Resposta RUNNING

{
  "status": "ok",
  "message": null,
  "data": {
    "task_id": "019cb17e-9e23-3d40-4447-48a651249460",
    "task_status": "RUNNING",
    "ppt_biz_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "ppt_url": "https://felo.ai/slides/oM8A9iJHg8dT4ZKgHThQTx"
  }
}

Resposta COMPLETED

{
  "status": "ok",
  "message": null,
  "data": {
    "task_id": "019cb17e-9e23-3d40-4447-48a651249460",
    "task_status": "COMPLETED",
    "ppt_biz_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "ppt_url": "https://felo.ai/slides/oM8A9iJHg8dT4ZKgHThQTx",
    "live_doc_short_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "live_doc_url": "https://felo.ai/livedoc/oM8A9iJHg8dT4ZKgHThQTx"
  }
}

Resposta COMPLETED (AI_PAGE)

{
  "status": "ok",
  "message": null,
  "data": {
    "task_id": "019d7a4d-6ab5-a96d-0f98-43ca434ab621",
    "task_status": "COMPLETED",
    "ppt_biz_id": "9qiLTmT77fA3aVurrMHvRJ",
    "ppt_url": "https://felo.ai/slides/9qiLTmT77fA3aVurrMHvRJ",
    "ai_page_html": "https://felo.ai/ai-page/9qiLTmT77fA3aVurrMHvRJ"
  }
}

Resposta FAILED / PENDING / EXPIRED / CANCELED

{
  "status": "ok",
  "message": null,
  "data": {
    "task_id": "019cb17e-9e23-3d40-4447-48a651249460",
    "task_status": "FAILED",
    "ppt_biz_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "ppt_url": "https://felo.ai/slides/oM8A9iJHg8dT4ZKgHThQTx",
    "error_message": "PPT generation failed",
    "live_doc_short_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "live_doc_url": "https://felo.ai/livedoc/oM8A9iJHg8dT4ZKgHThQTx"
  }
}

Campos da resposta histórica

Campo	Tipo	Descrição
`task_id`	string	ID da tarefa
`task_status`	string	Status atual da tarefa
`ppt_biz_id`	string	ID de negócio do PPT (mapeado do `thread_short_id` do backend)
`ppt_url`	string	URL do PPT, formato: `https://felo.ai/slides/{ppt_biz_id}`
`error_message`	string	Presente em `FAILED` / `PENDING` / `EXPIRED` / `CANCELED`; string vazia `""` quando o downstream não fornece detalhes do erro
`ai_page_html`	string	Presente quando a tarefa roda no modo AI_PAGE e o histórico downstream retorna uma URL de resultado HTML
`live_doc_short_id`	string	Short ID do LiveDoc. Em `COMPLETED`, vem do `live_doc_short_id` do downstream; nos status de falha terminal, é retornado quando disponível
`live_doc_url`	string	URL do LiveDoc correspondente a `live_doc_short_id`

Exportar PPTX

Depois que a tarefa de geração de PPT chega a COMPLETED, envie uma exportação assíncrona usando o ppt_business_id da resposta de criação (ou o ppt_biz_id da resposta histórica):

curl -X POST 'https://openapi.felo.ai/v2/ppts/YOUR_PPT_BUSINESS_ID/export' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

Consulte GET https://openapi.felo.ai/v2/ppts/{ppt_business_id}/export com a mesma chave de API Bearer a cada 2–5 segundos. O proprietário da chave de API deve ser o dono do PPT. Os dois endpoints retornam data.status: NOT_STARTED, PROCESSING, COMPLETED ou FAILED. Apenas COMPLETED inclui download_url e expires_at.

A URL assinada de download expira 30 minutos após a emissão. Chame o endpoint GET novamente para obter uma URL nova; isso não regenera o PPTX. O POST usa application/json e aceita {}. Repetir o POST enquanto uma exportação está em processamento não inicia outro trabalho; chamá-lo após a conclusão regenera o PPTX e gera a cobrança de créditos de exportação de PPT existente. Créditos insuficientes retornam HTTP 402. Limites de requisições específicos do endpoint podem se aplicar; tente novamente mais tarde em caso de HTTP 429. Uma exportação com falha pode ser enviada de novo.

{
  "status": "ok",
  "message": null,
  "data": {
    "status": "COMPLETED",
    "download_url": "https://example.com/presentation.pptx?signature=...",
    "expires_at": "2026-09-29T10:30:00Z"
  }
}

Recomendação de consulta

Use o task_id da resposta de criação e consulte o status a cada 2–5 segundos até que o status se torne um estado terminal.

Exemplos de status comuns:

RUNNING: a tarefa ainda está em processamento
COMPLETED: a tarefa foi concluída com sucesso
FAILED / PENDING / EXPIRED / CANCELED: a tarefa chegou a um status terminal com error_message; live_doc_url também é retornado quando disponível

Valores de status desconhecidos podem aparecer conforme o backend evolui; trate-os como não terminais, a menos que a documentação diga o contrário.

Códigos de erro

Código	Status HTTP	Descrição
`UNAUTHORIZED`	401	A chave de API é inválida ou foi revogada
`PPT_TASK_CREATE_FAILED`	502	Falha na chamada downstream de criação da tarefa
`PPT_TASK_QUERY_FAILED`	502	Falha na chamada downstream de consulta do status da tarefa