Ideal House
Pular para o conteúdo

Documentação da API de experimentação virtual de móveis#

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


📖 Visão geral#

A API de experimentação virtual de móveis permite colocar virtualmente itens de mobiliário em uma cena de ambiente usando IA. Você fornece uma imagem do cômodo e uma lista de itens de mobiliário (cada um com uma imagem e um ID do produto), e a IA compõe o mobiliário perfeitamente na cena. O fluxo de trabalho é assíncrono e envolve duas etapas:

  1. Criar uma tarefa — Envie sua imagem do cômodo e a lista de mobiliário, e você receberá um taskId.
  2. Consultar resultados — Use o taskId para consultar o status da tarefa e recuperar a imagem gerada.

📌 Observação: Atualmente, apenas o modo creative é suportado.


🔐 Autenticação#

Todas as requisições da 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 em repositórios públicos.


💰 Dedução de créditos#

[!WARNING] 🪙 Os créditos são deduzidos com base no modelType selecionado após a criação bem-sucedida da tarefa. Se a tarefa finalmente falhar, os créditos deduzidos serão automaticamente reembolsados na sua conta.
Créditos insuficientes retornarão o código de erro 9051. 📄 Consulte Referência de Dedução de Créditos.

Modelo (modelType)Créditos Deduzidos
Base3 créditos
Pro10 créditos

📌 Endpoints da API#


1. Criar Tarefa de Prova de Móveis#

Cria uma nova tarefa de IA para prova de móveis e retorna um taskId único para consulta.

Endpoint

Texto simples
POST /api/v1/furnitureTryOn/generate

Cabeçalhos da Requisição

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

Corpo da Requisição

CampoTipoObrigatórioDescrição
imageUrlstring✅ SimURL da imagem da cena do cômodo na qual o mobiliário será inserido
furnitureListarray✅ SimLista de itens de mobiliário a serem inseridos na cena. Máximo de 6 itens. Consulte Objeto de Item de Móvel
promptstring❌ OpcionalPrompt de texto personalizado para orientar adicionalmente a inserção e o estilo
modelTypestring❌ OpcionalTipo de qualidade do modelo. Enum: Base, Pro. Padrão: Base

🛋️ Objeto de Item de Móvel#

Cada item em furnitureList deve ser um objeto com os seguintes campos:

CampoTipoObrigatórioDescrição
imageUrlstring✅ SimURL da imagem do produto de mobiliário (recomenda-se fundo transparente ou limpo)

⚠️ furnitureList pode conter no máximo 6 itens.

🖼️ Requisitos de imagem: A imagem do cômodo e cada imagem de mobiliário devem usar JPG/JPEG, PNG ou WebP. Cada imagem não deve exceder 20 MB, com dimensões de 128 × 128 px a 6,000 × 6,000 px (inclusivo). Imagens que excedem as dimensões máximas em pixels são automaticamente redimensionadas proporcionalmente para caber dentro de 6,000 × 6,000 px antes do processamento. Os URLs das imagens devem ser diretamente acessíveis pelo servidor da API.

Exemplo

json
"furnitureList": [
  {
    "imageUrl": "https://example.com/sofa.png"
  },
  {
    "imageUrl": "https://example.com/table.png"
  }
]

Tipos de Modelo

ValorDescrição
BasePadrão. Equilíbrio entre velocidade e qualidade
ProSaída de maior qualidade, processamento mais lento

📥 Exemplos de Requisição#

cURL
bash
# Basic request (Base model)
curl -X POST "https://api.ideal.house/api/v1/furnitureTryOn/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/living-room.jpg",
    "furnitureList": [
      {
        "imageUrl": "https://example.com/sofa.png"
      },
      {
        "imageUrl": "https://example.com/coffee-table.png"
      }
    ],
    "prompt": "modern minimalist style"
  }'

# Pro model
curl -X POST "https://api.ideal.house/api/v1/furnitureTryOn/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/living-room.jpg",
    "furnitureList": [
      {
        "imageUrl": "https://example.com/sofa.png"
      }
    ],
    "prompt": "Scandinavian interior with warm lighting",
    "modelType": "Pro"
  }'
Java (OkHttp)
java
import okhttp3.*;
import java.io.IOException;

