Skip to main content
POST
Obtenha URLs PUT assinadas para um envio de imagem de referência que lhe pertence. Uma imagem de 8 MiB tem no máximo duas partes. Salve o ETag retornado por cada PUT para upload_complete.

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: images: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 uploadId retornado pela ação upload_initialize deste domínio.Formato: “uuid”. Padrão: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$.
array
obrigatório
Lista de valores. Consulte o esquema de entrada completo para ver a estrutura dos itens.Mínimo de itens: 1. Máximo de itens: 2.
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. Um array de URLs PUT assinadas temporárias, uma por número distinto de parte solicitado. A resposta não contém bytes de imagem, ETags ou campos de tamanho por parte.

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 images:write; nenhum escopo adicional de upload é necessário.
  • uploadId é o UUID de initialize. partNumbers contém 1–2 inteiros, cada um entre 1 e 2, e cada parte deve existir para o fileSize declarado da sessão. Números de partes solicitados em duplicidade são reduzidos a uma URL.
  • Envie os bytes binários brutos de cada parte por PUT para cada URL retornada. Content-Length é assinado e deve corresponder exatamente a min(partSize, fileSize - (partNumber - 1) × partSize). No exemplo de 7 MiB, a parte 1 tem 5,242,880 bytes e a parte 2 tem 2,097,152 bytes. Não envie JSON, multipart/form-data nem base64 para a URL assinada.
  • Salve o cabeçalho de resposta ETag de cada PUT bem-sucedido e envie esses valores para images_upload_complete. Trate as URLs assinadas como permissões privadas e temporárias de upload.
  • Somente um envio pertencente ao usuário conectado pode ser assinado, concluído ou abortado. Esses aliases aceitam apenas sessões JPG, PNG e WebP de no máximo 8 MiB, mesmo que a sessão tenha sido criada por outra família de envio.
  • 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.
  • 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.
  • Para obter URLs novas após a expiração de uma hora enquanto a sessão ainda estiver ativa, chame sign-parts com um novo requestId. Tentar novamente com o mesmo requestId retorna o resultado salvo, incluindo as URLs antigas.

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