ZiB Network

<script src="https://app.zibnetwork.com/sdk/zib-sdk.js"></script>

Authorization: Bearer <access_key>:<secret_key>

// Server: initiate the upload (credentials stay on your server)
const initRes = await fetch('https://api.zibnetwork.com/v1/api/upload/initiate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ZIB_ACCESS_KEY}:${process.env.ZIB_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    bucket: 'my-bucket',
    key: 'videos/intro.mp4',
    file_size: fileBuffer.length,
    content_type: 'video/mp4',  // forwarded to the CDN's Content-Type header
  }),
});
const registration = await initRes.json();
// registration = { type, file_id, upload_url?, upload_id?, ... }
// (Additional opaque fields are returned — pass the entire object straight to the SDK.)

// Return 'registration' to the browser for ZiBStorage.uploadDirect()
// or use the SDK on the server side if you need a non-browser upload path.

import requests

headers = {"Authorization": f"Bearer {ZIB_ACCESS_KEY}:{ZIB_SECRET_KEY}"}

# List buckets
buckets = requests.get("https://s3.zibnetwork.com/s3/", headers=headers)

# List objects
objects = requests.get("https://s3.zibnetwork.com/s3/my-bucket", headers=headers)

# Start encoding
res = requests.post(
    "https://api.zibnetwork.com/v1/api/encoding/jobs",
    headers={**headers, "Content-Type": "application/json"},
    json={"object_key": file_id, "transcription": "recommended"},
)
job = res.json()  # { encoding_id, status, progress, ... }

{
  "encode": true,
  "transcription": "fastest" | "recommended" | "accurate",
  "vision": "standard" | "hq",
  "webhook_url": "https://yourapp.com/api/zib-pipeline-event",
  "webhook_secret": "whsec_..."
}

// server route — e.g. /api/upload-initiate
const res = await fetch('https://api.zibnetwork.com/v1/api/upload/initiate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${ACCESS_KEY}:${SECRET_KEY}`,
  },
  body: JSON.stringify({
    bucket: 'video',
    key: `videos/${contentId}/${videoType}-${Date.now()}-${fileName}`,
    file_size: fileSize,
    pipeline: {
      encode: true,
      transcription: 'recommended',
      vision: 'standard',
      webhook_url: 'https://yourapp.com/api/zib-pipeline-event',
      webhook_secret: process.env.WEBHOOK_SECRET,
    },
  }),
})

const registration = await res.json()
// Return registration to browser — credentials stay on the server
return Response.json(registration)

{
  "file_id": "a1b2c3d4-...",
  "status": "ai_processing",
  "cdn_url": "https://cdn.zibnetwork.com/objects/a1b2c3d4-...",
  "declared": { "encode": true, "transcription": "recommended", "vision": "standard" },
  "stages": {
    "upload":        { "status": "complete",
                       "phase": "distributed",
                       "replication_safe_at": null },
    "encoding":      { "status": "completed", "encoding_id": "...", "progress": 100,
                       "hls_manifest_url": "https://cdn.zibnetwork.com/...m3u8",
                       "dash_manifest_url": "https://cdn.zibnetwork.com/...mpd" },
    "transcription": { "status": "running", "tier": "recommended", "progress": 40,
                       "output_file_id": null },
    "vision":        { "status": "queued", "tier": "standard", "progress": 0,
                       "output_file_id": null }
  },
  "error": null
}

// Server-side only — your master Bearer credentials never reach the browser.
const res = await fetch('https://api.zibnetwork.com/v1/api/upload/pin/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.ZIB_ACCESS_KEY}:${process.env.ZIB_SECRET_KEY}`,
  },
  body: JSON.stringify({
    bucket: 'video',
    key: 'videos/abc-123/main.mp4',
    pipeline: {
      encode: true,
      webhook_url: 'https://yourapp.com/api/zib-webhook',
      webhook_secret: process.env.ZIB_WEBHOOK_SECRET,
    },
  }),
});

