{ "openapi": "3.1.0", "info": { "title": "Huisvue API", "version": "1.0.0", "description": "Richt uw woningfoto's virtueel in, maak ze leeg of renoveer ze in enkele seconden, voor een paar cent per foto.\n\nAuthentication: `Authorization: Bearer hv_…` (create up to 5 keys in your account, page API). Each job costs the same credits as on nl.huisvue.com; failed jobs are refunded. Jobs run asynchronously: start one, then poll it until `statut` is `termine` or `echec`. Results are signed links valid 24 h. Limits: 120 requests per minute per key, 50 pending jobs, 50 images per batch, 15 MB per image." }, "externalDocs": { "url": "https://nl.huisvue.com/developers" }, "servers": [ { "url": "https://nl.huisvue.com/api/v1" } ], "security": [ { "cle": [] } ], "tags": [ { "name": "outils" }, { "name": "travaux" }, { "name": "compte" } ], "paths": { "/outils": { "get": { "operationId": "listerOutils", "tags": [ "outils" ], "summary": "List tools, their cost and settings", "security": [], "responses": { "200": { "description": "Tools", "content": { "application/json": { "schema": { "type": "object", "properties": { "outils": { "type": "array", "items": { "$ref": "#/components/schemas/Outil" } } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } }, "/solde": { "get": { "operationId": "lireSolde", "tags": [ "compte" ], "summary": "Credit balance", "responses": { "200": { "description": "Balance", "content": { "application/json": { "schema": { "type": "object", "required": [ "credits" ], "properties": { "credits": { "type": "integer" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } }, "/travaux": { "get": { "operationId": "listerTravaux", "tags": [ "travaux" ], "summary": "Recent jobs, newest first", "parameters": [ { "name": "limite", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "outil", "in": "query", "schema": { "type": "string", "enum": [ "vider", "staging", "renovation", "saison", "ciel", "annonce" ] } } ], "responses": { "200": { "description": "Jobs", "content": { "application/json": { "schema": { "type": "object", "properties": { "travaux": { "type": "array", "items": { "$ref": "#/components/schemas/Travail" } } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } }, "post": { "operationId": "lancerTravail", "tags": [ "travaux" ], "summary": "Start a job (one image) or a batch (several images, same settings)", "description": "Send JSON with image URLs (https only) or base64, or multipart/form-data with files. For one-photo tools, several images create a batch (`lot`): one job per image, up to 50. Credits are checked for the whole batch before anything starts.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "vider (4 credits per image)", "type": "object", "required": [ "outil", "images" ], "properties": { "outil": { "const": "vider" }, "valeurs": { "$ref": "#/components/schemas/Valeurs_vider" }, "images": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/Image" } } } }, { "title": "staging (5 credits per image)", "type": "object", "required": [ "outil", "images" ], "properties": { "outil": { "const": "staging" }, "valeurs": { "$ref": "#/components/schemas/Valeurs_staging" }, "images": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/Image" } } } }, { "title": "renovation (8 credits per image)", "type": "object", "required": [ "outil", "images" ], "properties": { "outil": { "const": "renovation" }, "valeurs": { "$ref": "#/components/schemas/Valeurs_renovation" }, "images": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/Image" } } } }, { "title": "saison (3 credits per image)", "type": "object", "required": [ "outil", "images" ], "properties": { "outil": { "const": "saison" }, "valeurs": { "$ref": "#/components/schemas/Valeurs_saison" }, "images": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/Image" } } } }, { "title": "ciel (2 credits per image)", "type": "object", "required": [ "outil", "images" ], "properties": { "outil": { "const": "ciel" }, "valeurs": { "$ref": "#/components/schemas/Valeurs_ciel" }, "images": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/Image" } } } }, { "title": "annonce (3 credits per job)", "type": "object", "required": [ "outil", "valeurs" ], "properties": { "outil": { "const": "annonce" }, "valeurs": { "$ref": "#/components/schemas/Valeurs_annonce" }, "images": { "type": "array", "minItems": 0, "maxItems": 6, "items": { "$ref": "#/components/schemas/Image" } } } } ] } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "outil" ], "properties": { "outil": { "type": "string", "enum": [ "vider", "staging", "renovation", "saison", "ciel", "annonce" ] }, "fichiers": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "One or more image files (any field name)." }, "image_url": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Image URLs (https), repeatable." } }, "additionalProperties": { "type": "string", "description": "Tool settings, e.g. style=modern" } } } } }, "responses": { "202": { "description": "Started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lancement" } } } }, "400": { "description": "Malformed body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "402": { "description": "Not enough credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "413": { "description": "Too large (100 MB per request, 15 MB per image, 50 images per batch)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "422": { "description": "Invalid tool, settings or image", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "429": { "description": "Rate limited or too many pending jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } }, "/travaux/{id}": { "get": { "operationId": "lireTravail", "tags": [ "travaux" ], "summary": "A job, with signed links to its results", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Travail" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } }, "/lots/{id}": { "get": { "operationId": "lireLot", "tags": [ "travaux" ], "summary": "A batch: progress, jobs and, once done, a ZIP of all results", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lot" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } } }, "components": { "securitySchemes": { "cle": { "type": "http", "scheme": "bearer", "description": "API key (hv_…)" } }, "schemas": { "Erreur": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "examples": [ "insufficient_credits" ] }, "message": { "type": "string" } }, "additionalProperties": true } } }, "Image": { "oneOf": [ { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Public https URL" }, "nom": { "type": "string" } } }, { "type": "object", "required": [ "base64" ], "properties": { "base64": { "type": "string", "description": "Base64 or data URL" }, "nom": { "type": "string" } } } ] }, "Outil": { "type": "object", "properties": { "id": { "type": "string" }, "nom": { "type": "string" }, "resume": { "type": "string" }, "cout": { "type": "integer", "description": "Credits per job" }, "images": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" }, "par_lot": { "type": "boolean", "description": "Several images = one job each (batch)" } } }, "champs": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "Travail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "outil": { "type": "string" }, "statut": { "type": "string", "enum": [ "en_attente", "en_cours", "termine", "echec" ] }, "cout": { "type": "integer" }, "valeurs": { "type": "object", "additionalProperties": { "type": "string" } }, "lot": { "type": [ "string", "null" ] }, "nom": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "web", "api", "mcp" ] }, "cree_le": { "type": "string", "format": "date-time" }, "commence_le": { "type": [ "string", "null" ], "format": "date-time" }, "termine_le": { "type": [ "string", "null" ], "format": "date-time" }, "resultats": { "type": "array", "items": { "type": "object", "required": [ "url", "expire_le" ], "properties": { "url": { "type": "string", "format": "uri" }, "expire_le": { "type": "string", "format": "date-time" } } }, "description": "Signed links, valid 24 h" }, "texte": { "type": [ "string", "null" ], "description": "Text result (Markdown)" }, "erreur": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "rembourse": { "type": "boolean" } } }, "Lot": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "outil": { "type": "string" }, "statut": { "type": "string", "enum": [ "en_cours", "termine", "partiel", "echec" ] }, "total": { "type": "integer" }, "termines": { "type": "integer" }, "echecs": { "type": "integer" }, "en_cours": { "type": "integer" }, "zip": { "oneOf": [ { "type": "object", "required": [ "url", "expire_le" ], "properties": { "url": { "type": "string", "format": "uri" }, "expire_le": { "type": "string", "format": "date-time" } } }, { "type": "null" } ] }, "travaux": { "type": "array", "items": { "$ref": "#/components/schemas/Travail" } } } }, "Lancement": { "type": "object", "properties": { "lot": { "type": [ "string", "null" ], "description": "Batch id when several images were sent" }, "outil": { "type": "string" }, "cout_total": { "type": "integer" }, "travaux": { "type": "array", "items": { "$ref": "#/components/schemas/Travail" } }, "echecs": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "Valeurs_vider": { "type": "object", "additionalProperties": false, "required": [], "properties": {} }, "Valeurs_staging": { "type": "object", "additionalProperties": false, "required": [], "properties": { "piece": { "type": "string", "title": "Ruimte", "enum": [ "living room", "bedroom", "kitchen", "dining room", "home office", "children's bedroom" ], "default": "living room" }, "style": { "type": "string", "title": "Style", "enum": [ "modern", "Scandinavian", "industrial", "classic elegant", "japandi", "warm bohemian" ], "default": "modern" } } }, "Valeurs_renovation": { "type": "object", "additionalProperties": false, "required": [], "properties": { "zone": { "type": "string", "title": "Zone", "enum": [ "facade", "interieur" ], "default": "facade" }, "niveau": { "type": "string", "title": "Werken", "enum": [ "rafraichissement", "complete" ], "default": "complete" }, "style": { "type": "string", "title": "Style", "enum": [ "contemporary", "classic", "natural materials" ], "default": "contemporary" } } }, "Valeurs_saison": { "type": "object", "additionalProperties": false, "required": [], "properties": {} }, "Valeurs_ciel": { "type": "object", "additionalProperties": false, "required": [], "properties": {} }, "Valeurs_annonce": { "type": "object", "additionalProperties": false, "required": [ "lieu" ], "properties": { "langue": { "type": "string", "title": "Taal", "enum": [ "French", "English", "Dutch", "German", "Spanish", "Italian" ], "default": "Dutch" }, "lieu": { "type": "string", "title": "Plaats", "maxLength": 1000 }, "infos": { "type": "string", "title": "Oppervlakte, kamers, prijs", "maxLength": 1000 }, "atouts": { "type": "string", "title": "Troeven", "maxLength": 1000 } } } } } }