API Reference

Overview

BitMind provides multiple API endpoints for different use cases, from consumer applications to enterprise-grade services. This document provides an overview of available APIs with complete OpenAPI specifications for detailed implementation.

📋 OpenAPI Specifications

Complete OpenAPI 3.0 specifications are available for all APIs:

View and interact with these specifications using Swagger UI or generate client SDKs using OpenAPI Generator.

API Categories

1. Subnet API (Oracle API)

  • Base URL: https://api.bitmind.ai/oracle/v1

  • Purpose: AI content detection services

  • Authentication: Bearer token (API key or JWT)

  • Rate Limits: API key users (based on subscription tier), JWT users (1 req/sec with burst)

2. Enterprise API

  • Base URL: https://enterprise.bitmind.ai

  • Purpose: Enterprise-grade detection services

  • Authentication: API key + OAuth 2.0

  • Rate Limits: 1,000-10,000+ requests/hour

API Overview

Subnet API (Oracle API)

The Subnet API provides AI content detection services with comprehensive image and video analysis capabilities. Key features include:

  • Image Detection: Multi-version processing with C2PA analysis

  • Video Detection: Frame-by-frame analysis with preprocessing

  • Video Preprocessing: Browser-compatible conversion and thumbnail generation

  • Upload Management: Presigned S3 URLs for large file uploads

For complete endpoint documentation, see the Subnet API OpenAPI Specification.

Enterprise API

The Enterprise API provides high-performance, enterprise-grade detection services with advanced features:

  • Health Monitoring: Service status and health checks

  • Image Inference: Binary and JSON-based image processing

  • Video Inference: Enterprise-grade video analysis

  • Batch Processing: Efficient multi-file processing

  • Privacy-Compliant: See Compliance & Privacy for details

For complete endpoint documentation, see the Enterprise API OpenAPI Specification.

Error Handling

Standard Error Response

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required field: image",
    "details": {
      "field": "image",
      "expected_type": "binary_data"
    },
    "request_id": "req_1234567890",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Common Error Codes

Code
Description
HTTP Status

INVALID_REQUEST

Malformed request

400

UNAUTHORIZED

Invalid authentication

401

FORBIDDEN

Insufficient permissions

403

NOT_FOUND

Resource not found

404

RATE_LIMITED

Rate limit exceeded

429

INTERNAL_ERROR

Server error

500

SERVICE_UNAVAILABLE

Service temporarily unavailable

503

Rate Limits

Subnet API (Oracle API)

  • API Key users: Rate limits based on subscription tier

  • JWT users: 1 request per second with burst allowance of 5 requests

  • Application-specific: Rate limits may vary based on the x-bitmind-application header

Enterprise API

  • Standard: 1,000 requests/hour

  • Enterprise: 10,000+ requests/hour

  • Custom: Negotiable for large deployments

cURL Examples

Oracle API - Image Detection

curl -X POST \
  -H "Authorization: Bearer your-api-key" \
  -H "x-bitmind-application: oracle-api" \
  -H "Content-Type: application/json" \
  -d '{"image": "https://example.com/image.jpg", "rich": true}' \
  "https://api.bitmind.ai/oracle/v1/34/detect-image"

Oracle API - Video Detection

curl -X POST \
  -H "Authorization: Bearer your-api-key" \
  -H "x-bitmind-application: oracle-api" \
  -H "Content-Type: multipart/form-data" \
  -F "[email protected]" \
  -F "rich=true" \
  "https://api.bitmind.ai/oracle/v1/34/detect-video"

Enterprise Batch Processing

curl -X POST \
  -H "Authorization: Bearer bm-enterprise-company-001" \
  -H "Content-Type: multipart/form-data" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]" \
  "https://enterprise.bitmind.ai/batch_image"

Large File Upload Workflow

The Subnet API has a 10MB limit for direct file uploads due to API Gateway restrictions. For larger files (up to 200MB), use the following workflow with presigned S3 URLs:

Overview

This three-step process allows you to upload large video files:

  1. Request a presigned S3 URL

  2. Upload your file directly to S3

  3. Process the video using the S3 URL

Step 1: Request Presigned Upload URL

Get a presigned S3 URL and credentials for uploading your file:

curl -X POST "https://api.bitmind.ai/oracle/v1/34/get-video-upload-url" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "video.mp4",
    "contentType": "video/mp4"
  }'

Response:

{
  "url": "https://applications-temp-videos-us-east-1.s3.us-east-1.amazonaws.com/",
  "fields": {
    "key": "temp/video-uuid.mp4",
    "Content-Type": "video/mp4",
    "bucket": "applications-temp-videos-us-east-1",
    "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
    "X-Amz-Credential": "...",
    "X-Amz-Date": "...",
    "X-Amz-Security-Token": "...",
    "Policy": "...",
    "X-Amz-Signature": "..."
  },
  "videoUrl": "https://applications-temp-videos-us-east-1.s3.us-east-1.amazonaws.com/temp/video-uuid.mp4"
}

Step 2: Upload to S3

Upload your file using the presigned URL and credentials from Step 1:

