> ## Documentation Index > Fetch the complete documentation index at: https://docs.videobgremover.com/llms.txt > Use this file to discover all available pages before exploring further. # Refine a job's mask with a SAM3 text prompt > Stack a second SAM3 text-prompt segmentation onto a completed job's existing mask. Use this when background removal is mostly correct but misses (or over-includes) part of the subject. - `op: "add"` unions the new mask onto the existing one (fills a missing region). - `op: "subtract"` removes the new mask's region from the existing one. The refinement is **non-destructive**: the original mask is preserved and a new versioned mask is written. On completion the job's active mask is updated, so a subsequent re-export (`POST /v1/jobs/{id}/exports`) returns the refined result in any format. Refinement runs GPU inference and consumes credits (refunded on failure). Only one refinement may run per job at a time, and the job must be `completed`. Send an optional `Idempotency-Key` to retry safely. The same key and request return the original refinement and its current status without another charge. Reusing a key with different inputs returns 409. Keys are scoped to your account and job and retained with the refinement record. After a terminal failure, use a new key for a new attempt. Version numbers may have gaps after failed attempts. ## OpenAPI ````yaml /openapi.yaml post /v1/jobs/{id}/refine-mask openapi: 3.0.3 info: title: VideoBGRemover API version: 1.6.0 description: > Remove backgrounds from videos using AI-powered processing. The VideoBGRemover API allows you to: - Upload videos or provide URLs for processing - Remove backgrounds with customizable options - Generate transparent videos in multiple formats - Compose videos on custom backgrounds (server-side) - Track processing status and manage credits ## Authentication All API requests require authentication using an API key in the `X-Api-Key` header. ## Credits System Background-removal pricing depends on the selected model. At standard frame rates, Light and Human use 0.75 credits per second, Original uses 1 credit per second, and Pro uses 3 credits per second. Blur uses 1 credit per second. Frame-rate and optional processing multipliers may apply; the start-job response returns the exact charge. contact: name: VideoBGRemover API Support url: https://videobgremover.com/contact license: name: MIT url: https://opensource.org/licenses/MIT servers: - url: https://api.videobgremover.com description: Production server security: - ApiKeyAuth: [] tags: - name: Jobs description: Video processing job management - name: Credits description: Credit balance and usage - name: API description: API metadata and documentation - name: Webhooks description: Webhook delivery and history paths: /v1/jobs/{id}/refine-mask: post: tags: - Jobs summary: Refine a job's mask with a SAM3 text prompt description: > Stack a second SAM3 text-prompt segmentation onto a completed job's existing mask. Use this when background removal is mostly correct but misses (or over-includes) part of the subject. - `op: "add"` unions the new mask onto the existing one (fills a missing region). - `op: "subtract"` removes the new mask's region from the existing one. The refinement is **non-destructive**: the original mask is preserved and a new versioned mask is written. On completion the job's active mask is updated, so a subsequent re-export (`POST /v1/jobs/{id}/exports`) returns the refined result in any format. Refinement runs GPU inference and consumes credits (refunded on failure). Only one refinement may run per job at a time, and the job must be `completed`. Send an optional `Idempotency-Key` to retry safely. The same key and request return the original refinement and its current status without another charge. Reusing a key with different inputs returns 409. Keys are scoped to your account and job and retained with the refinement record. After a terminal failure, use a new key for a new attempt. Version numbers may have gaps after failed attempts. operationId: refineMask parameters: - name: id in: path required: true schema: type: string format: uuid description: Completed job ID to refine - name: Idempotency-Key in: header required: false description: Unique request key; reuse only when retrying the same operation. schema: type: string minLength: 1 maxLength: 128 pattern: ^[\x21-\x7e]+$ requestBody: required: true content: application/json: schema: type: object required: - prompt properties: op: type: string enum: - add - subtract default: add description: Fuse mode — union (add) or difference (subtract) model: type: string enum: - videobgremover-pro - videobgremover-original default: videobgremover-pro description: Segmentation model (must support text prompts) prompt: type: object required: - text properties: mode: type: string enum: - text default: text text: type: string maxLength: 500 description: Concept to (re)segment, e.g. "the left hand" edge_cleanup: type: object description: >- Optional VideoMaMa soft-alpha edge refinement on the fused mask (smooths the union seam). Same engine as edge_cleanup on the direct removal flow. properties: enabled: type: boolean default: false size: type: integer minimum: 128 maximum: 1024 default: 512 description: Processing-resolution cap (longest edge), divisible by 8 example: op: add model: videobgremover-pro prompt: mode: text text: the left hand edge_cleanup: enabled: true size: 512 responses: '200': description: >- Persisted refinement and its current status (including terminal status on replay) content: application/json: schema: type: object properties: refinement_id: type: string format: uuid job_id: type: string format: uuid status: type: string example: queued op: type: string model: type: string version: type: integer credits_used: type: integer created_at: type: string format: date-time example: refinement_id: 7b1c3f2e-9a4d-4c1b-8e2f-0a1b2c3d4e5f job_id: 550e8400-e29b-41d4-a716-446655440000 status: queued op: add model: sam3 version: 2 credits_used: 30 created_at: '2026-06-28T12:00:00.000Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': description: Insufficient credits content: application/json: schema: $ref: 9260d07e-02e9-4ce8-8568-ca594463f0aa example: error: Insufficient credits '404': description: Job not found or does not belong to user content: application/json: schema: $ref: 9260d07e-02e9-4ce8-8568-ca594463f0aa '409': description: >- Another refinement is in progress, the active mask changed, or the key was reused with different inputs content: application/json: schema: $ref: 9260d07e-02e9-4ce8-8568-ca594463f0aa '500': $ref: '#/components/responses/InternalError' components: responses: BadRequest: description: Bad request - Invalid parameters content: application/json: schema: $ref: '#/components/schemas/APIError' examples: invalid_background: summary: Invalid background color value: error: >- Invalid background color format. Must be hex color like #FF0000 missing_params: summary: Missing required parameters value: error: Must provide either (filename + content_type) OR video_url Unauthorized: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/APIError' example: error: Invalid API key InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' example: error: Internal server error schemas: APIError: type: object properties: error: type: string description: Error message details: type: string description: Additional error details securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Api-Key description: API key with format `vbr_` followed by 32 characters ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.