ForHosting KIT · PDF e documentos

Estrutura de capítulos EPUB a partir de marcadores de PDF

Um EPUB útil precisa de uma ordem de leitura clara, mas um PDF frequentemente expressa essa ordem apenas pelo sumário de marcadores.

● BetaGrátis · no seu navegador

Executar grátis Ver a API

Use pelo WebAPIE-mailTelegramApp em breve

Esta capacidade recebe uma lista extraída de marcadores PDF e converte cada marcador de primeiro nível em uma entrada de capítulo EPUB. Ela preserva a ordem e os títulos, atribui nomes XHTML estáveis e mantém as páginas de destino quando disponíveis. Marcadores aninhados continuam sendo informações de seção e não viram capítulos independentes por engano. Se a origem não tiver marcadores de primeiro nível, a solicitação falhará claramente, sem inventar uma estrutura que o documento não forneceu.

Prepare o sumário de marcadores

Comece com o sumário de marcadores fornecido por um analisador ou uma ferramenta de inspeção de PDF, não com títulos visualmente destacados copiados do conteúdo das páginas. Envie os registros na ordem de leitura original. Cada registro precisa de um título e de um nível numérico, em que o nível 1 indica um marcador superior; uma página de destino numerada a partir de 1 é opcional. Um registro de nível 2 ou mais profundo pode descrever uma subseção, um apêndice, uma figura ou outro destino aninhado. Esses registros são validados porque dados malformados não devem passar silenciosamente, mas não são promovidos a capítulos EPUB. Os espaços nas extremidades dos títulos são removidos, preservando grafia, pontuação, capitalização e espaços internos. Os valores de página devem ser inteiros positivos quando informados. Essa representação explícita evita suposições baseadas em recuo ou tipografia e torna o resultado reproduzível entre sistemas. Também permite separar a extração do PDF do planejamento editorial em um fluxo automatizado.

Entenda a lista de capítulos gerada

A saída contém a quantidade de capítulos e uma lista ordenada. Cada capítulo recebe um índice iniciado em 1, o título normalizado do marcador superior correspondente e um nome estável como chapter-001.xhtml. Os nomes dependem da posição, não do título; assim, pontuação, títulos repetidos, textos não latinos ou futuras regras de slug não criam colisões. Quando um marcador de primeiro nível inclui uma página de destino, o capítulo também inclui source_page; quando nenhuma página foi fornecida, esse campo opcional é omitido em vez de receber null. A capacidade não extrai texto, divide o PDF, escreve XHTML nem monta um documento de navegação EPUB. Sua finalidade é estabelecer uma estrutura intermediária limpa para que etapas posteriores nomeiem arquivos, associem conteúdo extraído, criem itens da lombada e construam links de navegação. Como marcadores aninhados nunca viram capítulos, a contagem sempre corresponde ao número de registros de nível 1.

Trate sumários ausentes ou imperfeitos

Um PDF pode exibir páginas perfeitamente e ainda não conter marcadores utilizáveis. Nesse caso, não existe um sinal confiável de capítulos superiores, então a capacidade devolve um erro de entrada inválida em vez de inferir capítulos por números de página, tamanhos de fonte ou padrões de texto. Isso é essencial na conversão automatizada: uma lista inventada pode parecer plausível, mas associar conteúdo ao título errado ou achatar uma hierarquia intencional. Se o sumário existir, mas todos os marcadores estiverem abaixo do nível 1, o mesmo erro será devolvido, pois nenhum limite de capítulo superior pode ser determinado. Corrija a extração anterior ou acrescente um sumário deliberado antes de tentar novamente. Outros registros malformados falham com mensagens específicas de localização, incluindo títulos vazios, níveis inválidos e páginas não positivas. A implementação percorre no máximo 10,000 registros uma vez, não usa rede e não depende do horário. Entradas idênticas produzem índices e nomes idênticos por US$ 0,002 por solicitação.

Casos de uso

Planejar uma conversão para EPUB

Transforme um sumário PDF extraído no manifesto de capítulos que um fluxo poderá preencher com conteúdo XHTML.

Auditar a navegação do documento

