Bynn Intelligence Moderation API

openapi: 3.2.0
info:
  title: BYNN Moderation API
  description: 'The BYNN API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website’s client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects. To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no “switch” for changing between modes, just use the appropriate key to perform a live or test transaction. Requests made with test-mode credentials never hit live networks and incur no cost. **AUTHENTICATION:** Use your **Private API Key**, which looks like `private_xxxxxxxxxxxxxxxxxxxxxxxx` (or `private_sandbox_xxxxxxxxxxxxxxxxxxxxxxxx` for a sandbox key), as the username in HTTP Basic auth with an empty password, or send it as `Authorization: Bearer `. Your keys are at https://dashboard.bynn.com/integration.'
  termsOfService: https://bynn.com/terms
  contact:
    name: BYNN Development Team
    email: hello@bynn.com
    url: https://docs.bynn.com
  license:
    name: BYNN Documentation
    url: https://docs.bynn.com
  version: '1.0'
servers:
- url: https://api.bynn.com/v1
tags:
- name: Moderation
  description: Operations about moderations
paths:
  /moderation/models/all:
    get:
      summary: List all public moderation models (no auth required)
      description: Get all available moderation models across all types (image, video, audio, text) with public pricing
      responses:
        '200':
          description: List all public moderation models (no auth required)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_ModerationCategoryEntity'
      tags:
      - Moderation
      operationId: getModerationModelsAll
  /moderation/models/{api_name}:
    get:
      summary: Get a single moderation model with full documentation
      description: Get detailed information about a specific moderation model including full documentation
      parameters:
      - in: path
        name: api_name
        description: Model API name (e.g., nudity-detection)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Get a single moderation model with full documentation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_ModerationModelEntity'
      tags:
      - Moderation
      operationId: getModerationModelsApiName
  /moderation/infer:
    post:
      summary: Create a moderation inference
      description: Submit content for moderation using the specified model
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postModerationInfer'
        required: true
      security:
      - PrivateKey: []
      responses:
        '201':
          description: Create a moderation inference
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_InferenceEntity'
      tags:
      - Moderation
      operationId: postModerationInfer
  /moderation/infer_async:
    post:
      summary: Create an asynchronous moderation inference
      description: Submit content for moderation using the specified model. Returns 202 immediately; poll GET /moderation/inference/:token for the result. Billing happens at submit and is refunded automatically if processing fails.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postModerationInferAsync'
        required: true
      security:
      - PrivateKey: []
      responses:
        '201':
          description: Create an asynchronous moderation inference
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_InferenceEntity'
      tags:
      - Moderation
      operationId: postModerationInferAsync
  /moderation/inference/{token}:
    get:
      summary: Get inference result
      description: Retrieve the result of a moderation inference by token
      parameters:
      - in: path
        name: token
        description: The inference token (e.g., inf_abc123)
        required: true
        schema:
          type: string
      security:
      - PrivateKey: []
      responses:
        '200':
          description: Get inference result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_InferenceEntity'
      tags:
      - Moderation
      operationId: getModerationInferenceToken