public class FurnitureTryOnApiExample {

    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/living-room.jpg",
                "furnitureList": [
                    {
                        "imageUrl": "https://example.com/sofa.png"
                    },
                    {
                        "imageUrl": "https://example.com/coffee-table.png"
                    }
                ],
                "prompt": "modern minimalist style",
                "modelType": "Base"
            }
            """;

        Request request = new Request.Builder()
            .url(BASE_URL + "/api/v1/furnitureTryOn/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/living-room.jpg",
    "furnitureList": [
        {
            "imageUrl": "https://example.com/sofa.png"
        },
        {
            "imageUrl": "https://example.com/coffee-table.png"
        }
    ],
    "prompt": "modern minimalist style",
    "modelType": "Base"
}

# Pro model example:
# payload = {
#     "imageUrl": "https://example.com/living-room.jpg",
#     "furnitureList": [
#         {
#             "imageUrl": "https://example.com/sofa.png"
#         }
#     ],
#     "prompt": "Scandinavian interior with warm lighting",
#     "modelType": "Pro"
# }

response = requests.post(
    f"{BASE_URL}/api/v1/furnitureTryOn/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 createFurnitureTryOnTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/furnitureTryOn/generate`,
      {
        imageUrl: 'https://example.com/living-room.jpg',
        furnitureList: [
          {
            imageUrl: 'https://example.com/sofa.png'
          },
          {
            imageUrl: 'https://example.com/coffee-table.png'
          }
        ],
        prompt: 'modern minimalist style',
        modelType: 'Base'

        // Pro model:
        // modelType: 'Pro'
      },
      {
        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);
  }
}

createFurnitureTryOnTask();

📤 Resposta#

Resposta de Sucesso

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

2. Obter Resultado da Tarefa#

Recupera o status atual e a saída de uma tarefa de prova de móveis criada anteriormente.

Endpoint

Texto simples
GET /api/v1/furnitureTryOn/result

Cabeçalhos da Requisição

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

Parâmetros de Consulta

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

📥 Exemplos de Requisição#

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

public class FurnitureTryOnResultExample {

    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/furnitureTryOn/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

# Poll until task is complete
while True:
    response = requests.get(
        f"{BASE_URL}/api/v1/furnitureTryOn/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)  # Poll every 3 seconds

if status == "Success":
    output = result["output"]
    print("Result URL:", output["resultUrl"])
    print("Matched Items:", output.get("items", []))
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/furnitureTryOn/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('Matched Items:', result.output.items);
      } else {
        console.log('Task ended with status:', status);
      }
      break;
    }

    // Wait 3 seconds before next poll
    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/living-room.jpg",
      "furnitureList": [
        {
          "imageUrl": "https://example.com/sofa.png"
        },
        {
          "imageUrl": "https://example.com/coffee-table.png"
        }
      ],
      "prompt": "modern minimalist style",
      "modelType": "Base"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/furniture_try_on_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": 45,
    "input": {
      "imageUrl": "https://example.com/living-room.jpg",
      "furnitureList": [
        {
          "imageUrl": "https://example.com/sofa.png"
        }
      ],
      "prompt": "modern minimalist style",
      "modelType": "Base"
    },
    "output": null
  }
}

Resposta (Tarefa Falhou)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Failed",
    "waitNumber": 0,
    "percentage": 0,
    "input": {
      "imageUrl": "https://example.com/living-room.jpg",
      "furnitureList": [
        {
          "imageUrl": "https://example.com/sofa.png"
        }
      ],
      "modelType": "Base"
    },
    "output": null
  }
}

Campos da Resposta

CampoTipoDescrição
idlongIdentificador único da tarefa
statusstringStatus atual da tarefa (consulte Status da Tarefa)
waitNumberintegerNúmero de tarefas à frente na fila (0 significa que está sendo processada no momento)
percentageintegerPorcentagem de conclusão da tarefa (0–100)
inputobjectOs parâmetros de entrada originais da tarefa
input.imageUrlstringURL da imagem da cena do cômodo
input.furnitureListarrayLista de itens de mobiliário enviados (máx. 6 itens)
input.furnitureList[].imageUrlstringURL da imagem do produto de mobiliário
input.promptstringPrompt de texto personalizado (se fornecido)
input.modelTypestringTipo de modelo usado
outputobjectResultado da geração (disponível apenas quando status é Success)
output.resultUrlstringURL para a imagem do cômodo gerada com o mobiliário inserido
output.widthintegerLargura de saída em pixels
output.heightintegerAltura de saída em pixels

📊 Status da Tarefa#

StatusDescrição
UnprocessedA tarefa foi criada, mas ainda não começou
ProcessingA tarefa está sendo processada no momento
SuccessTarefa concluída com sucesso — a saída está disponível
FailedA tarefa falhou devido a um erro

Consulte a cada 3-5 segundos. Consulte Limite 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 obter detalhes específicos do erro
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 ou furnitureList ausentes, ou furnitureList excede 6 itensGaranta que imageUrl e furnitureList sejam fornecidos, não vazios e que contenham no máximo 6 itens
5002API_KEY_INVALIDChave API inválida ou ausenteVerifique se o cabeçalho APIKEY está presente e se o valor está correto
9010SCAN_TEXT_ERRORO prompt de texto não passou pela análise de conteúdoModifique o prompt para remover conteúdo sensível ou proibido
9038PROHIBITED_CONTENTA imagem gerada contém conteúdo proibidoAjuste o prompt/estilo/entradas e tente novamente
9051COINS_NOT_ENOUGHMoedas/créditos insuficientesRecarregue os créditos da sua conta e tente novamente

📄 Para a lista completa de códigos de erro comuns da API, consulte a Referência de Códigos de Erro.