Pular para o conteúdo
Entrar Lista de espera

Criar mídia

POST /v1/media escopo write

Começa o envio de uma mídia (vídeo, capa ou imagem: a foto de um post de imagem, só JPEG). Com simple: true e até 50 MB, envie o arquivo todo de uma vez em PUT /v1/media/:id/content; senão, envie em partes e conclua com POST /v1/media/:id/complete.

CabeçalhosAuthorization: Bearer praeko_… e X-Praeko-Contract: en. Sempre envie os dois.

Alias antigo em português (continua respondendo, marcado como obsoleto): /v1/midia.

Parâmetros

Nome Onde Descrição
Idempotency-Key cabeçalho Chave de idempotência (1 a 255 caracteres visíveis, por exemplo um UUID). Repetir o MESMO pedido com a mesma chave, em até 24 h, devolve a resposta guardada (com Idempotent-Replayed: true) sem executar de novo; outro pedido com a mesma chave dá 422 idempotency_key_reuse; um pedido ainda em andamento dá 409 idempotency_in_progress. Erros 5xx não são guardados. A chave vale por workspace e por rota. Veja Repetir uma requisição.

Corpo da requisição

JSON. Campos obrigatórios precisam ir; os outros podem ser omitidos.

Campo Tipo Descrição
type obrigatório texto Tipo da mídia: video, cover (capa) ou image (a foto de um post de imagem). Valores: video, cover, image.
name obrigatório texto Nome do arquivo (guardado com os caracteres seguros). 1 a 200 caracteres.
mime obrigatório texto Tipo do arquivo. Vídeo: video/mp4 ou video/quicktime. Capa: image/png ou image/jpeg. Imagem: só image/jpeg (o Studio exporta JPEG sRGB; o servidor não converte). Valores: video/mp4, video/quicktime, image/png, image/jpeg.
size obrigatório inteiro Tamanho em bytes. Vídeo até 5 GiB; capa e imagem até 20 MiB (o Instagram aceita foto de até 8 MB: isso é conferido ao criar o post). De 1 a 5368709120.
simple (opcional) verdadeiro/falso true envia o arquivo todo em um PUT /v1/media/:id/content (só até 50 MB). Sem ele, o envio é em partes. Padrão: false.
sha256 (opcional) texto Hash SHA-256 do arquivo, se quiser guardá-lo.
Exemplo de corpo
{
  "type": "video",
  "name": "dia-06-o-teste-que-falhava.mp4",
  "mime": "video/mp4",
  "size": 48230114,
  "simple": true
}

Exemplo

curl -X POST "https://praeko.app/v1/media" \
  -H "Authorization: Bearer $PRAEKO_KEY" \
  -H "X-Praeko-Contract: en" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "video",
  "name": "dia-06-o-teste-que-falhava.mp4",
  "mime": "video/mp4",
  "size": 48230114,
  "simple": true
}'

Resposta

Status de sucesso Quando
200 Sucesso.
Resposta 200
{
  "id": "01KA3VQ7M2T9XE4HB8N5RZ6C0D",
  "state": "uploading",
  "uploadHint": "PUT /v1/media/01KA3VQ7M2T9XE4HB8N5RZ6C0D/content"
}

Com simple: true a resposta é só id, state e uploadHint. Sem ele (envio em partes) vêm também minPartSize (5242880), maxPartSize (99614720) e suggestedPartSize (16777216), em bytes, e o uploadHint aponta para PUT /v1/media/:id/parts/<n>.

Erros

Status code Quando
400 empty_body O corpo veio vazio.
400 invalid_json O corpo não é um objeto JSON.
413 body_too_large O corpo passa de 1 MB.
422 invalid_field type, mime, name ou size inválidos.
422 file_too_large simple: true com mais de 50 MB.
422 invalid_image Mídia image cujo arquivo não é um JPEG (a conferência acontece no envio; no envio em partes, ao completar).
422 idempotency_key_reuse A Idempotency-Key já foi usada com outro pedido (método, caminho, query ou corpo diferentes).
409 idempotency_in_progress Um pedido com a mesma Idempotency-Key ainda está em andamento (repita em instantes).
409 idempotency_response_too_large A resposta original passou de 256 KB e não foi guardada; consulte o recurso por GET.

Erros de qualquer rota

Status code Quando
401 unauthorized Faltou o cabeçalho Authorization: Bearer ….
401 invalid_api_key A chave não existe.
401 revoked_api_key A chave foi revogada.
401 expired_api_key A chave expirou.
403 forbidden O escopo da chave não basta para esta rota (veja o selo de escopo).
429 rate_limited Passou do limite de requisições por minuto.

O corpo de todo erro é { "error": { "code", "message", "details"? } }. Veja todos os códigos.

Testar

Testar

O teste ao vivo usa a sua chave e a sua conta. Para quem não entrou, fica desligado.

Entre para testar
Dúvida ou erro nesta página? contato@praeko.appVer .md

Digite para buscar páginas, rotas e códigos de erro.