API Key Guide

Overview

This guide explains how to obtain and use a DeepMark API key to authenticate your requests.

Authentication Header

All API calls must include:

X-Client-Api-Key: <your-api-key>

Base URL

https://<your-deepmark-domain>

Getting an API Key

Generate your API key from the DeepMark Web App → API Key page.

1. The key is shown only once when generated or regenerated.
2. Regenerating a key immediately invalidates the previous key.
3. Store the key securely and never expose it publicly.

Discover Allowed Models

Endpoint

GET /client/models

Example: List all models

curl -sS "https://<your-deepmark-domain>/client/models" \
  -H "X-Client-Api-Key: <your-api-key>"

Example: Filter by model name

curl -sS "https://<your-deepmark-domain>/client/models?name=<model-name>" \
  -H "X-Client-Api-Key: <your-api-key>"

Example Response

[
  {
    "_id": "67f123...",
    "name": "model-a",
    "version": "1.0.0",
    "type": "video",
    "is_default": true,
    "description": "...",
    "max_watermark_length": 256,
    "min_watermark_length": 32,
    "default_watermarks": []
  }
]

Use the name and version from this response when calling embed or detect.

Submit Embed Job

Endpoint

POST /client/embed
Content-Type: multipart/form-data

Required Fields

Example Request

curl -sS -X POST "https://<your-deepmark-domain>/client/embed" \
  -H "X-Client-Api-Key: <your-api-key>" \
  -F "file=@/path/to/input.file" \
  -F "watermark=10101010" \
  -F "model=model-id"

Example Response

{
  "job_id": "2d6a6f2f-....",
  "status": "started"
}

Submit Detection Job

Endpoint

POST /client/detect
Content-Type: multipart/form-data

Required Fields

Example Request

curl -sS -X POST "https://<your-deepmark-domain>/client/detect" \
  -H "X-Client-Api-Key: <your-api-key>" \
  -F "file=@/path/to/input.file" \
  -F "model=model-id"

Example Response

{
  "job_id": "c0ab4f4f-....",
  "status": "started"
}

Download Job Result (Recommended: Presigned URL)

Endpoint

GET /client/inference-jobs/{job_id}/download?presign=1&disposition=attachment

Example: Request Presigned URL

curl -sS "https://<your-deepmark-domain>/client/inference-jobs/<job_id>/download?presign=1&disposition=attachment" \
  -H "X-Client-Api-Key: <your-api-key>"

Example Response

{
  "url": "https://s3...."
}

Download Using Presigned URL

curl -L "<presigned-url>" -o result.out

Notes

1. Presigned URLs are time-limited and short-lived
2. Use disposition=inline for browser or media playback behavior

Polling Pattern

Job processing is asynchronous.

Recommended flow

1. Submit job (embed or detect) and store the job ID
2. Poll:

   GET /client/inference-jobs/{job_id}/download?presign=1

3. If the job is not ready, API returns:

   400 Result not available yet

4. Retry after a few seconds until the result becomes available.

Common Errors

Security Best Practices

1. Never expose API keys in frontend or public code
2. Store keys in a secrets manager or backend environment variables
3. Rotate keys regularly
4. After regeneration, update all integrations immediately