Ideal House
Pular para o conteúdo

Documentação da Virtual Staging API#

URL Base: https://api.ideal.house
Versão: v1
Atualizado: 2026-04-13


📖 Visão Geral#

A Virtual Staging API permite redesenhar um ambiente vazio ou parcialmente mobiliado usando IA.
Você envia uma imagem do ambiente URL e um prompt de texto opcional, depois recupera o resultado gerado de forma assíncrona.

  1. Criar uma tarefa — Envie imageUrl e, opcionalmente, prompt, depois receba um taskId.
  2. Consultar resultados — Use taskId para verificar o status da tarefa e obter a imagem de saída.

🔐 Autenticação#

Todas as requisições de API devem ser autenticadas usando uma Chave API.

Inclua sua Chave API no cabeçalho da requisição:

CabeçalhoValor
APIKEYyour_api_key_here

⚠️ Mantenha sua Chave API segura. Não a exponha em código do lado do cliente ou repositórios públicos.


💰 Dedução de Créditos#

[!WARNING] 🪙 1 crédito é deduzido quando uma tarefa é criada com sucesso.
Se a tarefa finalmente falhar, o crédito deduzido será estornado automaticamente.
Créditos insuficientes retornarão o código de erro 9051. 📄 Consulte a Referência de Dedução de Créditos.

OperaçãoCréditos Deduzidos
Tarefa de Virtual Staging1 crédito

📌 Endpoints da API#


1. Criar Tarefa de Virtual Staging#

Cria uma nova tarefa de virtual staging e retorna um taskId único para consulta.

Endpointo

Texto simples
POST /api/v1/virtualStaging/generate

Cabeçalhos da Requisição

CabeçalhoObrigatórioDescrição
APIKEY✅ SimSua chave de autenticação API
Content-Type✅ Simapplication/json

Corpo da Requisição

CampoTipoObrigatórioDescrição
imageUrlstring✅ SimURL da imagem do ambiente fonte
promptstring❌ NãoPrompt opcional para orientar estilo e mobília
indoorTypeIdstring❌ NãoPredefinição opcional de tipo de ambiente. Veja Opções de Tipo Indoor
indoorStyleIdstring❌ NãoPredefinição opcional de estilo de interiores. Veja Opções de Estilo Indoor
indoorElemIdstring❌ NãoPredefinição opcional de elementos do ambiente. Suporta múltiplos IDs unidos por vírgula, por exemplo id1,id2

🖼️ Requisitos de imagem: Use JPG/JPEG, PNG ou WebP. Cada imagem deve ter no máximo 20 MB, com dimensões de 128 × 128 px até 6,000 × 6,000 px (inclusivo). Imagens que excedam as dimensões máximas em pixels são automaticamente reduzidas proporcionalmente para caber dentro de 6,000 × 6,000 px antes do processamento. A URL da imagem deve ser diretamente acessível pelo servidor da API.


🎨 Opções de Estilo#

indoorTypeId, indoorStyleId e indoorElemId podem ser selecionados no endpoint Configuração de Estilo da API.

Uso:

Texto simples
GET /api/v1/style/virtual_staging/getStyles
Grupo de EstiloCampo na RequisiçãoDescrição
roomTypeindoorTypeIdOpção de tipo de ambiente
styleindoorStyleIdOpção de estilo de interiores
elementsindoorElemIdOpção de elemento do ambiente. Suporta múltiplos IDs de opção unidos por vírgula, por exemplo id1,id2

Cada opção contém name, id e url. Passe o id da opção no campo correspondente da requisição.


📥 Exemplos de Requisição#

cURL
bash
curl -X POST "https://api.ideal.house/api/v1/virtualStaging/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/empty-living-room.jpg",
    "prompt": "Warm and modern living room styling",
    "indoorTypeId": "Interior Design_Interior Scene_Living Room",
    "indoorStyleId": "Interior_Interior Style_Popular_Vs_Modern Farmhouse",
    "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
  }'
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class VirtualStagingApiExample {

    private static final String BASE_URL = "https://api.ideal.house";
    private static final String API_KEY = "your_api_key_here";

    public static void main(String[] args) throws IOException {
        OkHttpClient client = new OkHttpClient();

        String requestBody = """
                {
                    "imageUrl": "https://example.com/empty-bedroom.jpg",
                    "prompt": "Cozy contemporary bedroom",
                    "indoorTypeId": "Interior Design_Interior Scene_Bed Room",
                    "indoorStyleId": "Interior_Interior Style_Popular_Vs_Contemporary Warm",
                    "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
                }
                """;

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/virtualStaging/generate")
                .addHeader("APIKEY", API_KEY)
                .addHeader("Content-Type", "application/json")
                .post(RequestBody.create(requestBody, MediaType.parse("application/json")))
                .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println("Response: " + response.body().string());
        }
    }
}
Python (requests)
python
import requests