const { pin, session_id, expires_at } = await res.json();
// pin → "mosaic-trinket-blanket"
// session_id → "5a6b862f-9bb6-4c5a-b5f3-df22bb9da959"
// expires_at → "2026-04-10T15:47:03Z"  (24 hours from creation)

// Poll until phase is 'ready' or 'failed'. The status endpoint returns
// a full lifecycle rollup so you can render byte-level upload progress,
// then encoding %, then analysis %, all from the same poll.
async function waitForCompletion(sessionId, onProgress) {
  while (true) {
    const res = await fetch(
      `https://api.zibnetwork.com/v1/api/upload/pin/status/${sessionId}`,
      {
        headers: { 'Authorization': `Bearer ${ACCESS_KEY}:${SECRET_KEY}` },
      }
    );
    const s = await res.json();

    // Surface live progress to the UI. `phase` walks through:
    //   pending → redeemed → uploading → encoding → analyzing → ready
    // Each phase populates its own sub-block (defensive read with ?? null
    // so you don't break if a future phase is added).
    onProgress?.({
      phase: s.phase,
      uploadPercent:    s.upload?.progress_percent      ?? null,
      encodingPercent:  s.encoding?.progress_percent    ?? null,
      analysisStage:    s.analysis?.current_stage       ?? null,
      transcriptionPct: s.analysis?.transcription_progress ?? null,
      visionPct:        s.analysis?.vision_progress     ?? null,
    });

    if (s.phase === 'ready')   return { file_id: s.file_id };
    if (s.phase === 'failed' || s.phase === 'expired') {
      throw new Error(`Upload ${s.phase}: ${s.error_message ?? 'no detail'}`);
    }

    await new Promise(r => setTimeout(r, 2000));  // poll every 2s
  }
}

{
  // Top-level rollup
  "phase": "encoding",                      // pending | redeemed | uploading | encoding | analyzing | ready | failed | expired
  "status": "uploading",                    // legacy field — keep reading 'phase' instead
  "redeemed_by_node_id": "ZB-899233",
  "file_id": "0c8e3765-9b2b-4a29-82cb-2f1911fe750c",
  "file_size_bytes": 1823450000,
  "error_message": null,
  "expires_at": "2026-04-15T15:47:03Z",

  // Populated while phase === "uploading" (omitted if no progress
  // report has landed in the last 30 seconds — node may have stalled)
  "upload": {
    "bytes_uploaded": 412300123,
    "total_bytes": 1823450000,
    "progress_percent": 22.6
  },

  // Populated when the pipeline declares encode: true
  "encoding": {
    "status": "encoding",                   // queued | encoding | complete | failed
    "progress_percent": 47.3
  },

  // Populated when the pipeline declares transcription and/or vision.
  // current_stage tracks the slowest path so a single bar reflects the
  // overall analysis progress.
  "analysis": {
    "current_stage": "transcription",       // "transcription" | "vision"
    "transcription_status": "running",      // null if not declared
    "transcription_progress": 42,           // 0–100, null if not declared
    "vision_status": "queued",              // null if not declared
    "vision_progress": 0                    // 0–100, null if not declared
  }
}

// After uploadDirect() completes, pass file_id to startEncoding
const job = await storage.startEncoding(result.file_id);
console.log(job.encoding_id); // use this to poll status

// Poll until complete
const status = await storage.getEncodingStatus(job.encoding_id);
// status.hls_manifest_url — adaptive stream, ready to play
// status.dash_manifest_url — DASH manifest for alternative players

// Webhook handler — store the progress value, render in your UI
app.post('/api/zib-webhook', (req, res) => {
  const { event, file_id, progress, stage } = req.body;

  if (event === 'encoding.progress') {
    // progress is an integer 0–100
    // stage is "encoding" or "sharding"
    await db.update('videos', { encoding_progress: progress }, { where: { file_id } });
  }

  if (event === 'encoding.complete') {
    // Final state — manifest URLs are now live
    await db.update('videos', {
      encoding_progress: 100,
      encoding_status: 'complete',
      hls_url: req.body.hls_manifest_url,
    }, { where: { file_id } });
  }

  res.sendStatus(200);
});

