API legível por máquina: OpenAPI 3.1, docs Markdown e llms.txt
Se você integra a Transloadit sem um dos nossos SDKs, até agora precisava ler a documentação e escrever manualmente cada chamada HTTP, corpo de requisição e manipulador de webhook. Agora toda a API está publicada como um documento OpenAPI 3.1, incluindo o webhook que enviamos a você, e cada página do nosso site também está disponível em Markdown. Gere um cliente tipado na sua linguagem, importe a API no Postman, valide os payloads dos webhooks com esquemas reais e direcione seu agente de programação com IA para uma documentação que ele realmente consiga ler.
O que a especificação abrange
O documento está em https://api2.transloadit.com/openapi.json. Uma cópia do mesmo arquivo está disponível em
https://transloadit.com/openapi.json. Ele usa OpenAPI 3.1.2 para a versão 2.0.0 da nossa API e
contém 43 operações distribuídas por 26 caminhos:
- Assemblies: criar, consultar o status, cancelar e reexecutar. As Assembly Notifications também podem ser listadas e reenviadas.
- Templates, credenciais de Template e Auth Keys com seus escopos.
- Uploads retomáveis via tus, estatísticas de Assembly, faturamento e estatísticas de filas.
POST /tokenpara tokens bearer do fluxo de credenciais do cliente do OAuth 2.0. Cada operação lista o escopo necessário, comotemplates:read.
Os esquemas de requisição incluem todas as Assembly
Instructions. Cada Step é descrito pelo esquema de parâmetros do seu
Robot. As respostas listam os códigos de erro que cada endpoint
pode retornar, como TEMPLATE_LIST_ERROR. Na data de publicação deste artigo, a seção
webhooks da especificação também descreve a Assembly
Notification que enviamos por POST para notify_url.
Gerar um cliente tipado
Veja como fazer em TypeScript, usando openapi-typescript para os tipos e
sua ferramenta complementar openapi-fetch para as chamadas:
mkdir my-app && cd my-app
npm init -y && npm pkg set type=module
npm install openapi-fetch @transloadit/utils ajv
npm install -D openapi-typescript typescript @types/node
npx openapi-typescript https://api2.transloadit.com/openapi.json \
--default-non-nullable false -o transloadit-api.d.ts
Por padrão, o openapi-typescript marca como obrigatória toda propriedade que tem um valor padrão.
Isso obrigaria você a passar parâmetros de Robot que são opcionais na especificação.
--default-non-nullable false mantém esses parâmetros opcionais. Nosso
tsconfig.json define skipLibCheck, pois o arquivo gerado
contém um tipo recursivo para valores JSON que, sem essa configuração, o TypeScript aponta como erro:
{
"compilerOptions": {
"module": "nodenext",
"target": "esnext",
"strict": true,
"noEmit": true,
"skipLibCheck": true,
"allowImportingTsExtensions": true,
"erasableSyntaxOnly": true,
"verbatimModuleSyntax": true
}
}
Este script list-templates.ts lista seus Templates.
Ele usa Signature Authentication, e a função auxiliar signParams de
@transloadit/utils cuida da assinatura:
import { signParams } from '@transloadit/utils'
import createClient from 'openapi-fetch'
import type { paths } from './transloadit-api.d.ts'
const { TRANSLOADIT_KEY: key, TRANSLOADIT_SECRET: secret } = process.env
if (!key || !secret) throw new Error('Set TRANSLOADIT_KEY and TRANSLOADIT_SECRET')
const client = createClient<paths>({ baseUrl: 'https://api2.transloadit.com' })
const expires = new Date(Date.now() + 5 * 60_000).toISOString()
const params = JSON.stringify({ auth: { key, expires }, pagesize: 3 })
const signature = await signParams(params, secret)
const { data, error } = await client.GET('/templates', {
params: { query: { params, signature } },
})
if (error) throw new Error(`${error.error}: ${error.message}`)
console.log(`${data.count} Templates, showing ${data.items.length}:`)
for (const template of data.items) console.log(`- ${template.id} ${template.name}`)
npx tsc -p . verifica os tipos do script. O Node.js 22.18 e versões posteriores
podem executar o arquivo TypeScript diretamente:
$ TRANSLOADIT_KEY=MY_AUTH_KEY TRANSLOADIT_SECRET=MY_SECRET_KEY node list-templates.ts
1726 Templates, showing 3:
- 1329f8… image-enhancer-v6
- d253c5… webm-to-mp4-v6
- e751d2… convert-an-image-from-avif-to-jpg-v6
Os tipos vêm da especificação, então tsc impede que um caminho digitado
incorretamente, como '/templats', ou um campo como
template.nmae passe pela verificação antes do envio da requisição. Após a
verificação de if (error), sabe-se que data é
a resposta de sucesso.
Como publicamos a especificação no padrão OpenAPI 3.1, você pode usar um gerador para sua própria
linguagem. Postman, Insomnia e ferramentas semelhantes importam o documento pela URL. Para conferir,
passamos a especificação pelo conversor openapi-to-postmanv2 do Postman. Ele produziu uma
coleção com todas as 43 requisições em 12 pastas. Em um cliente de API, os tokens bearer são a maneira
mais simples de se autenticar: obtenha um em
POST /token e envie-o como Authorization: Bearer ….
Webhooks tipados e eventos de status em tempo real
Enviamos cada Assembly Notification para notify_url como dois campos de formulário.
transloadit contém o Assembly Status em JSON. signature é
um HMAC-SHA1 dessa string exata, representado em hexadecimal com letras minúsculas e gerado com seu
Auth Secret. O esquema do payload está na especificação como assemblyNotificationPayload e também
é publicado como um JSON Schema independente. Depois de
verificar a assinatura, você pode validar o payload com esse esquema
e obter um resultado tipado:
import { Ajv } from 'ajv'
import type { components } from './transloadit-api.d.ts'
type AssemblyNotification = components['schemas']['assemblyNotificationPayload']
const url = 'https://transloadit.com/api-reference/schemas/webhooks/verified-json-payload.json'
const response = await fetch(url)
if (!response.ok) throw new Error(`GET ${url} failed with HTTP ${response.status}`)
const validate = new Ajv({ strict: false }).compile<AssemblyNotification>(await response.json())
// Call this only after verifying `signature` over the raw `transloadit` field
export function parseNotification(transloadit: string): AssemblyNotification {
const payload: unknown = JSON.parse(transloadit)
if (!validate(payload)) throw new Error(`Unexpected payload: ${validate.errors?.[0]?.message}`)
return payload
}
Testamos isso com uma Assembly real que usou
🤖 /http/import e 🤖 /image/resize,
ambos os Robots. Seu status final passou na validação. O TypeScript
então refinou seu tipo com base em ok === 'ASSEMBLY_COMPLETED', o que nos deu acesso a
results.resized. Um payload com um valor inventado para ok
foi rejeitado com must be equal to one of the allowed values.
Para acompanhar o progresso em tempo real, cada Assembly Status inclui um
update_stream_url. Envie uma requisição GET com
Accept: text/event-stream para essa URL e você receberá Server-Sent Events enquanto a Assembly
é executada: assembly_upload_finished, assembly_result_finished, assembly_execution_progress,
assembly_error e uma mensagem assembly_finished de encerramento. A
referência do fluxo documenta cada evento e inclui um link para o
JSON Schema de cada payload de evento.
Todas as páginas em Markdown e llms.txt para agentes
Agentes de programação com IA escrevem integrações melhores quando leem Markdown limpo em vez de
extrair conteúdo de HTML. Cada página pública de transloadit.com agora tem uma versão em Markdown.
Para obtê-la, substitua a barra final por .md: assim,
/docs/api/webhooks/ se torna /docs/api/webhooks.md. Você também pode enviar
Accept: text/markdown para a URL normal. As respostas HTML indicam a versão em Markdown
em um cabeçalho Link com rel="alternate", permitindo que
ferramentas que leem cabeçalhos de resposta a descubram.
$ curl -fsSL https://transloadit.com/docs/robots/image-resize.md
# Convert, resize, or watermark images
Robot: `/image/resize`
🤖/image/resize resizes, crops, changes colorization, rotation, and applies text and watermarks to images.
Stage: ga
…
Para facilitar a descoberta, /llms.txt é um índice
compacto. Ele inclui links para nossas páginas iniciais, a documentação em Markdown de cada Robot
e índices específicos para documentação, API, Robots, SDKs e FAQ. Também inclui links para índices
por tema: vídeo, imagens, áudio, documentos, upload, armazenamento e solução de problemas. Além
disso, direciona os agentes para a especificação:
$ curl -fsSL https://transloadit.com/llms.txt | grep -E 'OpenAPI|API endpoints'
- [Agent integration options](https://transloadit.com/mcp/): Upload, import, process, export, or retrieve files through MCP, OpenAPI, or an SDK.
- [API endpoints](https://transloadit.com/docs/api/llms.txt): Learn how you can leverage Transloadit’s file processing services most effectively
- [OpenAPI document](https://transloadit.com/openapi.json): Typed REST schema for generated clients and tools.
Continuamos publicando /llms-full.txt, um único arquivo de cerca de 1,5 MB. Os agentes
geralmente se saem melhor quando começam por llms.txt e buscam apenas as páginas
necessárias. Escrevemos mais sobre essa abordagem no artigo
Tornar APIs e documentação mais acessíveis a ferramentas de IA. Se
você quer que seu agente faça upload e processe arquivos por conta própria em vez de escrever código,
use o Transloadit MCP Server (English) ou nossas
habilidades para agentes. Nosso
guia de agentes de IA ajuda você a escolher entre essas opções.
O que ter em mente
- Com Signature Authentication,
paramsé uma string JSON assinada. O TypeScript verifica a requisição e a resposta, mas não verifica o que você coloca emparams. A API valida esse conteúdo quando você envia a requisição. POST /assembliesrecebemultipart/form-data. Achamos mais simples enviar um corpoFormDatacomfetchdiretamente e usar os tipos gerados para a resposta.- O OpenAPI 3.1 não consegue tipar os eventos individuais de um fluxo. Por isso, o fluxo de status
está documentado em sua página de referência e nos esquemas de eventos, em vez de aparecer como
um caminho normal em
openapi.json. - Para uploads no navegador e em dispositivos móveis, nossos SDKs continuam sendo o caminho mais curto. Eles acrescentam uploads retomáveis, novas tentativas e acompanhamento do progresso usando a mesma API.
Importe https://api2.transloadit.com/openapi.json no seu gerador ou cliente de API, explore a
referência da API e crie uma conta gratuita
para testar com sua própria Auth Key. Se um gerador encontrar algum problema no documento,
avise-nos.