sudomock-com Background removal API

openapi: 3.2.0
info:
  title: SudoMock Background removal API
  description: 'Product mockup API. Render PSD templates, turn product photos into reusable mockups, create still images and videos, personalize text with fonts, and manage asynchronous jobs and signed webhooks.


    Every endpoint answers failures with the same envelope, so the status codes, the error_code values and the retry rule are documented once at https://sudomock.com/docs/errors rather than repeated per operation.'
  version: 1.0.0
servers:
- url: https://api.sudomock.com
  description: Production
tags:
- name: Background removal
  description: Isolate a subject from its background as a standalone step.
paths:
  /api/v1/remove-background:
    post:
      tags:
      - Background removal
      summary: Remove the background from an image
      description: Isolates the subject of an image onto a transparent background and returns a clean PNG cutout URL, ready to use as render artwork. Costs 25 credits per image; credits are refunded automatically if processing fails.
      operationId: remove_background_api_v1_remove_background_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BackgroundRemovalRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackgroundRemovalResponse'
      x-mint:
        metadata:
          sidebarTitle: Remove background
      security:
      - ApiKeyAuth: []
      x-codeSamples:
      - lang: Node.js
        source: "const response = await fetch(\"https://api.sudomock.com/api/v1/remove-background\", {\n  method: \"POST\",\n  headers: {\n    \"x-api-key\": \"sm_your_api_key\",\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"url\": \"https://example.com/product-photo.jpg\"\n  }),\n});\n\nconst data = await response.json();\nconsole.log(data);"
      - lang: PHP
        source: "<?php\n\n$payload = <<<'JSON'\n{\n  \"url\": \"https://example.com/product-photo.jpg\"\n}\nJSON;\n\n$ch = curl_init(\"https://api.sudomock.com/api/v1/remove-background\");\ncurl_setopt($ch, CURLOPT_CUSTOMREQUEST, \"POST\");\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\n    \"x-api-key: sm_your_api_key\",\n    \"Content-Type: application/json\",\n]);\ncurl_setopt($ch, CURLOPT_POSTFIELDS, $payload);\n\n$response = curl_exec($ch);\ncurl_close($ch);\n\necho $response;"
      - lang: Python
        source: "import requests\n\npayload = {'url': 'https://example.com/product-photo.jpg'}\n\nresponse = requests.post(\n    \"https://api.sudomock.com/api/v1/remove-background\",\n    headers={\"x-api-key\": \"sm_your_api_key\"},\n    json=payload,\n)\n\nresponse.raise_for_status()\nprint(response.json())"
      - lang: Ruby
        source: "require \"net/http\"\nrequire \"uri\"\n\nuri = URI(\"https://api.sudomock.com/api/v1/remove-background\")\nrequest = Net::HTTP::Post.new(uri)\nrequest[\"x-api-key\"] = \"sm_your_api_key\"\nrequest[\"Content-Type\"] = \"application/json\"\n\nrequest.body = <<~JSON\n  {\n    \"url\": \"https://example.com/product-photo.jpg\"\n  }\nJSON\n\nresponse = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|\n  http.request(request)\nend\n\nputs response.body"
      - lang: Go
        source: "package main\n\nimport (\n\t\"bytes\"\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n)\n\nfunc main() {\n\tpayload := []byte(`{\n  \"url\": \"https://example.com/product-photo.jpg\"\n}`)\n\n\treq, err := http.NewRequest(\"POST\", \"https://api.sudomock.com/api/v1/remove-background\", bytes.NewBuffer(payload))\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"x-api-key\", \"sm_your_api_key\")\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\n\tbody, _ := io.ReadAll(res.Body)\n\tfmt.Println(string(body))\n}"
      - lang: Java
        source: "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\n\nString payload = \"\"\"\n{\n  \"url\": \"https://example.com/product-photo.jpg\"\n}\n\"\"\";\n\nHttpRequest request = HttpRequest.newBuilder()\n    .uri(URI.create(\"https://api.sudomock.com/api/v1/remove-background\"))\n    .header(\"x-api-key\", \"sm_your_api_key\")\n    .header(\"Content-Type\", \"application/json\")\n    .POST(HttpRequest.BodyPublishers.ofString(payload))\n    .build();\n\nHttpResponse<String> response = HttpClient.newHttpClient()\n    .send(request, HttpResponse.BodyHandlers.ofString());\n\nSystem.out.println(response.body());"
      - lang: .NET
        source: "using System.Net.Http;\nusing System.Text;\n\nvar payload = \"\"\"\n{\n  \"url\": \"https://example.com/product-photo.jpg\"\n}\n\"\"\";\n\nvar request = new HttpRequestMessage(HttpMethod.Post, \"https://api.sudomock.com/api/v1/remove-background\");\nrequest.Headers.Add(\"x-api-key\", \"sm_your_api_key\");\nrequest.Content = new StringContent(payload, Encoding.UTF8, \"application/json\");\n\nvar client = new HttpClient();\nvar response = await client.SendAsync(request);\n\nConsole.WriteLine(await response.Content.ReadAsStringAsync());"
      - lang: cURL
        source: "curl -X POST \"https://api.sudomock.com/api/v1/remove-background\" \\\n  -H \"x-api-key: sm_your_api_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"url\": \"https://example.com/product-photo.jpg\"\n  }'"
components:
  schemas:
    BackgroundRemovalData:
      properties:
        url:
          type: string
          description: URL of the transparent-PNG cutout
        width:
          type: integer
          description: Cutout width in pixels
        height:
          type: integer
          description: Cutout height in pixels
        credits_charged:
          type: integer
          description: Credits charged for this operation
      type: object
      required:
      - url
      - width
      - height
      - credits_charged
      title: BackgroundRemovalData
      description: Result payload for POST /api/v1/remove-background.
    BackgroundRemovalRequest:
      properties:
        url:
          anyOf:
          - type: string
          - type: 'null'
          description: URL of the image to process (HTTP/HTTPS). Either url or base64 must be provided.
        base64:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Raw base64-encoded image bytes (no data: prefix). Either url or base64 must be provided.'
        content_type:
          anyOf:
          - type: string
            pattern: ^image/(png|jpeg|webp|gif)$
          - type: 'null'
          description: Optional. The file type is detected from the image itself, so this field can be left out.
        idempotency_key:
          anyOf:
          - type: string
            maxLength: 255
            minLength: 1
          - type: 'null'
          description: Retry-stable request identifier. Required in both this field and the Idempotency-Key header for Studio calls.
      additionalProperties: false
      type: object
      title: BackgroundRemovalRequest
      description: 'Body for POST /api/v1/remove-background.


        Image source priority mirrors AssetInput: base64 > url.'
      example:
        url: https://example.com/product-photo.jpg
    BackgroundRemovalResponse:
      properties:
        data:
          $ref: '#/components/schemas/BackgroundRemovalData'
          description: The cutout image, its dimensions and the credits charged.
        success:
          type: boolean
          description: Success status
          default: true
      type: object
      required:
      - data
      title: BackgroundRemovalResponse
      description: The cutout image and where to fetch it.
      example:
        data:
          credits_charged: 25
          height: 3000
          url: https://cdn.sudomock.com/mockup-assets/bg-cutouts/9c4e1a7f3b2d8e6045a1c93f7b20de84.png
          width: 2400
        success: true
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key with sm_ prefix. Get your key at https://sudomock.com/dashboard/api-keys