Publicando nas redes
Como publicar clipes renderizados no TikTok, Instagram, YouTube e mais
Depois de renderizar um clipe, você pode publicá-lo em uma ou mais contas conectadas com POST /posts. Um único post pode levar vários clipes para várias contas de uma vez.
Antes de começar
Você precisa de duas coisas:
Um clipe renderizado
O edit_id vem do render: é ele que identifica o vídeo a publicar, e ele não expira nunca
Contas conectadas
O connection_id vem de GET /connections. Conecte novas contas pelo OAuth dentro de cut.pro: a API não conecta contas
Como o corpo é montado
Cada item de videos aponta um clipe (edit_id) para um ou mais destinos (targets). Cada destino combina uma conexão (connection_id) com a metadata daquela plataforma (título, privacidade, etc.).
curl -X POST https://api.cut.pro/api/v1/posts \
-H "X-Api-Key: $CUTPRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"videos": [
{
"edit_id": "7412908490112775",
"targets": [
{
"connection_id": "7399001244553012",
"metadata": {
"tiktok": {
"title": "Meu corte viral",
"privacyLevel": "PUBLIC_TO_EVERYONE"
}
}
},
{
"connection_id": "7399001244553099",
"metadata": {
"youtube": {
"title": "Meu corte viral",
"description": "Cortes do episódio de hoje",
"categoryId": "22",
"privacyStatus": "public"
}
}
}
]
}
]
}'{
"id": "7412909001223344",
"item_count": 2,
"scheduled_at": null,
"status": "pending"
}A metadata muda por plataforma (TikTok, YouTube, Instagram, Threads, Bluesky, LinkedIn, Pinterest, Facebook, X e car.media), e é a única parte da API que guarda os nomes de campo de cada rede (privacyLevel, categoryId, privacyStatus): eles seguem para a plataforma como estão. Os campos obrigatórios de cada uma estão na página do endpoint POST /posts, com o playground interativo.
Para agendar em vez de publicar agora, envie scheduled_at com uma data ISO 8601 no futuro.
Acompanhe a publicação
O post entra na fila e publica de forma assíncrona. Faça polling em GET /posts/{id}:
curl https://api.cut.pro/api/v1/posts/7412909001223344 \
-H "X-Api-Key: $CUTPRO_API_KEY"O status do post evolui assim:
| Status | Significado |
|---|---|
pending | Na fila, ainda não começou |
processing | Publicando nas contas |
completed | Todos os itens publicaram |
partial | Alguns publicaram, outros falharam |
failed | Nenhum item publicou |
O array items mostra o resultado por conta, que é o que importa quando o status é partial.
Quando algo falha
Itens falham de forma independente: um destino com erro não derruba os que já publicaram.
- Reenviar um item que falhou:
POST /posts/{id}/items/{itemId}/retry - Remover um item sem mexer nos demais:
DELETE /posts/{id}/items/{itemId} - Apagar o post inteiro:
DELETE /posts/{id} - Editar antes de publicar (por exemplo, ajustar o agendamento):
PATCH /posts/{id}
partial não é sucesso. Se o seu produto avisa "publicado" no partial, ele está mentindo para o usuário: leia items e mostre o que subiu e o que não subiu.
As recusas que acontecem antes de qualquer coisa ser criada:
code | Status | O que fazer |
|---|---|---|
INVALID_CONNECTIONS | 400 | extra.invalid_connections lista as conexões desconhecidas, revogadas ou que não publicam vídeo |
INVALID_METADATA | 400 | extra.field diz qual campo reprovou, como youtube.categoryId |
PLATFORM_UNAVAILABLE | 400 | Essa rede ainda não está aberta para publicação |
EDITS_NOT_FOUND | 404 | extra.invalid_edits lista os edit_id que não existem nesse workspace |
DAILY_LIMIT_EXCEEDED | 403 | A conta bateu o teto diário da plataforma. O extra traz daily_limit, used_today e quantos itens este pedido somaria |
DUPLICATE_POST | 409 | O mesmo clipe já está indo para a mesma conta |
O arquivo some, o edit fica
Cada item traz um render_id, e ele vira null quando o arquivo renderizado é apagado pela retenção do seu plano. O post continua lá, com o published_url e a metadata exata que foi publicada. Para ter o MP4 de volta, chame POST /renders com o edit_id do item (veja Receitas).