Stagify API

Introdução

A API expõe uma única coisa: o pipeline de decoração por trás do aplicativo web. Você envia a foto de um cômodo, informa um tipo de ambiente e um estilo de mobiliário, e recebe a imagem decorada na mesma resposta. Não há fila de tarefas nem nada a consultar no caminho normal.

Créditos são imagens inteiras. Você os compra antecipadamente e cada renderização bem-sucedida gasta um. Uma renderização que falha é reembolsada automaticamente, então você só paga por uma foto que recebeu. E como o saldo é pré-pago, uma chave roubada custa no máximo o que restar nela. Não há fatura no fim do mês.

As chaves são para uso servidor a servidor. A API não envia cabeçalhos CORS, portanto um navegador não pode chamá-la diretamente; isso é proposital, e uma chave acessível pelo JavaScript do navegador é uma chave vazada. Mostramos a chave uma única vez, guardamos apenas um hash e revogamos imediatamente.

Início rápido

Crie uma chave na sua página de chaves de API, compre um pacote de créditos e envie uma foto. A resposta traz a imagem decorada como data URL.

curl https://stagify.ai/api/v1/renders \
  -H "Authorization: Bearer $STAGIFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "image=@living-room.jpg" \
  -F "roomType=Living room" \
  -F "furnitureStyle=modern" \
  -F "labelVirtuallyStaged=true"

Uma renderização pode levar alguns minutos. Defina o tempo limite de leitura do seu cliente para 300 segundos e tente novamente com a mesma Idempotency-Key. É isso que garante que você nunca será cobrado duas vezes pela mesma foto.

Pacotes de créditos

Parâmetros da requisição

POST /api/v1/renders, enviado como multipart/form-data. Todos os valores aceitos abaixo também são servidos em JSON por GET /api/v1/options, que não exige chave de API, para que um cliente possa preencher seus próprios menus em vez de fixar esta tabela no código.

Idempotência

Uma renderização mantém a conexão aberta por minutos, o que significa que a falha que realmente vai te atingir é um socket caído depois de o trabalho terminar: cobrado e sem nada em mãos. Envie um cabeçalho Idempotency-Key em cada requisição e tente novamente com o mesmo valor.

Omitir o cabeçalho é permitido e significa nenhuma proteção contra repetição, que é o padrão honesto. Não derivamos uma chave a partir da sua foto: duas renderizações genuinamente distintas do mesmo cômodo colidiriam e quem chamasse em segundo receberia a imagem do primeiro.

Avisos de decoração virtual

Muitas regras da MLS e da NAR exigem que uma foto decorada virtualmente informe isso. labelVirtuallyStaged grava esse aviso nos pixels em vez de anexá-lo como metadado que uma ferramenta seguinte pode remover.

Se o aviso não puder ser aplicado, a imagem é retida em vez de entregue sem rótulo, a chamada responde 500 DISCLOSURE_STAMP_FAILED e seu crédito é reembolsado. Não há como desligar esse comportamento, nem um padrão por chave que o desative silenciosamente.

Erros

Toda falha responde { "error": "…", "code": "…" }. Ramifique pelo code, nunca pela mensagem. Mensagens mudam, códigos não.

Outros endpoints

• GET /api/v1/options: os valores aceitos de cada enumeração acima. Não exige chave de API.
• GET /api/v1/me: minha chave está funcionando? Devolve a conta e o saldo.
• GET /api/v1/credits: saldo e totais acumulados.
• GET /api/v1/renders/{id}: o status de uma renderização.

Cada resposta traz X-Stagify-Credits-Remaining, para você ver o saldo cair sem precisar consultá-lo.