{
"openapi": "3.1.0",
"info": {
"title": "VISOID public API",
"version": "v1",
"description": "[Visoid](https://www.visoid.com/) lets you create architectural renders in minutes.\n\nThis page explains how to use the **Visoid REST API** and integrate Visoid into your application.\n\nFor current rendering defaults, use `POST /api/v2/images/{imageId}/render/explore` with the same request body documented below. The v1 render endpoint preserves the rendering behavior from before October 30, 2026. Uploads, result polling, and upscaling continue to use v1.\n\n## Frequently Asked Questions (FAQ)\n\n\n How do I generate an API key?
\n\nIf you don't already have an API plan, contact our [sales team](https://www.visoid.com/render/architectural-rendering-api-from-visoid#contact_us).\n\nAfter your API plan is active, follow these steps to generate a key:\n\n1. Open the [API account page](https://app.visoid.com/account/api).\n2. Select **Generate your API key**, or select **Regenerate** to replace an existing key.\n3. Copy the displayed key and store it securely. You cannot retrieve it again.\n\nRegenerating a key disables the previous key immediately.\n\n \n\n\n How do I use my API key?
\n\nAuthenticate every API request with a valid API key.\n\nSend the key in the **`X-API-Key`** HTTP header.\n\n \n\n## Resources\n\n- https://www.visoid.com/\n- https://www.visoid.com/render/architectural-rendering-api-from-visoid\n"
},
"servers": [
{
"url": "https://app.visoid.com/api/v1"
}
],
"components": {
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "X-Api-Key"
}
},
"schemas": {
"Image": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"createdAt": {
"type": "string",
"format": "date-time"
}
},
"required": ["id", "createdAt"]
},
"Images": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Image"
}
},
"RenderExploreBody": {
"type": "object",
"properties": {
"callbackUrl": {
"description": "URL called when task is finished.\nEndpoint will be called using **POST** method with a body containing:\n- `imageId` the rendered image\n- `sourceImageId` the original image from which the rendering was made\n- `status` the state of the operation, could be `completed` or `failed`",
"type": "string",
"format": "uri"
},
"quality": {
"type": "string",
"enum": ["1K", "2K", "4K"],
"default": "1K",
"description": "Resolution of the rendered image. Costs **3 credits** for 1K, **5 credits** for 2K, and **10 credits** for 4K."
},
"style": {
"$ref": "#/components/schemas/RenderStyle"
},
"input": {
"type": "object",
"description": "Minimal required setting is `input.positivePrompt`",
"properties": {
"positivePrompt": {
"type": "string",
"default": ""
},
"freedom": {
"type": "number",
"default": 1.4,
"min": 0.6,
"max": 3
},
"mask": {
"type": "string",
"description": "Base64 encoded image mask.\n\n**The mask should have the same dimensions as the input image.**\n\n**The selected part of the image should be white, while the non-selected part should be fully transparent using the alpha channel**",
"example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}
}
}
},
"required": ["input"]
},
"RenderStyle": {
"type": "string",
"description": "Visual style applied to the render.",
"enum": [
"realistic",
"vector-sketch",
"vector-illustration",
"watercolor-sketch",
"watercolor-collage",
"highlighted-sketch",
"pastel-concept",
"post-digital-collage",
"ink-sketch"
],
"default": "realistic"
},
"UpscaleBody": {
"type": "object",
"properties": {
"callbackUrl": {
"description": "URL called when task is finished.\nEndpoint will be called using **POST** method with a body containing:\n- `imageId` the upscaled image\n- `sourceImageId` the original image which was upscaled\n- `status` the state of the operation, could be `completed` or `failed`",
"type": "string",
"format": "uri"
},
"quality": {
"type": "string",
"enum": ["2K", "4K"],
"default": "2K"
},
"name": {
"type": "string"
}
}
}
}
},
"paths": {
"/images/{imageId}": {
"get": {
"summary": "Get an image (uploaded, rendered, or upscaled)",
"description": "Returns the image corresponding to the ID with a `file` field which is a link to the image's `Blob`. This link is signed and will expire after 20 minutes. You can generate a new link by calling this endpoint again.\n",
"parameters": [
{
"name": "imageId",
"in": "path",
"description": "Image ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "The image",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Image"
},
{
"type": "object",
"properties": {
"file": {
"description": "Link to the image's `Blob`",
"type": "string",
"format": "uri"
},
"status": {
"description": "The render state of the image",
"type": "string",
"enum": [
"complete",
"failed",
"initialized",
"rendering"
]
}
}
}
]
}
}
}
},
"404": {
"description": "No image corresponding to the imageId"
}
}
}
},
"/images/{imageId}/render/explore": {
"post": {
"summary": "Render an image using Explore tool",
"description": "_This operation costs_ **3 credits** for 1K, **5 credits** for 2K, and **10 credits** for 4K (controlled by the `quality` parameter).\n\nIt is possible to pass a Base64 image mask (`input.mask`) to select only parts of the image that should be changed.\n",
"parameters": [
{
"name": "imageId",
"in": "path",
"description": "Image ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RenderExploreBody"
}
}
}
},
"responses": {
"202": {
"description": "Rendering task started",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "ID of the created image",
"properties": {
"id": {
"type": "string",
"format": "uuid"
}
}
}
}
}
},
"404": {
"description": "No image corresponding to the imageId"
}
}
}
},
"/images/{imageId}/upscale": {
"post": {
"summary": "Upscale an image",
"description": "### Costs of upscaling an image\n| Quality | Cost (credits) |\n|---------|----------------|\n| 2K | 5 |\n| 4K | 10 |\n",
"parameters": [
{
"name": "imageId",
"in": "path",
"description": "Image ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpscaleBody"
}
}
}
},
"responses": {
"202": {
"description": "Upscaling task started",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "ID of the created image",
"properties": {
"id": {
"type": "string",
"format": "uuid"
}
}
}
}
}
},
"404": {
"description": "No image corresponding to the imageId"
}
}
}
},
"/images": {
"get": {
"summary": "Get the list of all images uploaded, rendered, and upscaled",
"responses": {
"200": {
"description": "All images sorted by date, the most recent first.\n\n*Note: limited to 1000 images*",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Images"
}
}
}
}
}
},
"post": {
"summary": "Upload a new image",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["image"],
"properties": {
"image": {
"type": "string",
"description": "Base64 of the image.\n\nHeight and width of the image should be minimum 50px\n\nImages above 67,108,864 total pixels (8192×8192) are rejected,\nand images larger than 4096px on either side are downscaled to fit.\n\nThis is limited by AWS Lambdas: the full request size is limited to 6MB.\n",
"example": "data:image/png;base64,iVBORw...."
},
"name": {
"type": "string"
},
"projectId": {
"type": "string",
"format": "uuid",
"description": "Optional project ID to associate the image with.\nIf not provided, the image is added to the project this\nconnection is pointed at, or to the most recently\nupdated project when it is pointed at none.\n"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Successfully uploaded",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "ID of the created image",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"webUrl": {
"type": "string",
"description": "Direct link to view the uploaded image in the app, in\nthe project it was added to.\n"
}
}
}
}
}
}
}
}
},
"/v2/images/{imageId}/render/explore": {
"post": {
"summary": "Render an image using current defaults (v2)",
"description": "_This operation costs_ **3 credits** for 1K, **5 credits** for 2K, and **10 credits** for 4K (controlled by the `quality` parameter).\n\nIt is possible to pass a Base64 image mask (`input.mask`) to select only parts of the image that should be changed.\n",
"parameters": [
{
"name": "imageId",
"in": "path",
"description": "Image ID",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RenderExploreBody"
}
}
}
},
"responses": {
"202": {
"description": "Rendering task started",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "ID of the created image",
"properties": {
"id": {
"type": "string",
"format": "uuid"
}
}
}
}
}
},
"404": {
"description": "No image corresponding to the imageId"
}
},
"operationId": "renderExploreV2",
"servers": [
{
"url": "https://app.visoid.com/api"
}
]
}
}
},
"tags": []
}