Heyzine API
Application programming interface for developers or NoCode tools to integrate flipbooks in applications or workflows.
Començant
Heyzine ofereix una API completa i flexible per gestionar els flipbooks del teu compte. Et permet crear, llistar i suprimir flipbooks, gestionar la llista d’accés amb contrasenya, obtenir codis d’incrustació i rebre leads mitjançant webhooks. L’API utilitza un Client ID o una clau API per a l’autenticació. Quan calgui la clau API, l’has de proporcionar en una capçalera d’aquesta manera:
Authorization: Bearer API_KEY
Accés o registre per veure aquí el teu identificador de client i la clau API.
Conversió de PDF a flipbook
Conversió mitjançant enllaç
Create a link with parameters pointing to your pdf file and use it in anchors, iframes, dialogs, or anywhere else. The link will redirect to the final flipbook url. The conversion process starts with the first access, so it can take some time to load the first time you open it. Per fer la conversió al servidor i evitar revelar l’URL original, pots utilitzar l’endpoint /rest i obtenir una resposta JSON.
Format de l’enllaç
https://heyzine.com/api1?pdf={pdf url}&k={client id}
Exemple bàsic
https://heyzine.com/api1?pdf=https://codingfocus.com/sample.pdf&k=d3m0
Títols i controls
https://heyzine.com/api1?pdf=https%3A%2F%2Fcodingfocus.com%2Fsample.pdf%3Fexample2&t=Test%20title&s=Test%20subtitle&d=1&k=d3m0
Copia el disseny d’una plantilla
https://heyzine.com/api1?pdf=https%3A%2F%2Fcodingfocus.com%2Fsample.pdf%3Fexample3&k=d3m0&tpl=02d4d12c08593f3d10a5f61338758eaa0bf67abd.pdf
Conversió amb l’API REST
Crida l’endpoint Sync REST des del client o el servidor per convertir el PDF i obtenir una resposta JSON amb els enllaços al flipbook, la miniatura i el PDF. The endpoint will send the response right after the conversion ends. You have to make sure the client has a long enough time out for the largest documents.
Crida l’endpoint Async REST per obtenir immediatament la resposta JSON si no vols esperar que acabi el procés de conversió. Subsequent calls to the endpoint with the same parameters will return the current state of the conversion. (started, processed, or failed). During the conversion time, flipbook links will show a not-found page.
Endpoint síncron
POST https://heyzine.com/api1/rest
Exemple de petició
{
"pdf": "https://codingfocus.com/sample.pdf",
"client_id": "d3m0",
"prev_next": true,
"rtl": true
}
Exemple de resposta
{
"id": "e8264ee61f7f5a9fd4291590480762b998574610.pdf",
"url": "https://heyzine.com/flip-book/e8264ee61f.html",
"thumbnail": "https://cdn.heyzine.com/flip-book/cover/e8264ee61f.jpg",
"pdf": "https://cdn.heyzine.com/flip-book/pdf/e8264ee61f7f5a9fd4291590480762b998574610.pdf",
"meta": {
"num_pages": 6,
"aspect_ratio": 0.7078
}
}
Endpoint asíncron
POST https://heyzine.com/api1/async
Exemple de petició
{
"pdf": "https://codingfocus.com/sample.pdf",
"client_id": "d3m0",
"show_info": true,
"background_color": "ffffff",
"rtl": true
}
Exemple de resposta
{
"id": "e8264ee61f7f5a9fd4291590480762b998574610.pdf",
"url": "https://heyzine.com/flip-book/e8264ee61f.html",
"thumbnail": "https://cdn.heyzine.com/flip-book/cover/e8264ee61f.jpg",
"pdf": "https://cdn.heyzine.com/flip-book/pdf/e8264ee61f7f5a9fd4291590480762b998574610.pdf",
"meta": {
"num_pages": 6,
"aspect_ratio": 0.7078
},
"state": "processed"
}
Gestió de flipbooks
Obtén informació del flipbook
Obtén tota la informació disponible sobre un flipbook concret mitjançant el seu identificador.
Endpoint
GET https://heyzine.com/api1/flipbook-details
Authorization: Bearer API_KEY
Exemple de petició
{
"id": "c16430e4c0cd91123474d0621b01b8f1f944f48ff85b1.pdf"
}
Exemple de resposta
{
"id": "c16430e4c0cd91123474d0621b01b8f1f944f48ff85b1.pdf",
"date": "2024-11-05T13:58:48Z",
"title": "My awesome test",
"subtitle": "Flipbook conversion using the API",
"description": "The description of the flipbook",
"private": "Internal management note",
"pages": 67,
"tags": "catalogs,summer,promotions",
"links": {
"custom": "https://mycustomdomain.aflip.in/my-flipbook",
"base": "https://heyzine.com/flip-book/c16430e4c0.html",
"thumbnail": "https://cdn.heyzine.com/flip-book/cover/c16430e4c0.jpg",
"pdf": "https://cdn.heyzine.com/flip-book/pdf/c16430e4c0cd91123474d0621b01b8f1f944f48ff85b1.pdf"
},
"oembed": { oEmbed object},
}
Llista els flipbooks
Obtén una llista de tots els flipbooks del compte.
Endpoint
GET https://heyzine.com/api1/flipbook-list
Authorization: Bearer API_KEY
Exemple de resposta
[
{
"id": "c16430e4c0cd91123474d0621b01b8f1f944f48ff85b1.pdf",
"date": "2024-11-05T13:58:48Z",
"title": "My awesome test",
"subtitle": "Flipbook conversion using the API",
"description": "The description of the flipbook",
"private": "Internal management note",
"pages": 67,
"size": 143135,
"links": {
"custom": "https://mycustomdomain.aflip.in/my-flipbook",
"base": "https://heyzine.com/flip-book/c16430e4c0.html",
"thumbnail": "https://cdn.heyzine.com/flip-book/cover/c16430e4c0.jpg",
"pdf": "https://cdn.heyzine.com/flip-book/pdf/c16430e4c0cd91123474d0621b01b8f1f944f48ff85b1.pdf"
}
}
]
Actualitza el disseny del flipbook
Canvia l’aspecte i les opcions d’un flipbook existent. La plantilla opcional copia els estils d’un altre flipbook del teu compte. Els camps especificats sobreescriuen els camps de la plantilla.
Endpoint
PATCH https://heyzine.com/api1/flipbook-design
Autorització: Bearer API_KEY
Exemple de petició
{
"id": "c16430e4c0cd91123474d0621b01b8f1f944f48ff85b1.pdf",
"template": "02d4d12c08593f3d10a5f61338758eaa0bf67abd.pdf",
"page_effect": "fade",
"url_path": "my-flipbook",
"url_domain": "docs.example.com",
"rtl": true
}
Exemple de resposta
{
"success": true,
"code": 200,
"msg": "Flipbook updated"
}
Suprimeix el flipbook
Suprimeix un flipbook concret mitjançant el seu identificador.
Endpoint
POST https://heyzine.com/api1/flipbook-delete
Authorization: Bearer API_KEY
Exemple de petició
{
"id": "c16430e4c0cd91123474d0621b01b8f1f944f48ff85b1.pdf"
}
Exemple de resposta
{
"success": true,
"code": 200,
"msg": "Flipbook deleted"
}
Bookshelf Management
List bookshelves
Get a list of all the bookshelves in the account.
Endpoint
GET https://heyzine.com/api1/bookshelf-list
Authorization: Bearer API_KEY
Exemple de resposta
[
{
"id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
"date": "2025-03-15T10:30:00Z",
"title": "Product Catalogs",
"subtitle": "All product flipbooks",
"description": "Collection of product catalogs",
"flipbook_count": 5,
"links": {
"url": "https://heyzine.com/shelf/a1b2c3d4e5.html",
"thumbnail": "https://heyzine.com/shelf/cover/a1b2c3d4e5.html"
}
}
]
List flipbooks in a bookshelf
Get a list of all the flipbooks in a specific bookshelf, ordered by position.
Endpoint
GET https://heyzine.com/api1/bookshelf-flipbooks
Authorization: Bearer API_KEY
Exemple de petició
{
"id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
}
Exemple de resposta
[
{
"id": "c16430e4c0cd91123474d0621b01b8f1f944f48ff85b1.pdf",
"date": "2024-11-05T13:58:48Z",
"title": "My awesome test",
"subtitle": "Flipbook conversion using the API",
"description": "The description of the flipbook",
"pages": 67,
"position": 0,
"links": {
"custom": "https://mycustomdomain.aflip.in/my-flipbook",
"base": "https://heyzine.com/flip-book/c16430e4c0.html",
"thumbnail": "https://cdn.heyzine.com/flip-book/cover/c16430e4c0.jpg",
"pdf": "https://cdn.heyzine.com/flip-book/pdf/c16430e4c0cd91123474d0621b01b8f1f944f48ff85b1.pdf"
}
}
]
Add flipbook to bookshelf
Add a flipbook to a bookshelf. Optionally specify a position to control the order.
Endpoint
POST https://heyzine.com/api1/bookshelf-add
Authorization: Bearer API_KEY
Exemple de petició
{
"id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
"flipbook_id": "c16430e4c0cd91123474d0621b01b8f1f944f48ff85b1.pdf",
"position": 2
}
Exemple de resposta
{
"success": true,
"code": 200,
"msg": "Flipbook added to bookshelf"
}
Remove flipbook from bookshelf
Remove a flipbook from a bookshelf.
Endpoint
POST https://heyzine.com/api1/bookshelf-remove
Authorization: Bearer API_KEY
Exemple de petició
{
"id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
"flipbook_id": "c16430e4c0cd91123474d0621b01b8f1f944f48ff85b1.pdf"
}
Exemple de resposta
{
"success": true,
"code": 200,
"msg": "Flipbook removed from bookshelf"
}
Protecció amb contrasenya
Configura la protecció amb contrasenya
Configura el mode de protecció amb contrasenya i el text que s’utilitzarà per demanar el nom d’usuari i la contrasenya a la pàgina d’inici de sessió del flipbook.
Endpoint
POST https://heyzine.com/api1/access-setup
Authorization: Bearer API_KEY
Exemple de petició
{
"name": "1f1aa4115833b3ee73a562ca27a422119ee22dc.pdf",
"mode": "users",
"text_user": "Please, type your email:",
"text_password": "Please, type your password:"
}
Exemple de resposta
{
"success": true,
"code": 200,
"msg": "Access configuration set"
}
Afegeix accés d’usuari
Concedeix a un usuari accés a un flipbook.
email_link, email_code, send_code and webhook_code are only available on Premium Plans
When access_type is webhook_code, password is the URL that receives a JSON POST with the following data. {"data": {"id_webhook", "type": "webhook_code", "code", "email", "timestamp", "expires_at", "flipbook": {"id", "title", "url", "kind"}}}. Any non-200 response is retried up to three times.
Endpoint
POST https://heyzine.com/api1/access-add
Authorization: Bearer API_KEY
Exemple de petició
{
"name": "1f1aa4115833b3ee73a562ca27a422119ee22dc.pdf",
"access_type": "user_pass",
"user": "reader@heyzine.com",
"password": "mYp4ssW0rd"
}
Exemple de resposta
{
"success": true,
"code": 200,
"msg": "Added to the access list"
}
Suprimeix l’accés de l’usuari
Revoca l’accés d’un usuari a un flipbook.
Endpoint
POST https://heyzine.com/api1/access-remove
Authorization: Bearer API_KEY
Exemple de petició
{
"name": "1f1aa4115833b3ee73a562ca27a422119ee22dc.pdf",
"user": "reader@heyzine.com",
}
Exemple de resposta
{
"success": true,
"code": 200,
"msg": "Removed from the access list"
}
Find the ID of a flipbook on your account
jQuery PDF a flipbook
jQuery plugin to convert all the PDF links on your site to flipbooks.
Pasos d'ús:
1.-Inclure jquery i el plugin mitjançant un CDN o descarrega i inclou-ho al teu projecte:
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
<script type="text/javascript" src="https://cdn.heyzine.com/release/jquery.pdfflipbook.4.js"></script>
2.-Crida el connector amb el Client Id per convertir tots els enllaços:
$('a').pdfFlipbook({ key: 'd3m0' });
3.-Opcionalment, pots usar atributs DOM per personalitzar el flipbook i la presentació resultant:
| Paràmetre | Requerit | Descripció | Exemple |
|---|---|---|---|
| flipbook | Opcional | Quan un element té un href, aquest atribut s'ignorarà, sino defineix la url del fitxer pdf i l'assigna al event de clic per a la navegació. | <span flipbook="/link-to-pdf.pdf">Això és un flipbook</span> |
| title | Opcional | Títol per a la pàgina | <a flipbook="/link-to-pdf.pdf" title="title">Això és un flipbook</a> |
| subtitle | Opcional | Subtítol per a la pàgina | <a flipbook="/link-to-pdf.pdf" subtitle="subtitle">Això és un flipbook</a> |
| showdownload | Opcional | Mostra el botó de descarrega a la pàgina del flipbook | <a flipbook="/link-to-pdf.pdf" showdownload>Això és un flipbook</a> |
| showmodal | Opcional | Obrir el flipbpok a un diàleg sencill sobre la pàgina | <a flipbook="/link-to-pdf.pdf" showmodal>Això és un flipbook</a> |
See the jquery demo here: Demo
API d’oEmbed
oEmbed és una API que permet a llocs web i aplicacions de tercers obtenir un codi d’incrustació HTML per mostrar flipbooks de Heyzine.
Detecció dels URI d’oEmbed
La majoria de flipbooks admeten oEmbed. L’aplicació pot detectar l’URI d’oEmbed corresponent cercant al flipbook un element amb el tipus "application/json+oembed".
Per exemple, el flipbook de mostra inclou l’etiqueta d’enllaç següent:
<link rel="alternate" type="application/json+oembed" href="https://heyzine.com/api1/oembed?url=https%3A%2F%2Fheyzine.com%2Fflip-book%2Fdce36e099f.html&format=json" title="PDF to Flipbook | Heyzine" />
Ús de dades d’oEmbed de Heyzine a la teva aplicació o lloc web
Envia una petició GET a /api1/oembed, amb el paràmetre url establert en un enllaç de flipbook per obtenir les seves dades d’oEmbed.
Heyzine admet els paràmetres estàndard d’oEmbed 1.0 (url, format, maxwidth i maxheight).
Request
https://heyzine.com/api1/oembed?url=https%3A%2F%2Fheyzine.com%2Fflip-book%2Fdce36e099f.html&format=json
Response
{
"type": "rich",
"version": "1.0",
"title": "Venice guide",
"provider_name": "Heyzine",
"provider_url": "https:\/\/heyzine.com",
"html": "<iframe allowfullscreen=\"allowfullscreen\" allow=\"clipboard-write\" scrolling=\"no\" class=\"fp-iframe\" style=\"width: 100%; height: 600px;\" src=\"https:\/\/heyzine.com\/flip-book\/dce36e099f.html\"><\/iframe>",
"width": 1920,
"height": 2717,
"thumbnail_url": "https:\/\/heyzine.com\/files\/uploaded\/v2\/dce36e099f71f95449f722bfc227cb4bdd1b30f0.pdf-thumb.jpg",
"thumbnail_width": 400,
"thumbnail_height": 566
}
Webhooks
Heyzine admet webhooks per notificar esdeveniments a una URL externa amb una freqüència predefinida.
Accedeix a la secció de webhooks del teu compte per definir els endpoints i la freqüència.
Webhook de leads
El webhook es cridarà cada vegada que es recullin leads nous en qualsevol formulari de generació de leads del compte.
Referència del cos de la petició:
data: {
"id_webhook": Identifier of the event,
"date": Date an time (UTC) of the event request,
"leads": [
0: {
date: Date and time (UTC) when the lead was collected,
first_value: Answer to the first field on the form,
second_value: Answer to the second field on the form,
flipbook: {
id: Identifier of the flipbook containing the form,
title: Title set on the publish settings of the flipbook
},
answer: [
0: {
label: Question on the form,
value: Lead answer,
},...
]
},...
]
}
MCP Server
The Heyzine MCP server lets AI assistants such as Claude, ChatGPT, Cursor or any other Model Context Protocol client work with your account directly: convert PDFs and office documents, list and update flipbooks, manage bookshelves and password access, and search the text of your documents.
It is a single endpoint speaking MCP over Streamable HTTP. Every tool runs the same code as the REST API described above, so plan limits, permissions and validation are identical, and the assistant can never do anything you could not do with your own API key.
Server URL
https://heyzine.com/mcp
Connection
Option 1: with your API key
The quickest way, for any client that lets you add a request header. Use the server URL plus your API key as a bearer token. Get your API key.
Clients that can only launch local commands can reach the server through the mcp-remote bridge, shown in the second example.
Remote MCP client (Claude, Codex, Cursor, VS Code)
{
"mcpServers": {
"heyzine": {
"url": "https://heyzine.com/mcp",
"headers": {
"Authorization": "Bearer API_KEY"
}
}
}
}
Option 2: sign in with Heyzine
For connectors that only ask for a URL, such as the ChatGPT and Claude connector directories. Add the server URL and nothing else.
The client discovers the authorization server on its own, opens a Heyzine login and consent screen, and stores the resulting token. There is no key to copy, and the token only works on the MCP endpoint, never on the REST API.
To revoke access, reset your API keys. That disconnects every app authorized on the account, so any other integration will have to be authorized again too.
Connector URL
https://heyzine.com/mcp
Try it with the official inspector
npx @modelcontextprotocol/inspector
Available tools
Ask the assistant in plain language, and it picks the tool. The list is here so you know what it can reach.
| Tool | What it does | Required arguments |
|---|---|---|
| heyzine_convert_attached_pdf | Turn a document attached to the conversation into a flipbook and return the finished result in the same call. | |
| heyzine_convert_pdf_async | Start converting a document from a public URL and return immediately. Call again with the same URL to check progress. Preferred way to convert a URL. | |
| heyzine_convert_pdf | Convert a document from a public URL and wait for the finished flipbook. Large documents may exceed the client timeout. | |
| heyzine_list_flipbooks | List the flipbooks in the account, most recent first. | — |
| heyzine_flipbook_details | Full details of one flipbook: URLs, page count and design settings. | id |
| heyzine_update_flipbook_design | Change the design and publication settings of an existing flipbook. | id |
| heyzine_delete_flipbook | Permanently delete a flipbook. | id |
| heyzine_set_flipbook_social | Set the title, description and thumbnail used when a flipbook is shared on social networks. | id |
| heyzine_set_bookshelf_social | Same, for a bookshelf. | id |
| heyzine_list_bookshelves | List the bookshelves in the account. | — |
| heyzine_list_bookshelf_flipbooks | List the flipbooks placed on one bookshelf, in display order. | id |
| heyzine_add_to_bookshelf | Place an existing flipbook on a bookshelf. | id, flipbook_id |
| heyzine_remove_from_bookshelf | Remove a flipbook from a bookshelf. The flipbook itself is kept. | id, flipbook_id |
| heyzine_access_setup | Configure the password protection mode of a flipbook or bookshelf. | id, mode |
| heyzine_access_add | Add a user or password to an access list. | id, access_type, user or password |
| heyzine_access_remove | Remove a user or password from an access list. | id, user or password |
| heyzine_oembed | oEmbed data, including the embed HTML, for a public flipbook URL. | url |
Password protection tools use the same id argument as the other flipbook tools, the id returned when the flipbook was created; set type to bookshelf when the target is a bookshelf.
Wherever a tool takes a flipbook or bookshelf id, the assistant may also pass the public link of the publication, the short id that appears in that link, or its custom URL path. Heyzine looks the value up among the publications of the connected account and uses the full id, so a link pasted into the chat is enough to protect, edit or delete a flipbook.
Bookshelf tools require a plan that includes bookshelves, and custom URLs require a plan with that feature.
Converting a document
The conversion tools take PDF, Word (doc, docx), PowerPoint (ppt, pptx), OpenDocument (odt, odp) and RTF files. There are two ways to hand over the document, one tool for each, and the assistant picks the right one on its own.
Attach the file to the chat, and the assistant uses heyzine_convert_attached_pdf. In ChatGPT, and any other client that can pass attachments to a connector, drop the document into the conversation and ask for a flipbook. Heyzine downloads and converts it while the tool runs, then returns the finished flipbook, so the file never has to be published or polled later.
Give a public URL, and the assistant uses heyzine_convert_pdf_async. Any direct link to a supported document works, which is what clients without file support use.
Both are idempotent: converting the same URL twice returns the same flipbook, and so does converting the same attachment twice. Uploading a second copy of a document is a new attachment, though, so that does create a second flipbook.
For MCP client developers
The endpoint accepts POST only, always answers application/json, and does not use SSE or sessions. Protocol versions 2026-07-28, 2025-11-25, 2025-06-18 and 2025-03-26 are accepted through the MCP-Protocol-Version header. A request with no token, or an invalid one, answers 401 with a WWW-Authenticate header pointing at the protected resource metadata, which is what starts the OAuth discovery below. Authorization uses OAuth 2.1 with PKCE (S256 only) and the mcp scope.
The server advertises io.modelcontextprotocol/skills under capabilities.extensions. skills/list and skills/get expose the workflow skills with complete static resource manifests, and resources/read returns each listed file with a verifiable SHA-256 digest.
Discovery and OAuth endpoints
GET https://heyzine.com/.well-known/oauth-protected-resource/mcp
GET https://heyzine.com/.well-known/oauth-authorization-server
POST https://heyzine.com/mcp/register
GET https://heyzine.com/mcp/authorize
POST https://heyzine.com/mcp/token
Calling a tool directly
POST https://heyzine.com/mcp
Authorization: Bearer API_KEY
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "heyzine_convert_pdf_async",
"arguments": {
"pdf": "https://codingfocus.com/sample.pdf",
"title": "My awesome test"
}
}
}
A failed tool is reported as a normal result with isError set to true, so the assistant can read the error message. Protocol errors, unknown methods and invalid tool requests produce JSON-RPC errors.
MCP Skills
These skills tell an MCP client how to combine the tools above for common workflows. Clients load them through skills/list and skills/get; the source files are also public at the URLs below.
| Skill | What it does |
|---|---|
| flipbook-publishing | Convert attached files or public URLs into flipbooks, then list, inspect, brand, update, or delete them. |
| bookshelf-collections | Organize existing flipbooks on bookshelves: list shelves, inspect contents, add, remove, or reposition. |
| flipbook-access-control | Enable or disable protection, set a shared password, and grant or revoke individual access. |
| flipbook-embedding | Get embed HTML for a flipbook and set the title, description, and thumbnail used in social previews. |
Límits API
Amb el pla gratuït tens fins a 5 flipbooks gratuïts i, un cop superat el límit, s’eliminaran les publicacions més antigues. Amb una subscripció tens conversions il·limitades. Suposem un ús raonable de l’API. Contacta amb nosaltres per obtenir informació sobre casos d’ús especials.
Metadades socials
Defineix les metadades socials d’un flipbook
Defineix el títol, la descripció i la miniatura de les metadades per compartir a les xarxes socials d’un flipbook concret.
Endpoint
POST https://heyzine.com/api1/flipbook-social
Autorització: Bearer API_KEY
Exemple de petició
{
"id": "c16430e4c0cd91123474d0621b01b8f1f944f48ff85b1.pdf",
"title": "My Flipbook Title",
"description": "A description for social sharing.",
"thumbnail": "https://example.com/image.jpg"
}
Exemple de resposta
{
"success": true
}
Defineix les metadades socials d’un prestatge
Defineix el títol, la descripció i la miniatura de les metadades per compartir a les xarxes socials d’un prestatge (biblioteca) concret.
Endpoint
POST https://heyzine.com/api1/bookshelf-social
Autorització: Bearer API_KEY
Exemple de petició
{
"id": "library1234567890abcdef",
"title": "My Bookshelf Title",
"description": "A description for social sharing.",
"thumbnail": "https://example.com/library-image.jpg"
}
Exemple de resposta
{
"success": true
}