BASE_URL = "https://api.ideal.house"
API_KEY  = "your_api_key_here"

headers = {
    "APIKEY": API_KEY,
    "Content-Type": "application/json"
}

payload = {
    "imageUrl": "https://example.com/empty-home-office.jpg",
    "prompt": "Minimal modern home office",
    "indoorTypeId": "Interior Design_Interior Scene_Home Office",
    "indoorStyleId": "Interior_Interior Style_Popular_Vs_Modern Minimal",
    "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
}

response = requests.post(
    f"{BASE_URL}/api/v1/virtualStaging/generate",
    headers=headers,
    json=payload
)

data = response.json()
task_id = data.get("data")
print(f"Task ID: {task_id}")
Node.js (axios)
javascript
const axios = require('axios');

const BASE_URL = 'https://api.ideal.house';
const API_KEY  = 'your_api_key_here';

async function createVirtualStagingTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/virtualStaging/generate`,
      {
        imageUrl: 'https://example.com/empty-dining-room.jpg',
        prompt: 'Modern luxury dining room',
        indoorTypeId: 'Interior Design_Interior Scene_Dining Room',
        indoorStyleId: 'Interior_Interior Style_Popular_Vs_Modern Luxury',
        indoorElemId: 'Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table'
      },
      {
        headers: {
          'APIKEY': API_KEY,
          'Content-Type': 'application/json'
        }
      }
    );

    const taskId = response.data.data;
    console.log('Task ID:', taskId);
    return taskId;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

createVirtualStagingTask();

📤 Resposta#

Resposta de Sucesso

json
{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}
CampoTipoDescrição
codeinteger0 indica sucesso
messagestringMensagem de resposta
datalongO ID único da tarefa para consulta de resultados

2. Obter Resultado da Tarefa#

Recupera o status atual e a saída de uma tarefa de virtual staging criada anteriormente.

Endpointo

Texto simples
GET /api/v1/virtualStaging/result

Cabeçalhos da Requisição

CabeçalhoObrigatórioDescrição
APIKEY✅ SimSua chave de autenticação API

Parâmetros de Consulta

ParâmetroTipoObrigatórioDescrição
taskIdlong✅ SimO ID da tarefa retornado pelo endpoint de criação

📥 Exemplos de Requisição#

cURL
bash
curl -X GET "https://api.ideal.house/api/v1/virtualStaging/result?taskId=1234567890123456789" \
  -H "APIKEY: your_api_key_here"
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class VirtualStagingResultExample {

    private static final String BASE_URL = "https://api.ideal.house";
    private static final String API_KEY = "your_api_key_here";

    public static void main(String[] args) throws IOException {
        OkHttpClient client = new OkHttpClient();
        long taskId = 1234567890123456789L;

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/virtualStaging/result?taskId=" + taskId)
                .addHeader("APIKEY", API_KEY)
                .get()
                .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println("Response: " + response.body().string());
        }
    }
}
Python (requests)
python
import requests
import time

BASE_URL = "https://api.ideal.house"
API_KEY  = "your_api_key_here"

headers = {
    "APIKEY": API_KEY
}

task_id = 1234567890123456789

while True:
    response = requests.get(
        f"{BASE_URL}/api/v1/virtualStaging/result",
        headers=headers,
        params={"taskId": task_id}
    )

    data = response.json()
    result = data.get("data", {})
    status = result.get("status")

    print(f"Status: {status}, Progress: {result.get('percentage')}%, Queue: {result.get('waitNumber')}")

    if status in ("Success", "Failed"):
        break

    time.sleep(3)

if status == "Success":
    output = result["output"]
    print("Result URL:", output["resultUrl"])
    print("Size:", output["width"], "x", output["height"])
else:
    print("Task ended with status:", status)
Node.js (axios)
javascript
const axios = require('axios');

const BASE_URL = 'https://api.ideal.house';
const API_KEY  = 'your_api_key_here';

async function pollResult(taskId) {
  const headers = { 'APIKEY': API_KEY };

  while (true) {
    const response = await axios.get(
      `${BASE_URL}/api/v1/virtualStaging/result`,
      {
        headers,
        params: { taskId }
      }
    );

    const result = response.data.data;
    const { status, percentage, waitNumber } = result;

    console.log(`Status: ${status} | Progress: ${percentage}% | Queue: ${waitNumber}`);

    if (['Success', 'Failed'].includes(status)) {
      if (status === 'Success') {
        console.log('Result URL:', result.output.resultUrl);
        console.log('Size:', result.output.width, 'x', result.output.height);
      } else {
        console.log('Task ended with status:', status);
      }
      break;
    }

    await new Promise(resolve => setTimeout(resolve, 3000));
  }
}

pollResult(1234567890123456789n);

📤 Resposta#

Resposta de Sucesso (Tarefa Concluída)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/empty-room.jpg",
      "prompt": "modern country living room with warm neutral materials",
      "indoorTypeId": "Interior Design_Interior Scene_Living Room",
      "indoorStyleId": "Interior_Interior Style_Popular_Vs_Modern Farmhouse",
      "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/virtual_staging_result.jpg",
      "width": 1024,
      "height": 1024
    }
  }
}

Resposta (Tarefa em Processamento / Em Fila)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Processing",
    "waitNumber": 1,
    "percentage": 46,
    "input": {
      "imageUrl": "https://example.com/empty-room.jpg",
      "prompt": "coastal bedroom with soft light and natural textures",
      "indoorTypeId": "Interior Design_Interior Scene_Bed Room",
      "indoorStyleId": "Interior_Interior Style_Popular_Vs_Contemporary Warm"
    },
    "output": null
  }
}

Resposta (Tarefa Falhou)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Failed",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/empty-room.jpg",
      "prompt": "..."
    },
    "output": null
  }
}

Campos da Resposta

CampoTipoDescrição
idlongIdentificador único da tarefa
statusstringStatus atual da tarefa (veja Status da Tarefa)
waitNumberintegerNúmero de tarefas à frente na fila (0 significa em processamento atualmente)
percentageintegerPorcentagem de conclusão da tarefa (0-100)
errorReasonstringMotivo da falha quando status é Failed
inputobjectParâmetros de entrada originais enviados para esta tarefa
input.imageUrlstringURL da imagem do ambiente fonte
input.promptstringPrompt do usuário (se fornecido)
input.indoorTypeIdstringPredefinição de tipo de ambiente usada (se fornecida)
input.indoorStyleIdstringPredefinição de estilo de interiores usada (se fornecida)
input.indoorElemIdstringPredefinição de elemento do ambiente usada (se fornecida). Pode conter múltiplos IDs unidos por vírgula
outputobjectResultado da geração (disponível apenas quando status é Success)
output.resultUrlstringURL da imagem resultante do virtual staging gerado
output.widthintegerLargura da imagem de saída em pixels
output.heightintegerAltura da imagem de saída em pixels

📊 Status da Tarefa#

StatusSignificado
UnprocessedTarefa criada e aguardando na fila
ProcessingTarefa está sendo executada atualmente
SuccessTarefa concluída com sucesso
FailedTarefa falhou e nenhuma saída foi produzida

Consulte a cada 3-5 segundos. Consulte Limitação de Tarefas da API.


❌ Respostas de Erro#

Todas as respostas de erro compartilham a mesma estrutura JSON:

json
{
  "code": 5002,
  "message": "Invalid API Key",
  "data": null
}

Referência de Códigos de Erro#

CódigoNomeDescriçãoAção Sugerida
1001FAILEDFalha na requisição (erro genérico)Verifique o campo message para detalhes específicos
1003INTERNAL_ERRORErro interno do servidorTente novamente após um breve atraso; entre em contato com o suporte se persistir
1011PARAM_ERRORErro nos parâmetros da requisição (por exemplo, imageUrl ausente)Certifique-se de que imageUrl é fornecido e é um URL válido
5002API_KEY_INVALIDChave API inválida ou ausenteCertifique-se de que o cabeçalho APIKEY está presente e correto
9010SCAN_TEXT_ERRORFalha na moderação de conteúdo do promptRevise o prompt para remover conteúdo sensível ou proibido
9038PROHIBITED_CONTENTA imagem de saída gerada contém conteúdo proibidoAjuste o prompt/estilo/entrada e tente novamente
9051COINS_NOT_ENOUGHCréditos insuficientesAdicione créditos e tente novamente

📄 Para definições completas de erros comuns, consulte a Referência de Códigos de Erro.