Skip to content

Getting Started

Prerequisites

  • Linux or macOS
  • Rust toolchain with edition 2024 support
  • FFmpeg available on PATH
  • Bento4 tools available on PATH, especially mp4fragment and mp4dash

Verify the external tools:

ffmpeg -version
mp4fragment
mp4dash

Build The Workspace

cargo build --workspace

Optional validation before first run:

cargo test --workspace --no-run

Configure The Service

The HTTP service loads config/service.toml by default. The checked-in default enables:

  • bind on 0.0.0.0:8080
  • local output sink at ./.artifacts/output
  • C2PA settings from config/c2pa/default_c2pa_sdk_settings.toml
  • media packager pipeline from config/media-packager/media_packager_pipeline.toml

To use a different config file, set SERVICE_CONFIG_PATH. To control log verbosity, set RUST_LOG (e.g. RUST_LOG=info).

See the Configuration Guide for the full runtime model, including S3 and feature-gated behavior.

Start The Service

cargo run -p service-http

To expose generated API docs:

cargo run -p service-http --features openapi
cargo run -p service-http --features "openapi scalar-docs"

To preview the docs site itself:

make docs-serve

First Requests

Health Probe

curl -i http://localhost:8080/v2/health

Expected result: HTTP 200 OK with an empty body.

Sign A Video Synchronously

curl -X POST http://localhost:8080/v2/sync/c2pa/video \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      {
        "type": "local_file_path",
        "path": "./tests/fixtures/video/mp4/video1.mp4"
      }
    ],
    "params": {},
    "output": {
      "type": "local",
      "name": "signed-videos"
    }
  }'

Example response:

{
  "job_id": "01234567-89ab-cdef-0123-456789abcdef",
  "status": "succeeded",
  "results": [
    {
      "input_index": 0,
      "status": "succeeded",
      "output_path": "./.artifacts/output/signed-videos/video1_c2pa.mp4"
    }
  ],
  "timing": {
    "queued_at": "2026-04-09T08:00:00Z",
    "started_at": "2026-04-09T08:00:01Z",
    "finished_at": "2026-04-09T08:00:05Z"
  }
}

Submit An Async Job And Poll It

curl -X POST http://localhost:8080/v2/c2pa/video \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      {
        "type": "remote_file_url",
        "url": "https://example.com/video.mp4",
        "filename_hint": "video.mp4"
      }
    ],
    "params": {}
  }'

Response:

{
  "job_id": "01234567-89ab-cdef-0123-456789abcdef",
  "status": "queued"
}

Poll the job:

curl http://localhost:8080/v2/jobs/01234567-89ab-cdef-0123-456789abcdef

Package A Publication

curl -X POST http://localhost:8080/v2/sync/package \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      {
        "type": "local_folder_path",
        "path": "./tests/fixtures/video/mp4"
      }
    ],
    "params": {},
    "output": {
      "type": "local",
      "name": "publications"
    }
  }'

Feature-Gated Capabilities

OpenAPI And Scalar

  • --features openapi exposes /openapi.json
  • --features "openapi scalar-docs" additionally exposes /docs

S3

cargo run -p service-http --features s3

Enables:

  • s3://... remote inputs through remote_file_url and remote_folder_url
  • request-selected S3 outputs through output.type = "s3"

If S3 config is present in config/service.toml but the binary is built without the s3 feature, startup fails. See Running With S3 for the full setup.

Common Issues

ffmpeg Or mp4fragment Not Found

Install the external tools and ensure they are on PATH.

Health Check Fails

Confirm the service is listening on the configured bind address:

curl -i http://localhost:8080/v2/health

Sync Request Times Out Or Request Body Too Large

See Troubleshooting for the config fields to adjust.

Next Steps