API

Те же инструменты, что и на сайте, только из вашей программы. Три шага: загрузить файл, создать задачу, забрать результат.

Ключ доступа

Ключ создаётся в аккаунте и передаётся заголовком. Ключ виден один раз при создании — сохраните его сразу.

Authorization: Bearer sk_ваш_ключ

За минуту

1. Загружаем файл. Тело запроса — сам файл, без multipart. Тип определяется по содержимому, а не по расширению.

curl -X POST "https://formatika.app/api/v1/uploads?toolId=image.convert&filename=photo.png" \
  -H "Authorization: Bearer $FORMATIKA_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @photo.png

# {"id":"up_…","filename":"photo.png","mime":"image/png","bytes":820428}

2. Создаём задачу. Параметры проверяются схемой того инструмента, который вы указали.

curl -X POST "https://formatika.app/api/v1/jobs" \
  -H "Authorization: Bearer $FORMATIKA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toolId": "image.convert",
    "uploadIds": ["up_…"],
    "params": { "format": "webp", "quality": 82 }
  }'

# {"id":"job_…","status":"QUEUED","toolId":"image.convert","credits":0}

3. Опрашиваем состояние раз в секунду. Когда статус станет DONE, в files придут ссылки на результат — они подписаны и живут 15 минут.

curl "https://formatika.app/api/v1/jobs/job_…" -H "Authorization: Bearer $FORMATIKA_KEY"

# {"status":"DONE","progress":100,
#  "files":[{"filename":"photo.webp","bytes":9352,"url":"/api/v1/files/…?exp=…&sig=…"}]}

curl -O -J "https://formatika.app/api/v1/files/…?exp=…&sig=…"

То же самое из JavaScript

Пакет @formatika/sdk проходит эти три шага одним вызовом: загружает файл, ставит задачу, следит за ней и отдаёт результат. Работает везде, где есть fetch, — Node, Bun, Deno, edge. Ключ необязателен: без него действует та же бесплатная норма.

npm install @formatika/sdk

import { readFile, writeFile } from 'node:fs/promises'
import { Formatika } from '@formatika/sdk'

const formatika = new Formatika({ apiKey: process.env.FORMATIKA_API_KEY })

const result = await formatika.run({
  tool: 'image.convert',
  files: { filename: 'photo.heic', data: await readFile('photo.heic') },
  params: { format: 'webp', quality: 82 },
  onProgress: (percent) => console.log(percent),
})

for (const file of result.files) {
  await writeFile(file.filename, await file.download())
}

Нормы и кредиты

Бесплатно: 10 задач в сутки без аккаунта и 50 с аккаунтом. Сверх нормы задача выполняется за кредиты, при регистрации начисляется 50. Сколько списано — в поле credits ответа.

Инструменты

image.convertКонвертер изображений

