> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kynva.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Insert object into scene

> Insert an object into a background scene using AI-powered placement



## OpenAPI

````yaml /openapi.yaml post /api/v1/ai/insert-object
openapi: 3.0.0
info:
  title: Kynva Public API
  description: >

    # Kynva Public API v4.0


    The stateless contract API: everything flows through

    `POST /api/v1/facade/generate` with a `RenderForgeRequestV1` body.


    ## Entry Points


    ### Sync preview

    ```

    POST /generate { operation: "preview" } → 200 with rendered outputs

    ```


    ### Async render

    ```

    POST /generate { operation: "render" } → 202 + job → poll GET
    /render-jobs/{id} or subscribe to webhooks

    ```


    ### Signed image URLs (the OG-image primitive)

    ```

    POST /api/v1/generate/sign → signed GET URLs → 302 to immutable rendered
    PNGs

    ```


    ## Core Principle

    Deterministic by construction: the same request, engine version, and seed

    produce byte-identical output.


    ## API Versioning

    Include `X-API-Version: 2026-01-01` in all requests.


    ## Authentication

    Include `Authorization: Bearer <token>` in all requests (signed image

    GET URLs authenticate by signature instead).


    ## Idempotency

    Include `Idempotency-Key: <uuid>` for all POST/PATCH mutations.


    ## Rate Limiting

    Tiered limits per endpoint category (see documentation).
  version: 4.0.0
  contact:
    name: Kynva Support
    url: https://github.com/fredadun/renderforge
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://api.kynva.ai
    description: Production
  - url: https://renderforge-production-838f.up.railway.app
    description: Production (direct, until api.kynva.ai DNS lands)
  - url: http://localhost:3000
    description: Development
security:
  - bearerAuth: []
tags:
  - name: Brands
    description: Brand management
  - name: BrandKits
    description: Brand kit version management
  - name: Assets
    description: Asset upload and management
  - name: Drafts
    description: Draft creation and workflow
  - name: Decisions
    description: Decision records and explainability
  - name: Render Jobs
    description: Async render job management
  - name: Webhooks
    description: Webhook configuration and DLQ
  - name: Render Now
    description: Single-call convenience endpoint
  - name: Templates (Advanced)
    description: Template selection and listing
  - name: Validation (Advanced)
    description: Stateless validation
  - name: Compile (Advanced)
    description: Stateless compilation
  - name: Licenses (Advanced)
    description: License checking
  - name: Spec Render (Advanced)
    description: Direct spec preview/render
  - name: Reference
    description: Reference data (export profiles, API versions)
  - name: System
    description: Health checks and system info
  - name: Images
    description: Generate images from templates
  - name: Templates
    description: Manage reusable templates
  - name: Health
    description: Service health and status
paths:
  /api/v1/ai/insert-object:
    post:
      tags:
        - AI
      summary: Insert object into scene
      description: Insert an object into a background scene using AI-powered placement
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - backgroundUrl
                - objectUrl
              properties:
                backgroundUrl:
                  type: string
                  format: uri
                  description: URL of the background/scene image
                objectUrl:
                  type: string
                  format: uri
                  description: URL of the object image (should have transparent background)
                placement:
                  type: string
                  enum:
                    - auto
                    - center
                    - left
                    - right
                    - top
                    - bottom
                    - custom
                  default: auto
                  description: >-
                    Placement strategy (auto uses Claude Vision for intelligent
                    placement)
                customPosition:
                  type: object
                  properties:
                    x:
                      type: number
                    'y':
                      type: number
                  description: Custom position (only used when placement is "custom")
                scale:
                  type: number
                  minimum: 0.1
                  maximum: 3
                  default: 1
                blendMode:
                  type: string
                  enum:
                    - normal
                    - multiply
                    - screen
                    - overlay
                    - soft-light
                    - hard-light
                  default: normal
                shadowEnabled:
                  type: boolean
                  default: false
                shadow:
                  type: object
                  properties:
                    offsetX:
                      type: number
                      default: 5
                    offsetY:
                      type: number
                      default: 5
                    blur:
                      type: number
                      default: 10
                    opacity:
                      type: number
                      minimum: 0
                      maximum: 1
                      default: 0.5
                    color:
                      type: string
                      default: '#000000'
                prompt:
                  type: string
                  description: 'Hint for AI placement: "place on the table"'
                outputFormat:
                  type: string
                  enum:
                    - png
                    - webp
                    - jpg
                  default: png
                quality:
                  type: number
                  minimum: 1
                  maximum: 100
                  default: 90
        required: true
      responses:
        '200':
          description: Object inserted successfully
          content:
            application/json:
              schema:
                description: Object inserted successfully
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      url:
                        type: string
                      width:
                        type: number
                      height:
                        type: number
                      placement:
                        type: object
                        properties:
                          x:
                            type: number
                          'y':
                            type: number
                          scale:
                            type: number
                      confidence:
                        type: number
                      reasoning:
                        type: string
                      processingTime:
                        type: number
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Your Kynva API key (kyn_live_xxx or kyn_test_xxx; legacy rf_ keys remain
        valid)

````