Compare a quantidade e a ordem dos capítulos EPUB pretendidos com os marcadores superiores do PDF antes da publicação.

Criar nomes de capítulo estáveis

Atribua nomes XHTML posicionais sem colisões, mesmo com títulos repetidos, pontuação ou caracteres não latinos.

Perguntas frequentes

Quanto custa?

O preço da API é US$ 0,002 por solicitação, e a mesma transformação determinística pode ser executada no navegador.

Esta capacidade lê o próprio arquivo PDF?

Não. Ela recebe o sumário de marcadores já extraído de um PDF e o converte em uma lista de capítulos.

O que conta como capítulo?

Cada marcador cujo nível seja exatamente 1 vira um capítulo, na mesma ordem da entrada.

O que acontece com marcadores aninhados?

Eles são validados, mas não são emitidos como capítulos. Depois, podem ser tratados como seções do capítulo superior.

E se o PDF não tiver marcadores de primeiro nível?

A solicitação devolve um erro de entrada inválida porque a capacidade não inventa limites de capítulos.

As páginas de destino são obrigatórias?

Não. Quando uma página existe, ela vira source_page; caso contrário, esse campo opcional é omitido.

Para desenvolvedores — acesso via API

Tudo nesta página está disponível via API. Esta seção é para equipes que querem integrar a ferramenta aos próprios sistemas; quem não precisa disso pode simplesmente usar a ferramenta acima.

Endpoint

POSThttps://api.kit.forhosting.com/pdf/to-epub-structure

Autenticação por token Bearer. Um único POST coloca a tarefa na fila; o resultado chega por webhook ou link assinado.

Chame do seu código

curl -X POST https://api.kit.forhosting.com/pdf/to-epub-structure \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"outline":[{"title":"Introduction","level":1,"page":1},{"title":"Background","level":2,"page":3},{"title":"Methods","level":1,"page":12}]}'

const res = await fetch("https://api.kit.forhosting.com/pdf/to-epub-structure", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "outline": [
      {
        "title": "Introduction",
        "level": 1,
        "page": 1
      },
      {
        "title": "Background",
        "level": 2,
        "page": 3
      },
      {
        "title": "Methods",
        "level": 1,
        "page": 12
      }
    ]
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/pdf/to-epub-structure",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "outline": [
        {
            "title": "Introduction",
            "level": 1,
            "page": 1
        },
        {
            "title": "Background",
            "level": 2,
            "page": 3
        },
        {
            "title": "Methods",
            "level": 1,
            "page": 12
        }
    ]
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/pdf/to-epub-structure", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"outline":[{"title":"Introduction","level":1,"page":1},{"title":"Background","level":2,"page":3},{"title":"Methods","level":1,"page":12}]}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"outline":[{"title":"Introduction","level":1,"page":1},{"title":"Background","level":2,"page":3},{"title":"Methods","level":1,"page":12}]}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/pdf/to-epub-structure", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

Exemplo de requisição

{
  "outline": [
    {
      "title": "Introduction",
      "level": 1,
      "page": 1
    },
    {
      "title": "Background",
      "level": 2,
      "page": 3
    },
    {
      "title": "Methods",
      "level": 1,
      "page": 12
    }
  ]
}

Exemplo de resposta

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "pdf.to_epub_structure",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

A API é assíncrona: cada chamada devolve um task_id na hora. Se preferir polling, consulte o status a até 1 requisição por segundo.

Preço

por chamadaUS$ 0,002

Preço publicado, sem tokens nem créditos escondidos. Tarefa que falha não é cobrada.

Limites

`max_mb`	25
`max_pages`	200

Erros

HTTP	Código	O que significa
`401`	`unauthorized`	Token ausente ou inválido. Confira o header Authorization.
`402`	`insufficient_balance`	Saldo insuficiente para esta tarefa. Faça uma recarga e tente de novo.
`404`	`unknown_type`	Esse tipo de tarefa não existe. Confira o campo type no catálogo.
`429`	`rate_limited`	Muitas requisições em pouco tempo. Espere um instante e tente de novo.

Ver a documentação completa do KIT →