Принимает:: image/*, .heic, .heif, .avif
Лимит:: 30 × 50 МБ

Параметры

format · enum (jpeg | png | webp | avif | tiff)
quality · number · default 82
resize · group · optional
stripMetadata · boolean · default true

image.resizeИзменить размер изображения

Принимает:: image/*, .heic, .heif, .avif
Лимит:: 30 × 50 МБ

Параметры

width · number · optional
height · number · optional
fit · enum (inside | cover | contain) · default "inside"
format · enum (same | jpeg | png | webp) · default "same"
quality · number · default 85

image.compressСжать изображение

Принимает:: image/*, .heic, .heif, .avif
Лимит:: 30 × 50 МБ

Параметры

targetKb · number · optional
quality · number · default 75
format · enum (same | jpeg | webp) · default "same"
maxWidth · number · optional

image.cropОбрезать изображение

Принимает:: image/*, .heic, .heif, .avif
Лимит:: 30 × 50 МБ

Параметры

aspect · enum (1:1 | 4:3 | 3:4 | 16:9 | 9:16 | 3:2 | 2:3) · default "1:1"
position · enum (center | top | bottom | left | right) · default "center"
format · enum (same | jpeg | png | webp) · default "same"
quality · number · default 88

image.rotateПовернуть изображение

Принимает:: image/*, .heic, .heif, .avif
Лимит:: 30 × 50 МБ

Параметры

angle · enum (0 | 90 | 180 | 270) · default "90"
flipHorizontal · boolean · default false
flipVertical · boolean · default false
format · enum (same | jpeg | png | webp) · default "same"

image.metadataУдалить EXIF и геометку

Принимает:: image/*, .heic, .heif, .avif
Лимит:: 30 × 50 МБ

Параметры

keepIcc · boolean · default true

image.paletteПалитра из изображения

Принимает:: image/*, .heic, .heif, .avif
Лимит:: 10 × 50 МБ

Параметры

colors · number · default 6

audio.convertКонвертер аудио

Принимает:: audio/*, .m4a, .opus, .aac, .wma
Лимит:: 10 × 200 МБ

Параметры

format · enum (mp3 | aac | opus | flac | wav | ogg)
bitrateKbps · number · default 192
mono · boolean · default false
sampleRate · enum (22050 | 44100 | 48000 | same) · default "same"

audio.extractИзвлечь звук из видео

Принимает:: video/*, .mkv, .webm, .mov, .avi, .m4v
Лимит:: 5 × 500 МБ

Параметры

format · enum (same | mp3 | aac | opus | wav) · default "same"
bitrateKbps · number · default 192

audio.trimОбрезать аудио

Принимает:: audio/*, .m4a, .opus, .aac
Лимит:: 10 × 200 МБ

Параметры

start · string · default "0"
end · string · optional
reencode · boolean · default false
fade · boolean · default false

audio.normalizeВыровнять громкость

Принимает:: audio/*, .m4a, .opus, .aac
Лимит:: 10 × 200 МБ

Параметры

target · enum (-23 | -16 | -14) · default "-16"
truePeak · number · default -1.5

audio.mergeСклеить аудио

Принимает:: audio/*, .m4a, .opus, .aac
Лимит:: 20 × 200 МБ

Параметры

format · enum (same | mp3 | m4a | wav) · default "same"
bitrateKbps · number · default 192

audio.silence-trimОбрезать тишину

Принимает:: audio/*, .m4a, .opus, .aac
Лимит:: 10 × 200 МБ

Параметры

thresholdDb · number · default -45
keepMs · number · default 200

audio.tagsИзменить теги аудио

Принимает:: audio/*, .m4a, .opus, .aac
Лимит:: 20 × 200 МБ

Параметры

title · string · optional
artist · string · optional
album · string · optional
year · number · optional
clear · boolean · default false

video.convertКонвертировать видео

Принимает:: video/*, .mp4, .mov, .mkv, .webm, .avi, .m4v
Лимит:: 3 × 500 МБ

Параметры

format · enum (mp4 | webm | mkv) · default "mp4"
quality · number · default 24
speed · enum (fast | balanced | small) · default "fast"

video.compressСжать видео

Принимает:: video/*, .mp4, .mov, .mkv, .webm, .avi, .m4v
Лимит:: 2 × 500 МБ

Параметры

targetMb · number · default 25
audioKbps · number · default 96

video.resizeИзменить разрешение видео

Принимает:: video/*, .mp4, .mov, .mkv, .webm, .avi, .m4v
Лимит:: 3 × 500 МБ

Параметры

height · enum (1080p | 720p | 480p | 360p) · default "720p"
quality · number · default 24

video.trimОбрезать видео

Принимает:: video/*, .mp4, .mov, .mkv, .webm, .avi, .m4v
Лимит:: 3 × 500 МБ

Параметры

from · string · default "0"
to · string · default ""
precise · boolean · default false

video.muteУбрать звук из видео

Принимает:: video/*, .mp4, .mov, .mkv, .webm, .avi, .m4v
Лимит:: 5 × 500 МБ

Параметры

video.to-gifВидео в GIF

Принимает:: video/*, .mp4, .mov, .mkv, .webm, .avi, .m4v
Лимит:: 3 × 500 МБ

Параметры

from · string · default "0"
seconds · number · default 5
width · number · default 480
fps · number · default 12

video.subtitlesСубтитры в видео

Принимает:: video/*, .mp4, .mov, .mkv, .webm, .srt, .vtt, .ass, .ssa
Лимит:: 2 × 500 МБ

Параметры

mode · enum (burn | attach) · default "burn"
fontSize · number · default 24

video.thumbnailКадр из видео

Принимает:: video/*, .mp4, .mov, .mkv, .webm, .avi, .m4v
Лимит:: 5 × 500 МБ

Параметры

at · string · default ""
format · enum (jpg | png | webp) · default "jpg"
width · number · default 0

pdf.mergeОбъединить PDF

Принимает:: application/pdf, .pdf
Лимит:: 30 × 100 МБ

Параметры

keepMetadata · boolean · default false

pdf.splitРазделить PDF

Принимает:: application/pdf, .pdf
Лимит:: 5 × 100 МБ

Параметры

mode · enum (ranges | each) · default "ranges"
pages · string · default "1"

pdf.pagesПовернуть и удалить страницы PDF

Принимает:: application/pdf, .pdf
Лимит:: 10 × 100 МБ

Параметры

rotate · enum (0 | 90 | 180 | 270) · default "0"
remove · string · default ""
rotatePages · string · default ""

pdf.from-imageКартинки в PDF

Принимает:: image/*, .heic, .heif, .avif
Лимит:: 50 × 50 МБ

Параметры

pageSize · enum (fit | a4 | letter) · default "fit"
marginMm · number · default 0
quality · number · default 85

pdf.compressСжать PDF

Принимает:: application/pdf, .pdf
Лимит:: 10 × 100 МБ

Параметры

preset · enum (screen | ebook | printer) · default "ebook"
grayscale · boolean · default false

pdf.to-imagePDF в картинки

Принимает:: application/pdf, .pdf
Лимит:: 5 × 100 МБ

Параметры

format · enum (jpeg | png) · default "jpeg"
dpi · enum (72 | 150 | 300) · default "150"
pages · string · default ""

text.subtitlesКонвертировать субтитры

Принимает:: .srt, .vtt, text/vtt, text/plain, application/x-subrip
Лимит:: 20 × 5 МБ

Параметры

format · enum (vtt | srt) · default "vtt"
shiftMs · number · default 0

archive.zipСоздать ZIP

Принимает:: */*
Лимит:: 100 × 100 МБ

