Struttura dei capitoli EPUB dai segnalibri PDF
Un EPUB valido richiede un ordine di lettura chiaro, ma spesso un PDF lo esprime soltanto tramite la struttura dei segnalibri.
Esegui gratis nel browser
Questa capacità riceve l’elenco estratto e converte ogni segnalibro di primo livello in una voce di capitolo EPUB. Conserva ordine e titoli, assegna nomi XHTML stabili e riporta le pagine di destinazione disponibili. I segnalibri annidati restano informazioni di sezione e non diventano capitoli autonomi. Se la sorgente non contiene segnalibri di primo livello, la richiesta non riesce e segnala il problema, senza inventare una struttura assente dal documento.
Prepari la struttura dei segnalibri
Parta dalla struttura prodotta da un analizzatore o da uno strumento di ispezione PDF, non da intestazioni visivamente evidenti copiate dalle pagine. Fornisca i record nell’ordine di lettura originale. Ognuno richiede un titolo e un livello numerico, dove 1 indica il livello principale; la pagina di destinazione, numerata da 1, è facoltativa. I record di livello 2 o superiore possono descrivere sottosezioni, appendici, figure o altre destinazioni annidate. Vengono convalidati, perché dati malformati non devono passare inosservati, ma non sono promossi a capitoli EPUB. Gli spazi esterni ai titoli vengono eliminati, mentre ortografia, punteggiatura, maiuscole e spazi interni restano invariati. Le pagine devono essere interi positivi. Questa rappresentazione esplicita evita ipotesi basate su rientri o tipografia, rende il risultato ripetibile e separa l’estrazione del PDF dalla pianificazione editoriale.
Interpreti l’elenco dei capitoli
L’output contiene il conteggio e un array ordinato di capitoli. Ogni capitolo riceve un indice a partire da 1, il titolo normalizzato del relativo segnalibro principale e un nome stabile come chapter-001.xhtml. Il nome dipende dalla posizione, non dal titolo, quindi punteggiatura, duplicati, testi non latini o future regole per gli slug non generano collisioni. Se è presente una pagina di destinazione, il capitolo include source_page; altrimenti il campo facoltativo viene omesso e non impostato su null. La capacità non estrae testo, non divide il PDF, non scrive XHTML e non crea il documento di navigazione EPUB. Produce invece una struttura intermedia che i passaggi successivi possono usare per denominare file, associare contenuti, creare voci dello spine e collegamenti di navigazione. Il totale corrisponde sempre ai record di livello 1.
Gestisca strutture mancanti o imperfette
Un PDF può visualizzare correttamente le pagine pur non contenendo segnalibri utilizzabili. Senza un segnale affidabile per i capitoli principali, la capacità restituisce un errore di input non valido invece di dedurre confini da numeri di pagina, dimensioni dei caratteri o schemi testuali. Una lista inventata potrebbe sembrare plausibile, ma associare contenuti al titolo sbagliato o appiattire una gerarchia intenzionale. Lo stesso errore compare se tutti i segnalibri sono sotto il livello 1. In tal caso corregga l’estrazione a monte o aggiunga una struttura deliberata prima di riprovare. Gli altri record malformati producono messaggi specifici per posizione, titolo vuoto, livello non valido o pagina non positiva. L’algoritmo esegue un solo passaggio su un massimo di 10,000 record, senza rete né dipendenze temporali. Lo stesso input genera sempre gli stessi indici e nomi a $0.002 per richiesta.
Casi d'uso
Pianificare una conversione EPUB
Trasformi una struttura PDF estratta nel manifesto che una pipeline potrà riempire con contenuti XHTML.
Verificare la navigazione
Confronti numero e ordine dei capitoli previsti con i segnalibri principali del PDF prima della pubblicazione.
Creare nomi di capitolo stabili
Assegni nomi XHTML posizionali senza collisioni anche con titoli ripetuti, punteggiati o non latini.
Domande frequenti
Quanto costa?
Il prezzo dell’API è $0.002 per richiesta; la stessa trasformazione deterministica può essere eseguita nel browser.
Questa capacità legge direttamente il PDF?
No. Riceve la struttura dei segnalibri già estratta e la converte in un elenco di capitoli.
Che cosa conta come capitolo?
Ogni segnalibro con livello esattamente pari a 1 diventa un capitolo, rispettando l’ordine di input.
Che cosa accade ai segnalibri annidati?
Vengono convalidati ma non emessi come capitoli; potranno diventare sezioni del capitolo principale.
Che cosa accade se mancano segnalibri principali?
La richiesta restituisce un errore di input non valido, perché la capacità non inventa i confini.
Le pagine di destinazione sono obbligatorie?
No. Una pagina presente diventa source_page; in caso contrario, il campo facoltativo viene omesso.
Per sviluppatori — accesso via API
Tutto quello che vedi in questa pagina è disponibile anche via API. Questa sezione è per i team che vogliono integrarlo nei propri sistemi; chi non ne ha bisogno può semplicemente usare lo strumento qui sopra.
Endpoint
Autenticazione con Bearer token: un POST mette in coda l'attività e il risultato arriva via webhook o link firmato.
Chiamala dal tuo stack
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)Esempio di richiesta
{
"outline": [
{
"title": "Introduction",
"level": 1,
"page": 1
},
{
"title": "Background",
"level": 2,
"page": 3
},
{
"title": "Methods",
"level": 1,
"page": 12
}
]
}Esempio di risposta
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "pdf.to_epub_structure",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}L'API è asincrona: ricevi subito un task_id e puoi fare polling fino a 1 richiesta al secondo.
Prezzi
Prezzo pubblicato, senza token né crediti. Se l'attività fallisce, non paghi.
Limiti
max_mb | 25 |
max_pages | 200 |
Errori
| HTTP | Codice | Significato |
|---|---|---|
401 | unauthorized | Chiave API mancante o non valida: controlla l'header Authorization. |
402 | insufficient_balance | Credito esaurito: ricarica per continuare a eseguire attività. |
404 | unknown_type | Tipo di attività sconosciuto: controlla il campo type della richiesta. |
429 | rate_limited | Troppe richieste in poco tempo: rallenta e riprova tra qualche secondo. |