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

# Inpaint an area

> Use a mask to change part of an image.

Use a completed image as the source. Upload a black-and-white PNG mask with exactly the same dimensions: white marks the region to change and black preserves it. Send its ID in `mask_image_id`.

The defaults are model `v1`, mode `inpaint`, and `denoise: 1.0`. This operation creates one image. A lower denoise value makes a gentler change.

A successful request returns HTTP `202` with a `jobs` array. Save each `id`, then [get the job](/api-reference/jobs/get) until it finishes. Read the completed media from `result.url` and its reusable ID from `result.id`. Use an [Idempotency-Key](/api-reference/errors) when submitting work that may be retried.


## OpenAPI

````yaml api-reference/openapi.json POST /v1/images/{id}/inpaint
openapi: 3.0.3
info:
  title: bitStudio public API
  version: 1.0.0
  description: >-
    Public v1 operations. Create work with a focused endpoint, then retrieve its
    job. Media IDs are opaque; API clients do not manage Studio versions. New
    response fields may be added; clients should ignore fields they do not
    recognize.
servers:
  - url: https://api.bitstudio.ai
    description: Production
security:
  - bearerAuth: []
paths:
  /v1/images/{id}/inpaint:
    post:
      summary: Inpaint an area
      operationId: inpaint
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Source resource ID.
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 128
            pattern: ^[!-~]+$
          description: >-
            Use a unique key for each intended creation. Retry the same method,
            path and JSON with the same key to replay its response for 24 hours
            after completion. Conflicting requests and unfinished or uncertain
            outcomes return 409. An uncertain receipt is never automatically
            rerun.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicInpaintRequest'
            example:
              mask_image_id: 22222222-2222-4222-8222-222222222222
              prompt: White fabric
      responses:
        '202':
          description: Accepted; poll each job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Submission'
              example:
                jobs:
                  - id: 11111111-1111-4111-8111-111111111111
                    status: pending
                    task: inpaint
                    created_at: '2026-09-15T12:00:00Z'
                    result: null
                    error: null
                    credits_used: 1
        default:
          description: Request failed; inspect code and message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    PublicInpaintRequest:
      type: object
      additionalProperties: false
      properties:
        model:
          type: string
          default: v1
          description: Model for this operation. Account and plan limits apply.
          enum:
            - v1
        resolution:
          type: string
          enum:
            - standard
            - high
          default: standard
          description: Output quality; dimensions depend on the model and aspect ratio.
        num_images:
          type: integer
          description: Number of outputs. Defaults to 1. Account limits still apply.
          minimum: 1
          maximum: 1
          example: 1
          default: 1
        seed:
          type: integer
          description: Optional seed; it does not guarantee identical results.
        mask_image_id:
          type: string
          description: >-
            Uploaded black-and-white PNG mask: white marks the region to change;
            black preserves the surrounding area. Must match the selected source
            dimensions.
          format: uuid
        prompt:
          type: string
          description: What should appear in the masked area.
        mode:
          type: string
          enum:
            - inpaint
            - extend
          default: inpaint
        reference_image_id:
          type: string
          description: Optional reference, mutually exclusive with reference_asset_id.
          format: uuid
        reference_asset_id:
          type: string
          description: >-
            Optional reusable reference, mutually exclusive with
            reference_image_id.
          format: uuid
        asset_ids:
          type: array
          items:
            type: string
          description: >-
            Additional reusable reference asset IDs. Supported types depend on
            the operation.
        denoise:
          type: number
          minimum: 0.05
          maximum: 1
          description: Strength of the change.
          example: 1
          default: 1
        style:
          type: string
          description: Optional style directions.
        speed:
          type: string
          description: >-
            Optional processing speed; accepted values depend on the operation
            and model.
      required:
        - mask_image_id
    Submission:
      type: object
      required:
        - jobs
      properties:
        jobs:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Job'
    Error:
      type: object
      required:
        - code
        - message
        - request_id
      properties:
        code:
          type: string
        message:
          type: string
        request_id:
          type: string
          format: uuid
        error:
          type: string
          description: Compatibility error description.
        cta:
          type: boolean
          description: Account action is required.
        next_action:
          type: string
    Job:
      type: object
      required:
        - id
        - status
        - task
        - created_at
        - result
        - error
        - credits_used
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - pending
            - generating
            - completed
            - failed
            - policy_blocked
        task:
          type: string
          nullable: true
          description: >-
            Processing task. This may be more specific than the submitted
            operation.
        created_at:
          type: string
          format: date-time
        result:
          $ref: '#/components/schemas/JobResult'
        error:
          $ref: '#/components/schemas/JobError'
        credits_used:
          type: number
          minimum: 0
          description: >-
            Credits currently charged for this output, in display credits: 1
            means one Studio credit. Fractional amounts are preserved. A
            completed refund is reflected as 0 when polling. Creation and
            idempotency replay responses are snapshots; poll for the latest
            charge.
          example: 1.5
    JobResult:
      type: object
      nullable: true
      required:
        - image_id
        - url
        - width
        - height
        - id
        - type
      properties:
        image_id:
          type: string
          format: uuid
          description: Compatibility alias for id. Use id for new integrations.
        url:
          type: string
          format: uri
          description: Completed media URL.
        width:
          type: integer
          nullable: true
        height:
          type: integer
          nullable: true
        id:
          type: string
          format: uuid
          description: >-
            Opaque media ID. Pass an image result ID into the next image
            operation.
        type:
          type: string
          enum:
            - image
            - video
    JobError:
      type: object
      nullable: true
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: >-
            Safe failure classification. Handle unknown or new values with a
            general failure message.
        message:
          type: string
          description: Safe, readable failure description.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Create an API key in Studio → account menu → API Keys. Keep it on your
        server.

````