Параметры

level · enum (fast | normal | max) · default "normal"

archive.unzipРаспаковать ZIP

Принимает:: application/zip, application/x-zip-compressed, .zip
Лимит:: 5 × 100 МБ

Параметры

data.convertCSV, JSON и YAML

Принимает:: text/csv, text/tab-separated-values, application/json, application/yaml, text/yaml, .csv, .tsv, .json, .yaml, .yml
Лимит:: 20 × 20 МБ

Параметры

format · enum (csv | json | yaml) · default "json"

document.convertДокументы в PDF

Принимает:: application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.openxmlformats-officedocument.presentationml.presentation, application/msword, application/vnd.ms-excel, application/vnd.ms-powerpoint, application/vnd.oasis.opendocument.text, application/vnd.oasis.opendocument.spreadsheet, application/vnd.oasis.opendocument.presentation, application/rtf, .docx, .xlsx, .pptx, .doc, .xls, .ppt, .odt, .ods, .odp, .rtf, .txt
Лимит:: 5 × 50 МБ

Параметры

archival · boolean · default false

utility.hashКонтрольная сумма файла

Принимает:: */*
Лимит:: 20 × 500 МБ

Параметры

algorithm · enum (md5 | sha1 | sha256 | sha512) · default "sha256"

utility.base64Файл в base64 и обратно

Принимает:: */*
Лимит:: 20 × 20 МБ

Параметры

dataUri · boolean · default false
lineBreaks · boolean · default false

image.for-webФото для сайта

Принимает:: image/*, .heic, .heif, .avif
Лимит:: 30 × 50 МБ

Параметры

document.for-emailДокумент для отправки

Принимает:: application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.openxmlformats-officedocument.presentationml.presentation, application/msword, application/vnd.ms-excel, application/vnd.ms-powerpoint, application/vnd.oasis.opendocument.text, application/vnd.oasis.opendocument.spreadsheet, application/vnd.oasis.opendocument.presentation, application/rtf, .docx, .xlsx, .pptx, .doc, .xls, .ppt, .odt, .ods, .odp, .rtf, .txt
Лимит:: 5 × 50 МБ

Параметры

video.for-messengerВидео для мессенджера

Принимает:: video/*, .mp4, .mov, .mkv, .webm, .avi, .m4v
Лимит:: 2 × 500 МБ

Параметры

Ошибки

Наружу приходит код, а не текст: сообщение вы собираете сами, на своём языке. HTTP-статус соответствует коду.

404 UNKNOWN_TOOL400 INVALID_PARAMS413 INPUT_TOO_LARGE400 TOO_MANY_FILES415 UNSUPPORTED_FORMAT422 CORRUPT_INPUT413 INPUT_TOO_LONG413 PIXEL_LIMIT500 ENGINE_FAILED504 TIMEOUT507 OUT_OF_MEMORY499 CANCELED402 QUOTA_EXCEEDED429 RATE_LIMITED401 UNAUTHORIZED403 FORBIDDEN404 NOT_FOUND410 EXPIRED500 STORAGE_FAILED500 INTERNAL

Полная спецификация OpenAPI