<!-- hls.js (browser) -->
<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
<video id="video" controls></video>
<script>
  const hls = new Hls();
  hls.loadSource('https://cdn.zibnetwork.com/stream/<file_id>/master.m3u8');
  hls.attachMedia(document.getElementById('video'));
</script>

<!-- Native HLS (Safari / iOS) -->
<video controls src="https://cdn.zibnetwork.com/stream/<file_id>/master.m3u8"></video>

Content-Type:    application/json
X-ZiB-Event:     <event name>            e.g. encoding.complete
X-ZiB-Job-ID:    <uuid>                  on encoding.* and {transcription,vision}.complete
X-ZiB-Signature: sha256=<hex>            HMAC-SHA256 over the raw request body

// file.ready — fired the moment shard count reaches the redundancy target
{
  "event":       "file.ready",
  "file_id":     "a1b2c3d4-...",
  "bucket":      "my-bucket",
  "object_key":  "videos/2026-04/film.mp4",
  "size_bytes":  524288000,
  "customer_id": "c0ffee...",
  "timestamp":   "2026-04-08T17:30:00.000Z"
}

// encoding.queued | encoding.started | encoding.sharding | encoding.complete | encoding.failed
// All five share the same shape — only the "event" and "status" fields change.
{
  "event":               "encoding.complete",
  "job_id":              "<encoding_jobs.id>",
  "status":              "complete",          // queued | encoding | sharding | complete | failed
  "file_id":             "a1b2c3d4-...",
  "customer_id":         "c0ffee...",
  "hls_manifest_url":    "https://cdn.zibnetwork.com/<file_id>/master.m3u8",  // null until "complete"
  "dash_manifest_url":   "https://cdn.zibnetwork.com/<file_id>/manifest.mpd", // null until "complete"
  "error_message":       null,                // populated on "failed"
  "transcription_model": "recommended",       // null if transcription not requested
  "vision_model":        "standard",          // null if vision not requested
  "timestamp":           "2026-04-08T17:32:14.000Z"
}

// encoding.progress — throttled mid-encode update
// Fires periodically while encoding is running so your UI can render a real
// progress bar instead of sitting at 0% from encoding.started until
// encoding.complete. Throttle policy: at most every 10s OR every 5% delta,
// whichever comes first. Idempotent — replays of the same percent are safe.
//
// You don't need this event to know the job will eventually finish — the
// existing encoding.complete event still fires. encoding.progress is purely
// for UI feedback.
{
  "event":     "encoding.progress",
  "job_id":    "<encoding_jobs.id>",
  "file_id":   "a1b2c3d4-...",
  "progress":  47,                 // integer 0–100
  "stage":     "encoding",         // "encoding" | "sharding"
  "timestamp": "2026-04-08T17:31:08.000Z"
}

// transcription.complete — fires when the SRT/WebVTT artefact has been
// produced and stored. Fetch via https://cdn.zibnetwork.com/objects/<srt_file_id>
{
  "event":        "transcription.complete",
  "job_id":       "<encoding_jobs.id OR compute_jobs.id>",
  "file_id":      "a1b2c3d4-...",
  "srt_file_id":  "f00d...",
  "timestamp":    "2026-04-08T17:34:02.000Z"
}

// vision.complete — fires when the ZibSidecar JSON has been produced and
// stored. Fetch via https://cdn.zibnetwork.com/objects/<sidecar_file_id>
// and parse as JSON for the full sidecar (scenes, IAB categories, etc.).
{
  "event":            "vision.complete",
  "job_id":           "<encoding_jobs.id OR compute_jobs.id>",
  "file_id":          "a1b2c3d4-...",
  "sidecar_file_id":  "ba11...",
  "timestamp":        "2026-04-08T17:36:48.000Z"
}