curl -X POST "YOUR_S3_URL" \
  -F "key=YOUR_S3_KEY" \
  -F "Content-Type=video/mp4" \
  -F "bucket=applications-temp-videos-us-east-1" \
  -F "X-Amz-Algorithm=AWS4-HMAC-SHA256" \
  -F "X-Amz-Credential=YOUR_CREDENTIAL" \
  -F "X-Amz-Date=YOUR_DATE" \
  -F "X-Amz-Security-Token=YOUR_TOKEN" \
  -F "Policy=YOUR_POLICY" \
  -F "X-Amz-Signature=YOUR_SIGNATURE" \
  -F "[email protected]"

Step 3: Process Video

Once uploaded, use the videoUrl from Step 1 to process your video:

curl -X POST "https://api.bitmind.ai/oracle/v1/34/detect-video" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video": "YOUR_VIDEO_URL",
    "rich": true,
    "startTime": 0,
    "endTime": 30,
    "fps": 30
  }'

Complete Bash Script Example

Click to expand complete bash script
#!/bin/bash

# Step 0: Set Configuration
YOUR_API_KEY="your_bitmind_api_key"
VIDEO_FILE="path_to_video.mp4"

# Display configuration for verification
echo "=== Configuration ==="
echo "API Key: $YOUR_API_KEY"
echo "Video File: $VIDEO_FILE"
echo ""

# Step 1: Get presigned URL and store response
echo "=== Step 1: Requesting presigned URL ==="
S3_RESPONSE=$(curl -s -X POST "https://api.bitmind.ai/oracle/v1/34/get-video-upload-url" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "'$(basename $VIDEO_FILE)'",
    "contentType": "video/mp4"
  }')

echo "S3 Response: $S3_RESPONSE"
echo ""

# Step 1.5: Extract variables from response
echo "=== Step 1.5: Extracting credentials ==="
S3_KEY=$(echo $S3_RESPONSE | jq -r '.fields.key')
S3_CREDENTIAL=$(echo $S3_RESPONSE | jq -r '.fields."X-Amz-Credential"')
S3_DATE=$(echo $S3_RESPONSE | jq -r '.fields."X-Amz-Date"')
S3_TOKEN=$(echo $S3_RESPONSE | jq -r '.fields."X-Amz-Security-Token"')
S3_POLICY=$(echo $S3_RESPONSE | jq -r '.fields.Policy')
S3_SIGNATURE=$(echo $S3_RESPONSE | jq -r '.fields."X-Amz-Signature"')
S3_URL=$(echo $S3_RESPONSE | jq -r '.url')
VIDEO_URL=$(echo $S3_RESPONSE | jq -r '.videoUrl')

# Display extracted variables for verification
echo "S3 Key: $S3_KEY"
echo "S3 URL: $S3_URL"
echo "Video URL: $VIDEO_URL"
echo ""

# Step 2: Upload to S3
echo "=== Step 2: Uploading video to S3 ==="
curl -X POST "$S3_URL" \
  -F "key=$S3_KEY" \
  -F "Content-Type=video/mp4" \
  -F "bucket=applications-temp-videos-us-east-1" \
  -F "X-Amz-Algorithm=AWS4-HMAC-SHA256" \
  -F "X-Amz-Credential=$S3_CREDENTIAL" \
  -F "X-Amz-Date=$S3_DATE" \
  -F "X-Amz-Security-Token=$S3_TOKEN" \
  -F "Policy=$S3_POLICY" \
  -F "X-Amz-Signature=$S3_SIGNATURE" \
  -F "file=@$VIDEO_FILE"

echo ""
echo "Upload complete!"
echo ""

# Step 3: Process video
echo "=== Step 3: Processing video ==="
curl -X POST "https://api.bitmind.ai/oracle/v1/34/detect-video" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video": "'$VIDEO_URL'",
    "rich": true,
    "startTime": 0,
    "endTime": 30,
    "fps": 30
  }'

Important Notes

  • File Size Limit: Maximum file size is 200MB (compared to 10MB for direct uploads)

  • Presigned URL Expiry: URLs expire in 15 minutes - complete all steps within this timeframe

  • Supported Formats: mp4, mov, avi, mkv, webm, wmv

  • Requirements: You'll need jq installed for JSON parsing in the bash script

  • File Location: Ensure your video file exists at the specified path

When to Use This Workflow

Use this workflow when:

  • Your video file exceeds 10MB

  • You need to upload files up to 200MB

  • You want more reliable uploads for large files

  • You're implementing a production application with large media files

For files under 10MB, you can use the direct upload method shown in the cURL examples above.

Best Practices

1. Authentication

  • Store API keys securely (environment variables, key management systems)

  • Never commit API keys to version control

  • Use different keys for different environments

  • Rotate keys regularly

2. Error Handling

  • Always check response status codes

  • Implement exponential backoff for retries

  • Log errors for debugging

  • Handle rate limits gracefully

3. Performance

  • Use batch endpoints for multiple files

  • Implement caching for repeated requests

  • Monitor API usage and limits

  • Use appropriate timeouts

4. Security

  • Validate input data before sending

  • Use HTTPS for all requests

  • Implement request signing where required

  • Monitor for suspicious activity

Resources

  • OpenAPI Specifications: See links above

  • For help, visit the Support page

For the most up-to-date API documentation, visit docs.bitmind.ai

PreviousAPI PricingNextAuthentication

Last updated