ConvertAPI · Example Payload
Convertapi Examples
File ConversionPDFDocumentsImagesAudioVideoE-booksOffice DocumentsBatch Processing
Convertapi Examples is an example object payload from ConvertAPI, with 12 top-level fields. It illustrates the shape of data this provider's APIs accept or return.
Top-level fields
POST /uploadGET /userGET /user/statisticPOST /convert/pdf/to/jpgPOST /convert/docx/to/pdfPOST /convert/jpg/to/pdfPOST /convert/html/to/pdfPOST /convert/xlsx/to/pdfPOST /convert/png/to/jpgGET /d/{fileId}DELETE /d/{fileId}HEAD /d/{fileId}
Example Payload
{
"POST /upload": {
"path": "/upload",
"method": "POST",
"summary": "Upload file",
"description": "When source files require multiple conversions, optimizing performance is possible by uploading the file once and then performing multiple conversions without the need for re-uploading.\nThe uploaded file is securely stored on the convertapi.com server for a maximum period of 3 hours and can be accessed through a unique secret URL with a UUID.\nIn conversion requests, the file can be referenced using the File ID, which is generated upon successful file upload.\n",
"parameters": [
{
"name": "filename",
"in": "query",
"description": "File name.\nRequired if the header field `content-disposition` is not set.\n",
"schema": {
"type": "string"
},
"example": "myfile.pdf"
},
{
"name": "content-disposition",
"in": "header",
"description": "This header field is used to determine the file name.\n**Required** if query parameter `filename` is not set.\nQuery parameter `filename` overrides this parameter.\n",
"schema": {
"type": "string"
},
"example": "Content-Disposition: inline; filename=\"myfile.pdf\""
},
{
"name": "fileId",
"in": "query",
"description": "Custom ID for the file that is uploaded. Lowercase alphanumeric character string.",
"schema": {
"$ref": "#/components/schemas/fileId"
},
"example": "25811safe8e61dd3f51ef00ee5f58b92"
},
{
"name": "url",
"in": "query",
"description": "Remote file URL. The URL of the file you want to upload and store on the ConvertAPI file server.\nIf the file is accessible by the URL, it can be uploaded directly from its location by passing the URL instead of the file itself.\n",
"schema": {
"type": "string",
"format": "uri"
},
"example": "https://example.com/myfile.pdf"
},
{
"name": "headername",
"in": "query",
"description": "Remote file request header field name (used exclusively in conjunction with the `url` parameter).",
"schema": {
"type": "string"
},
"example": "header-field-name"
},
{
"name": "headervalue",
"in": "query",
"description": "Remote file request header field value (used exclusively in conjunction with the `url` and `headername` parameters).",
"schema": {
"type": "string"
},
"example": "Header field value"
}
],
"tags": [
"File Server"
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"description": "The file to upload",
"format": "binary"
}
}
},
"example": "There can be only one part with file data.\n```http\n[POST]\nhttps://v2.convertapi.com/upload \nContent-Type: multipart/form-data; boundary=----7MA4YWxkTrZu0gW\n\n------7MA4YWxkTrZu0gW\nContent-Disposition: form-data; name=\"file\"; filename=\"my_file.doc\"\n\n--FILE DATA--\n------7MA4YWxkTrZu0gW--\n```\n"
},
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
},
"example": "```http\n[POST]\nhttps://v2.convertapi.com/upload \nContent-Disposition: inline; filename=\"my_file.doc\"\n\n--FILE DATA--\n```\n"
}
}
},
"responses": {
"200": {
"description": "The file to upload",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"FileName": {
"type": "string",
"example": "myfile.docx"
},
"FileExt": {
"type": "string",
"example": "docx"
},
"FileSize": {
"type": "integer",
"format": "int32",
"example": "1026736"
},
"FileId": {
"type": "string",
"example": "9shcxkk4zvesuzl2xavmg9afqbr2ty62"
},
"Url": {
"type": "string",
"format": "uri",
"example": "https://v2.convertapi.com/d/9shcxkk4zvesuzl2xavmg9afqbr2ty62"
}
}
}
},
"text/plain": {
"schema": {
"format": "string",
"example": "9shcxkk4zvesuzl2xavmg9afqbr2ty62"
}
}
}
},
"400": {
"description": "File request with an invalid file ID",
"content": {}
},
"415": {
"description": "The file type is not supported",
"content": {}
},
"500": {
"description": "Unable to store or download remote file",
"content": {}
}
}
},
"GET /user": {
"path": "/user",
"method": "GET",
"summary": "User information",
"description": "The endpoint returns information about a user account. It is helpful to check the account balance status and other data. The endpoint can be authenticated only with a secret, the token is not accepted.\n",
"parameters": [],
"tags": [
"User"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"Active": {
"type": "boolean",
"description": "User can perform conversions"
},
"Email": {
"type": "string",
"description": "User email",
"example": "user@example.com"
},
"Secret": {
"type": "string",
"description": "Authentication secret",
"example": "1XKrszdaFZH33WTh"
},
"ApiKey": {
"type": "integer",
"description": "Authentication API key",
"format": "int64",
"example": 842679918
},
"ConversionsTotal": {
"type": "integer",
"description": "Plan conversion count",
"format": "int64",
"example": 5000
},
"ConversionsConsumed": {
"type": "integer",
"description": "Conversions consumed",
"format": "int64",
"example": 458
},
"SecondsLeft": {
"type": "integer",
"format": "int64",
"deprecated": true
},
"FullName": {
"type": "string",
"description": "User full name",
"example": "John Wick"
}
}
}
}
}
},
"401": {
"description": "",
"content": {}
}
}
},
"GET /user/statistic": {
"path": "/user/statistic",
"method": "GET",
"summary": "Statistics",
"description": "The endpoint that returns information about your usage statistics based on the date range.",
"parameters": [
{
"name": "startDate",
"in": "query",
"description": "Conversions from date",
"required": true,
"schema": {
"type": "string"
},
"example": "2023-09-01"
},
{
"name": "endDate",
"in": "query",
"description": "Conversions to date",
"required": true,
"schema": {
"type": "string"
},
"example": "2023-09-30"
}
],
"tags": [
"User"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"Result": {
"type": "boolean",
"description": "Is conversion successful"
},
"CreatedAt": {
"type": "string",
"description": "Conversion time"
},
"ExecutionTime": {
"type": "integer",
"description": "Conversion duration",
"format": "int32"
},
"Converter": {
"type": "string",
"description": "File converter name"
},
"SourceFormat": {
"type": "string",
"description": "Source file format (docx, pdf, jpg etc.)"
},
"DestinationFormat": {
"type": "string",
"description": "Destination file format (docx, pdf, jpg etc.)"
},
"Ip": {
"type": "string",
"description": "File conversion request origin IP"
},
"Source": {
"type": "string",
"description": "Source file name"
},
"Error": {
"type": "string",
"description": "Conversion error message"
}
}
}
}
},
"text/csv": {
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "",
"content": {}
}
}
},
"POST /convert/pdf/to/jpg": {
"path": "/convert/pdf/to/jpg",
"method": "POST",
"summary": "",
"description": "",
"parameters": [],
"tags": [
"Conversion"
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"required": [
"File"
],
"type": "object",
"properties": {
"Timeout": {
"maximum": 1200,
"minimum": 10,
"type": "integer",
"description": "Conversion timeout in seconds.",
"default": 900,
"x-ca-featured": false,
"x-ca-label": "Timeout",
"x-ca-group": "Execution",
"x-ca-type": "Integer",
"x-ca-representation": "Default",
"x-ca-range": {
"from": "10",
"to": "1200"
}
},
"StoreFile": {
"type": "boolean",
"description": "When the `StoreFile` parameter is set to `True`, your converted file is written to ConvertAPI\u2019s encrypted, temporary storage and made available via a time-limited secure download URL, valid for up to 3 hours. After this period, the file is permanently deleted.\r\n\r\nWhen `StoreFile` is set to `False`, conversion happens entirely in-memory. The raw file bytes are streamed back in the API response without touching disk or external storage, ensuring maximum security and zero persistence so that only you can access the content.\r\n",
"default": false,
"x-ca-featured": false,
"x-ca-label": "Store file",
"x-ca-group": "Output",
"x-ca-type": "Bool",
"x-ca-representation": "Default"
},
"File": {
"type": "string",
"description": "File to be converted. Value can be URL or file content.",
"format": "binary",
"x-ca-featured": true,
"x-ca-label": "File",
"x-ca-group": "Input",
"x-ca-type": "File",
"x-ca-representation": "Default",
"x-ca-allowed-extensions": [
"pdf"
]
},
"FileName": {
"type": "string",
"description": "The `FileName` property defines the name of the output file(s) generated by the file conversion API, ensuring safe and\r\nunique file naming. It sanitizes input filenames to remove potentially harmful characters, automatically appends the\r\ncorrect file extension based on the target format, and includes an indexing feature to distinguish multiple output files\r\nfrom a single input. For example, converting `report.docx` to PDF format might result in `report.pdf` for a single file,\r\nor `report_0.pdf`, `report_1.pdf` for multiple files, ensuring each output file is uniquely identifiable.",
"x-ca-featured": false,
"x-ca-label": "Output file name",
"x-ca-group": "Output",
"x-ca-type": "String",
"x-ca-representation": "Default",
"x-ca-range": {
"from": "1",
"to": "200"
}
},
"Password": {
"type": "string",
"description": "Sets the password to open protected PDF.",
"x-ca-featured": false,
"x-ca-label": "Open password",
"x-ca-group": "Input",
"x-ca-type": "String",
"x-ca-representation": "Default"
},
"PageRange": {
"type": "string",
"description": "Set PDF page range to convert. Example 1-10 or 1,2,5.",
"default": "1-2000",
"x-ca-featured": false,
"x-ca-label": "Page Range",
"x-ca-group": "PDF",
"x-ca-type": "String",
"x-ca-representation": "Default",
"x-ca-range": {
"from": "1",
"to": "2000"
}
},
"Rotate": {
"enum": [
"default",
"none",
"rotate90",
"rotate180",
"rotate270"
],
"type": "string",
"description": "Set PDF page rotation before converting to image.",
"default": "default",
"x-ca-featured": false,
"x-ca-label": "Rotate page",
"x-ca-group": "PDF",
"x-ca-type": "Collection",
"x-ca-representation": "Dropdown",
"x-ca-values": {
"default": "Default",
"none": "None",
"rotate90": "Rotate 90",
"rotate180": "Rotate 180",
"rotate270": "Rotate 270"
}
},
"CropTo": {
"enum": [
"BoundingBox",
"TrimBox",
"MediaBox",
"ArtBox",
"BleedBox"
],
"type": "string",
"description": "Defines the options for cropping the page.",
"default": "BoundingBox",
"x-ca-featured": false,
"x-ca-label": "Crop to box",
"x-ca-group": "PDF",
"x-ca-type": "Collection",
"x-ca-representation": "Dropdown",
"x-ca-values": {
"BoundingBox": "Bounding Box",
"TrimBox": "Trim Box",
"MediaBox": "Media Box",
"ArtBox": "Art Box",
"BleedBox": "Bleed Box"
}
},
"ImageResolution": {
"maximum": 800,
"minimum": 10,
"type": "integer",
"description": "Set output image resolution in dpi.",
"default": 200,
"x-ca-featured": false,
"x-ca-label": "Image resolution",
"x-ca-group": "JPG Output",
"x-ca-type": "Integer",
"x-ca-representation": "Default",
"x-ca-range": {
"from": "10",
"to": "800"
}
},
"Scale": {
"maximum": 300,
"minimum": 10,
"type": "integer",
"description": "Scale.md.",
"x-ca-featured": false,
"x-ca-label": "Scale image",
"x-ca-group": "JPG Output",
"x-ca-type": "Integer",
"x-ca-representation": "Default",
"x-ca-range": {
"from": "10",
"to": "300"
}
},
"ImageHeight": {
"maximum": 10000,
"minimum": 10,
"type": "integer",
"description": "Image height in pixels.",
"x-ca-featured": false,
"x-ca-label": "Image height",
"x-ca-group": "JPG Output",
"x-ca-type": "Integer",
"x-ca-representation": "Default",
"x-ca-range": {
"from": "10",
"to": "10000"
}
},
"ImageWidth": {
"maximum": 10000,
"minimum": 10,
"type": "integer",
"description": "Image width in pixels.",
"x-ca-featured": false,
"x-ca-label": "Image width",
"x-ca-group": "JPG Output",
"x-ca-type": "Integer",
"x-ca-representation": "Default",
"x-ca-range": {
"from": "10",
"to": "10000"
}
},
"FitToSize": {
"type": "boolean",
"description": "Gets or sets whether to scale the output image to fit within both ImageWidth and ImageHeight while maintaining the aspect ratio. When enabled, the image is sized to fit the more restrictive dimension. Requires both width and height to be specified.",
"default": false,
"x-ca-featured": false,
"x-ca-label": "Fit to size",
"x-ca-group": "JPG Output",
"x-ca-type": "Bool",
"x-ca-representation": "Default"
},
"BackgroundColor": {
"type": "string",
"description": "Applies a color to the transparent PDF background, thereby setting the background color of the generated images. You can specify a color name (e.g. `white` or `black`), or use color codes such as RGB (e.g. `255,0,0`) or HEX (e.g. `#FF0000`). To preserve transparency, set the property value to `transparent`.",
"x-ca-featured": false,
"x-ca-label": "Background Color",
"x-ca-group": "JPG Output",
"x-ca-type": "Color",
"x-ca-representation": "Default"
},
"ImageQuality": {
"maximum": 100,
"minimum": 10,
"type": "integer",
"description": "Set output image quality.",
"default": 75,
"x-ca-featured": false,
"x-ca-label": "Output image quality",
"x-ca-group": "JPG Output",
"x-ca-type": "Integer",
"x-ca-representation": "Default",
"x-ca-range": {
"from": "10",
"to": "100"
}
},
"ColorSpace": {
"enum": [
"rgb",
"cmyk",
"gray",
"monochrome"
],
"type": "string",
"description": "Set image color space.",
"default": "rgb",
"x-ca-featured": false,
"x-ca-label": "Image color space",
"x-ca-group": "JPG Output",
"x-ca-type": "Collection",
"x-ca-representation": "Dropdown",
"x-ca-values": {
"rgb": "RGB",
"cmyk": "CMYK",
"gray": "Gray",
"monochrome": "Monochrome"
}
},
"BitDepth": {
"enum": [
"default",
"1",
"2",
"4",
"8",
"16"
],
"type": "string",
"description": "Set the number of bits per color channel in the output image. Higher values improve color precision and gradient smoothness but increase file size.",
"default": "default",
"x-ca-featured": false,
"x-ca-label": "Bit depth",
"x-ca-group": "JPG Output",
"x-ca-type": "Collection",
"x-ca-representation": "Dropdown",
"x-ca-values": {
"default": "Default",
"1": "1 bit",
"2": "2 bits",
"4": "4 bits",
"8": "8 bits",
"16": "16 bits"
}
},
"CompressionLevel": {
"maximum": 9,
"minimum": 0,
"type": "integer",
"description": "Define the compression level (0\u20139). A higher value increases compression, reducing file size. For lossy formats (JPG), this decreases image quality; for lossless formats (PNG), it increases compression strength without affecting quality.",
"x-ca-featured": false,
"x-ca-label": "Compression level",
"x-ca-group": "JPG Output",
"x-ca-type": "Integer",
"x-ca-representation": "Default",
"x-ca-range": {
"from": "0",
"to": "9"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ConversionCost": {
"type": "integer",
"description": "This amount will be deducted from your balance after the conversion.",
"format": "int32",
"example": 1
},
"Files": {
"type": "array",
"items": {
"type": "object",
"properties": {
"FileName": {
"type": "string",
"description": "Name of the converted file.",
"example": "myfile.pdf"
},
"FileExt": {
"type": "string",
"description": "File type (file name extension)",
"example": "pdf"
},
"FileSize": {
"type": "integer",
"description": "File size",
"format": "int32",
"example": 111955
},
"FileId": {
"type": "string",
"description": "File ID",
"example": "25811safe8e61dd3f51ef00ee5f58b92"
},
"Url": {
"type": "string",
"description": "File URL",
"example": "https://v2.convertapi.com/d/v01plsb72o0cmdooq90w4d1lnqsf6oy4/myfile.pdf"
},
"FileData": {
"type": "string",
"description": "Base64 encoded file data",
"format": "base64",
"example": "JVBERi0xLjcKJb662+4KMSAwIG9iago8PC9UeXBlIC9DYXRhbG9n..."
}
}
}
}
},
"externalDocs": {
"url": "https://www.convertapi.com/doc/content-types#applicationjson-1"
}
}
},
"multipart/mixed": {
"schema": {
"type": "string",
"format": "binary",
"externalDocs": {
"url": "https://www.convertapi.com/doc/content-types#multipartmixed"
}
},
"example": "--43cf1475-ab15-4c6b-b5ee-e2cbcedfe92f\nConversionCost: 1\nContent-Type: application/octet-stream\nContent-Disposition: attachment; filename=\"my_file.pdf\"; size=8475\n\n--FILE CONTENT--\n--43cf1475-ab15-4c6b-b5ee-e2cbcedfe92f--\n"
},
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary",
"externalDocs": {
"url": "https://www.convertapi.com/doc/content-types#applicationoctet-stream-1"
}
}
}
}
},
"400": {
"description": "",
"content": {}
},
"401": {
"description": "",
"content": {}
},
"415": {
"description": "",
"content": {}
},
"500": {
"description": "",
"content": {}
},
"503": {
"description": "",
"content": {}
}
}
},
"POST /convert/docx/to/pdf": {
"path": "/convert/docx/to/pdf",
"method": "POST",
"summary": "",
"description": "",
"parameters": [],
"tags": [
"Conversion"
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"required": [
"File"
],
"type": "object",
"properties": {
"Timeout": {
"maximum": 1200,
"minimum": 10,
"type": "integer",
"description": "Conversion timeout in seconds.",
"default": 900,
"x-ca-featured": false,
"x-ca-label": "Timeout",
"x-ca-group": "Execution",
"x-ca-type": "Integer",
"x-ca-representation": "Default",
"x-ca-range": {
"from": "10",
"to": "1200"
}
},
"StoreFile": {
"type": "boolean",
"description": "When the `StoreFile` parameter is set to `True`, your converted file is written to ConvertAPI\u2019s encrypted, temporary storage and made available via a time-limited secure download URL, valid for up to 3 hours. After this period, the file is permanently deleted.\r\n\r\nWhen `StoreFile` is set to `False`, conversion happens entirely in-memory. The raw file bytes are streamed back in the API response without touching disk or external storage, ensuring maximum security and zero persistence so that only you can access the content.\r\n",
"default": false,
"x-ca-featured": false,
"x-ca-label": "Store file",
"x-ca-group": "Output",
"x-ca-type": "Bool",
"x-ca-representation": "Default"
},
"File": {
"type": "string",
"description": "File to be converted. Value can be URL or file content.",
"format": "binary",
"x-ca-featured": true,
"x-ca-label": "File",
"x-ca-group": "Input",
"x-ca-type": "File",
"x-ca-representation": "Default",
"x-ca-allowed-extensions": [
"doc",
"docx"
]
},
"FileName": {
"type": "string",
"description": "The `FileName` property defines the name of the output file(s) generated by the file conversion API, ensuring safe and\r\nunique file naming. It sanitizes input filenames to remove potentially harmful characters, automatically appends the\r\ncorrect file extension based on the target format, and includes an indexing feature to distinguish multiple output files\r\nfrom a single input. For example, converting `report.docx` to PDF format might result in `report.pdf` for a single file,\r\nor `report_0.pdf`, `report_1.pdf` for multiple files, ensuring each output file is uniquely identifiable.",
"x-ca-featured": false,
"x-ca-label": "Output file name",
"x-ca-group": "Output",
"x-ca-type": "String",
"x-ca-representation": "Default",
"x-ca-range": {
"from": "1",
"to": "200"
}
},
"Password": {
"type": "string",
"description": "Sets the password to open protected documents.",
"x-ca-featured": false,
"x-ca-label": "Open Password",
"x-ca-group": "Word",
"x-ca-type": "String",
"x-ca-representation": "Default"
},
"PageRange": {
"type": "string",
"description": "Set page range. Example 1-10.",
"default": "1-6000",
"x-ca-featured": false,
"x-ca-label": "Page Range",
"x-ca-group": "Word",
"x-ca-type": "String",
"x-ca-representation": "Default",
"x-ca-range": {
"from": "1",
"to": "6000"
}
},
"ConvertMarkups": {
"type": "boolean",
"description": "Convert document markups like revisions and comments.",
"default": false,
"x-ca-featured": false,
"x-ca-label": "Convert markups",
"x-ca-group": "Word",
"x-ca-type": "Bool",
"x-ca-representation": "Default"
},
"ConvertTags": {
"type": "boolean",
"description": "Convert document structure tags for accessibility.",
"default": false,
"x-ca-featured": false,
"x-ca-label": "Convert accessibility tags",
"x-ca-group": "Word",
"x-ca-type": "Bool",
"x-ca-representation": "Default"
},
"ConvertMetadata": {
"type": "boolean",
"description": "Convert document metadata like Title, Author, Keywords to PDF metadata.",
"default": true,
"x-ca-featured": false,
"x-ca-label": "Convert metadata",
"x-ca-group": "Word",
"x-ca-type": "Bool",
"x-ca-representation": "Default"
},
"BookmarkMode": {
"enum": [
"none",
"headings",
"bookmarks"
],
"type": "string",
"description": "Specifies how bookmarks are created in the generated PDF: `None` disables bookmark creation, `Headings` generates bookmarks based on document headings, and `Bookmarks` uses existing bookmarks defined in the original file.",
"default": "headings",
"x-ca-featured": false,
"x-ca-label": "Bookmark Mode",
"x-ca-group": "Word",
"x-ca-type": "Collection",
"x-ca-representation": "Dropdown",
"x-ca-values": {
"none": "None",
"headings": "Headings",
# --- truncated at 32 KB (106 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/convertapi/refs/heads/main/examples/convertapi-examples.json