import crypto from 'crypto';

export async function POST(req) {
  // Read raw body before JSON parsing — signature is over raw bytes
  const body = await req.text();
  const sig = req.headers.get('x-zib-signature'); // "sha256=<hex>"

  const expected =
    'sha256=' +
    crypto
      .createHmac('sha256', process.env.ZIB_WEBHOOK_SECRET)
      .update(body)
      .digest('hex');

  if (sig !== expected) {
    return new Response('Unauthorized', { status: 401 });
  }

  const payload = JSON.parse(body);

  if (payload.event === 'file.ready') {
    // update your DB with cdn_url, mark upload complete, etc.
  }

  if (payload.event === 'encoding.complete') {
    // store hls_manifest_url, notify your users, etc.
  }

  return new Response('OK');
}

curl -s https://api.zibnetwork.com/v1/api/my-jobs \
  -H "Authorization: Bearer ${ACCESS_KEY}:${SECRET_KEY}"

# Filter:
curl -s "https://api.zibnetwork.com/v1/api/my-jobs?status=all" \
  -H "Authorization: Bearer ${ACCESS_KEY}:${SECRET_KEY}"

{
  "jobs": [
    {
      "file_id": "0c8e3765-9b2b-4a29-82cb-2f1911fe750c",
      "title": "trailer-final.mp4",
      "phase": "replicating",
      "phase_progress_pct": 66.7,
      "phase_detail": "peer 2 of 3 verified",
      "phase_updated_at": "2026-04-24T05:12:04Z",
      "replication_peer_count": 2,
      "replication_target_count": 3,
      "replication_safe_at": null,
      "retry_count": 0,
      "last_error": null,
      "cancellable": true,
      "retriable": false,
      "created_at": "2026-04-24T04:58:12Z",
      "node_id": "ZB-899233"
    }
  ]
}

curl -X DELETE https://api.zibnetwork.com/v1/api/my-jobs/${FILE_ID} \
  -H "Authorization: Bearer ${ACCESS_KEY}:${SECRET_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"reason":"user_abandoned_upload"}'

curl -X POST https://api.zibnetwork.com/v1/api/my-jobs/${FILE_ID}/retry \
  -H "Authorization: Bearer ${ACCESS_KEY}:${SECRET_KEY}"

const { encoding_id } = await zib.startEncoding(fileId, {
  transcription: 'recommended',  // 'fastest' | 'recommended' | 'accurate'
  vision: 'standard'             // 'standard' | 'hq'
});

// Poll until complete
const status = await zib.getEncodingStatus(encoding_id);
// status.srt_file_id    → WebVTT file (auto-injected into HLS manifest)
// status.sidecar_file_id → ZibSidecar JSON

// Standalone transcription
const { job_id } = await zib.submitTranscription(fileId, 'recommended');

// Standalone vision AI
const { job_id } = await zib.submitVisionAI(fileId, 'standard');

// Poll job status
const result = await zib.getComputeStatus(job_id);
// result.status          → 'queued' | 'processing' | 'complete' | 'failed'
// result.srt_file_id     → WebVTT file ID (when complete)
// result.sidecar_file_id → ZibSidecar file ID (when complete)

// Get the sidecar CDN URL from job status
const status = await zib.getComputeStatus(job_id);
const sidecarUrl = zib.getCdnUrl(status.sidecar_file_id);

// Fetch and parse
const sidecar = await fetch(sidecarUrl).then(r => r.json());

// Key fields:
sidecar.scene_understanding.executive_summary        // 150-200 word summary
sidecar.content_classification.garm.brand_safety_score  // 0.0–1.0
sidecar.clip_suggestions[0].virality_score           // 0.0–1.0
sidecar.chapters_youtube_format                      // paste into YouTube description
sidecar.transcript.full_text                         // full transcript string
sidecar.transcript.segments[0].intent               // hook / payoff / cta / ...
sidecar.content_classification.iab_categories[0].name  // IAB 3.0 taxonomy