components:
  schemas:
    Bynn_V1_Entities_ModerationModelEntity:
      type: object
      properties:
        id:
          type: string
          example: nudity_detection
          description: Unique model identifier
        api_name:
          type: string
          example: nudity-detection
          description: API name for model (hyphenated, used in API calls)
        name:
          type: string
          example: Nudity & Adult Content Detection
          description: Model display name
        description:
          type: string
          example: Detect nudity across 29 classes from very explicit to mildly suggestive
          description: Model description
        category:
          type: string
          example: Standard Moderation
          description: Model category
        moderation_type:
          type: string
          enum:
          - image
          - video
          - audio
          - text
          example: image
          description: Type of moderation (image, video, audio, text)
        icon:
          type: string
          example: shield-alert
          description: Lucide icon name for the model
        is_active:
          type: boolean
          example: true
          description: Whether the model is currently active
        accuracy:
          type: number
          example: 96.5
          description: Model accuracy percentage
        avg_response_time_ms:
          type: integer
          format: int32
          example: 150
          description: Average response time in milliseconds (calculated from last 10 completed inferences)
        pricing:
          type: object
          description: Pricing information
        all_plans_pricing:
          type: object
          description: Pricing information for all plan tiers (Trial, Core, Compliance, Forensic, Enterprise, Custom, Crypto)
        supported_formats:
          type: array
          items:
            type: array
            items: {}
          example:
          - jpg
          - png
          - gif
          - webp
          description: Supported file formats
        max_file_size_mb:
          type: integer
          format: int32
          example: 10
          description: Maximum file size in MB
        tags:
          type: array
          items:
            type: array
            items: {}
          example:
          - nsfw
          - adult-content
          - safety
          description: Model tags for filtering
        input_schema:
          type: object
          description: Input parameter schema from Triton model class
        output_schema:
          type: object
          description: Output field schema from Triton model class
        example_request:
          type: object
          description: Example API request parameters
        example_response:
          type: object
          description: Example API response
        require_plan:
          type: string
          enum:
          - trial
          - core
          - compliance
          - forensic
          - enterprise
          - custom
          - crypto
          example: core
          description: Minimum plan required to access this model
        sample_content:
          type: array
          example:
          - url: https://example.com/sample.jpg
            label: Sample image
          description: Sample content for testing (URLs for media, text for text models)
          items: {}
        version:
          type: integer
          format: int32
          example: 2601
          description: Model version number
        version_date:
          type: string
          example: '2026-01-03'
          description: Model version release date
        documentation_image_url:
          type: string
          example: https://cdn.example.com/model-docs/nudity-detection.webp
          description: Main documentation image URL
        has_documentation:
          type: boolean
          example: true
          description: Whether the model has documentation content
        documentation:
          type: string
          description: Rich text HTML documentation for the model
      required:
      - id
      - api_name
      - name
      - description
      - category
      - moderation_type
      - icon
      - is_active
      - accuracy
      - avg_response_time_ms
      - pricing
      - supported_formats
      - max_file_size_mb
      - tags
      - input_schema
      - output_schema
      - example_request
      - example_response
      - require_plan
      - sample_content
      - version
      - version_date
      - documentation_image_url
      - has_documentation
      description: Bynn_V1_Entities_ModerationModelEntity model
    postModerationInfer:
      type: object
      properties:
        model:
          type: string
          description: The model API name to use for moderation (e.g., nudity-detection, violence-detection)
        content:
          type: string
          description: Text content to moderate (for text models)
        image_url:
          type: string
          description: URL of the image to moderate (for image models)
        base64_image:
          type: string
          description: Base64-encoded image data (alternative to image_url)
        base64_pdf:
          type: string
          description: Base64-encoded PDF data (for OCR model, billed per page)
        video_url:
          type: string
          description: URL of the video to moderate (for video models)
        base64_video:
          type: string
          description: Base64-encoded video data (alternative to video_url)
        audio_url:
          type: string
          description: URL of the audio to moderate (for audio models)
        base64_audio:
          type: string
          description: Base64-encoded audio data (alternative to audio_url)
        metadata:
          type: object
          description: Additional metadata for the inference
        idempotency_key:
          type: string
          description: Idempotency key for request deduplication
        image_urls:
          type: array
          description: Array of image URLs (for batch image processing)
          items:
            type: string
        base64_images:
          type: array
          description: Array of base64-encoded images (for batch image processing)
          items:
            type: string
        fps:
          type: integer
          format: int32
          description: Frames per second to extract from video (1-10)
          minimum: 1
          maximum: 10
          default: 4
        distance_threshold:
          type: number
          format: float
          description: Face matching distance threshold (0.3-0.7, lower = stricter)
          default: 0.5
        extract_faces:
          type: boolean
          description: Extract cropped face PNG for best match
          default: false
      required:
      - model
      description: Create a moderation inference
    Bynn_V1_Entities_InferenceEntity:
      type: object
      properties:
        inference_id:
          type: string
          example: inf_abc123def456
          description: Unique inference identifier
        model_id:
          type: string
          example: nudity_detection
          description: The model used for this inference
        model_name:
          type: string
          example: Nudity & Adult Content
          description: The model display name
        moderation_type:
          type: string
          example: image
          description: Type of moderation (image, video, audio, text)
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
          example: completed
          description: Current status of the inference
        processing_mode:
          type: string
          enum:
          - sync
          - async
          example: sync
          description: 'How the inference is processed: sync (in-request) or async (queued, poll for result)'
        result:
          type: object
          description: The moderation result data. Inline result images (segmentation masks, face crops, redacted images) from async inferences are returned as presigned *_url fields, downloadable for up to 24 hours after completion.
        input_url:
          type: string
          example: https://example.com/image.jpg
          description: URL of the input file/content that was moderated, or indicator of base64 upload
        ip_address:
          type: string
          example: 192.168.1.1
          description: IP address from which the inference request originated
        response_time_ms:
          type: integer
          format: int32
          example: 150
          description: Response time in milliseconds
        error_message:
          type: string
          description: Error message if the inference failed
        created_at:
          type: string
          example: '2024-01-15T10:30:00Z'
          description: When the inference was created
        completed_at:
          type: string
          description: When the inference was completed
        duration_seconds:
          type: number
          example: 135.5
          description: Duration of the media file in seconds (for video/audio models)
        billable_quantity:
          type: integer
          format: int32
          example: 3
          description: Number of billable units (minutes for video/audio, images for batch)
        cost:
          type: string
          example: $0.00010
          description: Total cost of this inference (formatted with 5 decimals). Returns null for failed inferences.
      required:
      - inference_id
      - model_id
      - model_name
      - moderation_type
      - status
      - processing_mode
      - result
      - input_url
      - ip_address
      - response_time_ms
      - created_at
      - completed_at
      - duration_seconds
      - billable_quantity
      - cost
      description: Bynn_V1_Entities_InferenceEntity model
    Bynn_V1_Entities_ModerationCategoryEntity:
      type: object
      properties:
        name:
          type: string
          example: Standard Moderation
          description: Category name
        description:
          type: string
          example: Essential moderation models for detecting harmful content
          description: Category description
        icon:
          type: string
          example: shield
          description: Lucide icon name for the category
        models:
          type: array
          items:
            $ref: '#/components/schemas/Bynn_V1_Entities_ModerationModelEntity'
          description: Models in this category
      required:
      - name
      - description
      - icon
      - models
      description: Bynn_V1_Entities_ModerationCategoryEntity model
    postModerationInferAsync:
      type: object
      properties:
        model:
          type: string
          description: The model API name to use for moderation (e.g., nudity-detection, violence-detection)
        content:
          type: string
          description: Text content to moderate (for text models)
        image_url:
          type: string
          description: URL of the image to moderate (for image models)
        base64_image:
          type: string
          description: Base64-encoded image data (alternative to image_url)
        base64_pdf:
          type: string
          description: Base64-encoded PDF data (for OCR model, billed per page)
        video_url:
          type: string
          description: URL of the video to moderate (for video models)
        base64_video:
          type: string
          description: Base64-encoded video data (alternative to video_url)
        audio_url:
          type: string
          description: URL of the audio to moderate (for audio models)
        base64_audio:
          type: string
          description: Base64-encoded audio data (alternative to audio_url)
        metadata:
          type: object
          description: Additional metadata for the inference
        idempotency_key:
          type: string
          description: Idempotency key for request deduplication
        image_urls:
          type: array
          description: Array of image URLs (for batch image processing)
          items:
            type: string
        base64_images:
          type: array
          description: Array of base64-encoded images (for batch image processing)
          items:
            type: string
        fps:
          type: integer
          format: int32
          description: Frames per second to extract from video (1-10)
          minimum: 1
          maximum: 10
          default: 4
        distance_threshold:
          type: number
          format: float
          description: Face matching distance threshold (0.3-0.7, lower = stricter)
          default: 0.5
        extract_faces:
          type: boolean
          description: Extract cropped face PNG for best match
          default: false
      required:
      - model
      description: Create an asynchronous moderation inference
  securitySchemes:
    PrivateKey:
      type: apiKey
      name: Authorization
      in: header
      description: Enter your PRIVATE KEY token prefixed with `Bearer `, e.g. `Bearer your_token_here`
    PublicKey:
      type: apiKey
      name: Authorization
      in: header
      description: Enter your PUBLIC KEY token prefixed with `Bearer `, e.g. `Bearer your_token_here`