Skip to main content
POST
Prepare o envio de uma referência JPG, PNG ou WebP de até 8 MiB. Use thumbnails_upload_sign_parts para obter as URLs PUT, envie os bytes e chame thumbnails_upload_complete; use o fileKey retornado na geração.

Autenticação e permissões

string
obrigatório
Envie uma chave de API VoiceCheap neste cabeçalho. Authorization: Bearer com a mesma chave de API também é aceito. Tokens de acesso OAuth são aceitos apenas pelo MCP, não por este endpoint REST.
Permissões necessárias: thumbnails:write. É necessária uma assinatura paga ativa. As permissões não alteram funções na equipe, propriedade dos recursos, créditos de mídia ou limites do plano.

Parâmetros

string
Opcional na camada de transporte: o servidor insere um identificador antes da validação quando ele é omitido. Forneça seu próprio UUID v4 estável para recuperar com segurança uma resposta perdida.Formato: “uuid”. Padrão: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$.
string
obrigatório
O nome do arquivo da imagem, com uma extensão correspondente a contentType.Comprimento mínimo: 1. Comprimento máximo: 250. Padrão: \.(?:jpe?g|png|webp)$.
string
obrigatório
Valor de texto.Valores aceitos: “image/jpeg”, “image/png”, “image/webp”.
integer
obrigatório
Tamanho exato do arquivo em bytes, até 8 MiB.Mínimo: 1. Máximo: 8388608.
O JSON Schema abaixo preserva os nomes exatos dos campos, tipos aninhados, valores padrão, limites e valores aceitos expostos pela descoberta. Regras adicionais entre campos são listadas nas notas da operação.

Idempotência

Use um UUID v4 em requestId ou no cabeçalho HTTP Idempotency-Key para cada alteração. Reutilize o mesmo identificador e argumentos idênticos após uma falha de rede. Se ambos forem fornecidos, devem ser iguais. Repetir uma requisição salva não repete a operação nem consome outra chamada mensal. Requisições com falha ou interrompidas não são reiniciadas automaticamente. Qualquer alteração pode retornar HTTP 202 quando uma nova tentativa encontra a mesma requisição ainda em execução, mesmo que a primeira execução normalmente seja síncrona. Se a execução foi concluída, mas resultStored é false, uma nova tentativa retorna HTTP 200 com o estado salvo da requisição em vez do resultado original. Recupere a saída pela ação de histórico, resultado ou download do domínio correspondente.

Exemplos de requisição

Substitua os identificadores de recursos e as chaves de mídia dos exemplos pelos valores retornados para sua conta. Mantenha o identificador da requisição ao tentar novamente a mesma alteração.

Resposta

Uma primeira execução bem-sucedida retorna HTTP 200 com o resultado da operação em data. Uma repetição pode retornar o estado salvo da requisição. O exemplo mostra uma resposta aceita, não todos os campos opcionais. Uma nova sessão de upload de referência de imagem em várias partes, a futura chave do objeto, o tamanho da parte em bytes e o número máximo de uploads paralelos. Isso não envia bytes de imagem nem torna key pronta para geração.

Campos do resultado

Recuperar e consultar esta requisição

Use o mesmo identificador mesmo após perder a conexão. Se resultStored for false, recupere a saída pela ação correspondente de histórico, resultado ou download. Nunca inicie uma segunda geração apenas para verificar o progresso.
HTTP 200

Notas da operação

  • Requer thumbnails:write; nenhum escopo adicional de envio é necessário.
  • Os espaços nas extremidades de filename são removidos; ele deve conter 1–250 caracteres e terminar em .jpg, .jpeg, .png ou .webp. Sua extensão deve corresponder a contentType: image/jpeg, image/png ou image/webp. fileSize é o número inteiro exato de bytes, de 1 a 8,388,608.
  • A implementação compartilhada de upload retorna partSize de 5 MiB (5,242,880 bytes) para essas referências. Um arquivo de até 5 MiB usa uma parte; um arquivo maior, de até 8 MiB, usa duas. Solicite URLs PUT com thumbnails_upload_sign_parts, envie os bytes e chame thumbnails_upload_complete.
  • Use o fileKey retornado pela conclusão como uma entrada de referenceImageKeys em thumbnails_generate. O resultado da inicialização usa key, não fileKey. Não passe key para a geração antes da conclusão.
  • A sessão de upload de produção expira após 24 horas. As URLs assinadas das partes expiram após uma hora. A conclusão e o aborto removem a sessão ativa; sign-parts e complete passam então a retornar Upload not found. Nenhuma das respostas inclui um campo expiresAt.
  • Esta ação usa as criações e os envios do próprio usuário conectado, inclusive quando a credencial está conectada em um contexto de equipe.
  • Use um requestId UUID v4 ou o cabeçalho HTTP Idempotency-Key e reutilize-o com entradas idênticas ao tentar novamente. A camada de integração registra cada alteração e retorna seu estado ou resultado registrado sem executá-la novamente. Uma requisição com falha ou interrompida não é repetida automaticamente.
  • O nome do arquivo na chave do objeto é sanitizado e pode ser encurtado. Mantenha a chave e o uploadId exatos retornados; não os construa por conta própria. Os bytes da imagem são validados durante a geração, além do tamanho e do tipo declarados durante o upload.

Uso

Cada chamada bem-sucedida consome uma chamada mensal da API/MCP. Os créditos de mídia e as cotas de geração da própria operação também se aplicam.

Erros