openapi: 3.1.0 info: title: DecorViz API version: "1.0" description: | Generate photorealistic previews of furniture and decor products inside real customer room photos. Send a room photo and a product image, receive a composited result image hosted on a CDN-ready URL. Outputs are visual previews. DecorViz does not promise dimensional accuracy or measurement correctness. Communicate this to end users where relevant. contact: name: DecorViz API Support email: support@decorviz.ai servers: - url: https://decorviz.ai/api security: - apiKey: [] paths: /partner-generate: post: summary: Queue a generation description: | Validates inputs, reserves one generation from your balance, and queues the job. Returns immediately with 202 Accepted. Poll partner-status for the result. Failed generations are refunded automatically. operationId: createGeneration requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/GenerateRequest" responses: "202": description: Generation queued. content: application/json: schema: $ref: "#/components/schemas/GenerationPending" "200": description: Duplicate request_id. Returns the original generation. content: application/json: schema: $ref: "#/components/schemas/GenerationDuplicate" "400": description: Invalid input (MISSING_FIELDS, INVALID_IMAGE, UNSAFE_URL, INVALID_WEBHOOK_URL). content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Missing, malformed, or revoked API key (INVALID_API_KEY). content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Insufficient generation balance (INSUFFICIENT_CREDITS). content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: Account suspended (ACCOUNT_SUSPENDED). content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: RATE_LIMIT_EXCEEDED, CONCURRENCY_LIMIT_EXCEEDED, or DAILY_CAP_EXCEEDED. content: application/json: schema: $ref: "#/components/schemas/Error" /partner-status: get: summary: Poll generation status description: | Returns the current state of a generation. Poll no faster than once every 2 seconds. Typical completion time is 10 to 30 seconds. operationId: getGenerationStatus parameters: - name: id in: query required: true schema: type: string format: uuid description: Generation id returned by partner-generate. responses: "200": description: Current generation state. content: application/json: schema: oneOf: - $ref: "#/components/schemas/GenerationPending" - $ref: "#/components/schemas/GenerationCompleted" - $ref: "#/components/schemas/GenerationFailed" "401": description: Missing, malformed, or revoked API key. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Generation not found. content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Polling too fast. content: application/json: schema: $ref: "#/components/schemas/Error" /partner-usage: get: summary: Usage and balance description: | Returns your remaining balance and daily generation counts for a date range. Defaults to the last 30 days. Maximum range is 366 days. operationId: getUsage parameters: - name: from in: query required: false schema: type: string format: date - name: to in: query required: false schema: type: string format: date responses: "200": description: Balance and daily usage. content: application/json: schema: $ref: "#/components/schemas/Usage" "401": description: Missing, malformed, or revoked API key. content: application/json: schema: $ref: "#/components/schemas/Error" components: securitySchemes: apiKey: type: http scheme: bearer description: | API key issued by DecorViz, sent as a Bearer token. Live keys start with dv_live_, sandbox keys with dv_sandbox_. schemas: GenerateRequest: type: object required: - request_id - room_image properties: request_id: type: string maxLength: 128 description: | Your idempotency key, unique per generation. Sending the same request_id twice returns the original generation without charging again. room_image: type: string description: | Customer room photo as a base64 data URL or raw base64 string. JPEG, PNG, or WebP. Maximum 7 MB. product_image: type: string description: | Product photo as base64. Either product_image or product_image_url is required. product_image_url: type: string format: uri description: | Public HTTPS URL of the product photo. Fetched server-side with security validation. Either product_image or product_image_url is required. product_title: type: string maxLength: 300 description: Product name, strongly recommended for better results. product_scale_details: type: string maxLength: 800 description: | Product dimensions as text, for example "Width 220 cm, depth 95 cm". Strongly recommended for realistic sizing. prompt: type: string maxLength: 800 description: | Optional placement instructions, for example "Place the sofa near the window". Added to the product context layer of the generation prompt. Placement and realism rules remain DecorViz-controlled. category: type: string description: | Product category id from the documented list (sofa, table, bed, rug, and so on). Unknown or missing values fall back to a generic placement profile. product_url: type: string format: uri description: Optional product page URL, stored for your reference. webhook_url: type: string format: uri description: | Reserved. Accepted and stored, but webhook delivery is not yet active. Use polling. GenerationPending: type: object properties: id: type: string format: uuid status: type: string enum: [pending, processing] created_at: type: string format: date-time GenerationDuplicate: type: object properties: id: type: string format: uuid status: type: string enum: [pending, processing, completed, failed] created_at: type: string format: date-time duplicate: type: boolean const: true GenerationCompleted: type: object properties: id: type: string format: uuid status: type: string const: completed image_url: type: string format: uri description: Result image. Stable URL, hosted for 90 days by default. thumbnail_url: type: string format: uri created_at: type: string format: date-time completed_at: type: string format: date-time generations_used: type: integer const: 1 GenerationFailed: type: object properties: id: type: string format: uuid status: type: string const: failed error_code: type: string error_message: type: string created_at: type: string format: date-time completed_at: type: string format: date-time generations_used: type: integer const: 0 description: Failed generations are refunded automatically. Usage: type: object properties: balance_generations: type: integer description: Generations remaining on your account. from: type: string format: date to: type: string format: date totals: type: object properties: generations: type: integer completed: type: integer failed: type: integer in_flight: type: integer days: type: array items: type: object properties: date: type: string format: date generations: type: integer completed: type: integer failed: type: integer in_flight: type: integer Error: type: object properties: status: type: string const: error code: type: string description: | Stable machine-readable code. One of MISSING_FIELDS, INVALID_API_KEY, ACCOUNT_SUSPENDED, RATE_LIMIT_EXCEEDED, CONCURRENCY_LIMIT_EXCEEDED, DAILY_CAP_EXCEEDED, INSUFFICIENT_CREDITS, INVALID_IMAGE, UNSAFE_URL, INVALID_WEBHOOK_URL, MODEL_TIMEOUT, MODEL_REJECTED, NOT_FOUND, INTERNAL_ERROR. message: type: string description: Human-readable explanation. Do not parse; may change.