API-Referenz

vtn "$VTN_API_BASE/api/v1/account"

{
  "plan": "basic",
  "eligible": true,
  "remaining_seconds": 64800,
  "allowance_expires_at": 1792886400,
  "capabilities": {
    "api_admission_enabled": true,
    "key_creation_enabled": true,
    "server_upload_enabled": true,
    "long_jobs": true,
    "formats": [
      "mp4", "m4v", "mov", "webm", "mkv", "ogv", "avi", "wmv", "asf",
      "flv", "mpg", "mpeg", "vob", "ts", "mts", "m2ts", "3gp", "3g2",
      "mxf", "mp3", "m4a", "aac", "wav", "flac", "ogg", "oga", "opus",
      "wma", "amr", "aiff", "aif", "caf", "ac3"
    ],
    "audio_languages": [
      "auto", "af", "am", "ar", "hy", "az", "be", "bn", "bs", "bg", "my",
      "ca", "zh", "hr", "cs", "da", "nl", "en", "et", "tl", "fi", "fr",
      "gl", "ka", "de", "el", "gu", "ha", "he", "hi", "hu", "is", "id",
      "it", "ja", "kn", "kk", "km", "ko", "lv", "lt", "mk", "ms", "ml",
      "mt", "mr", "mn", "ne", "no", "fa", "pl", "pt", "pa", "ro", "ru",
      "sr", "sk", "sl", "es", "sw", "sv", "ta", "te", "th", "tr", "uk",
      "uz", "vi"
    ],
    "notes_languages": [
      "auto", "af", "am", "ar", "hy", "az", "be", "bn", "bs", "bg", "my",
      "ca", "zh", "hr", "cs", "da", "nl", "en", "et", "tl", "fi", "fr",
      "gl", "ka", "de", "el", "gu", "ha", "he", "hi", "hu", "is", "id",
      "it", "ja", "kn", "kk", "km", "ko", "lv", "lt", "mk", "ms", "ml",
      "mt", "mr", "mn", "ne", "no", "fa", "pl", "pt", "pa", "ro", "ru",
      "sr", "sk", "sl", "es", "sw", "sv", "ta", "te", "th", "tr", "uk",
      "uz", "vi"
    ],
    "download_formats": ["transcript_txt", "notes_md", "notes_html", "notes_pdf"],
    "email_opt_in": false,
    "limits": {
      "max_upload_bytes": 8589934592,
      "max_selection_seconds": null,
      "active_jobs": 1,
      "active_uploads": 1,
      "daily_uploads": 10,
      "daily_upload_bytes": 21474836480,
      "new_requests_per_minute": 12,
      "read_requests_per_minute": 60,
      "poll_after_seconds": 5,
      "result_page_bytes": 1000000,
      "result_page_items": 32,
      "upload_url_seconds": 900,
      "download_url_seconds": 600,
      "result_retention_seconds": 86400,
      "recovery_retention_seconds": 172800,
      "idempotency_retention_seconds": 34560000
    }
  }
}

vtn -X POST "$VTN_API_BASE/api/v1/uploads" \
  -H "Content-Type: application/json" \
  -d '{
    "byte_size": 1048576,
    "extension": "mp4"
  }'

{
  "upload_id": "upload-1",
  "state": "created",
  "expires_at": 1792807200,
  "part_size": 16777216,
  "part_count": 1,
  "error": null
}

vtn -X POST "$VTN_API_BASE/api/v1/uploads/upload-1/parts" \
  -H "Content-Type: application/json" \
  -d '{
    "part_numbers": [1]
  }'

{
  "upload_id": "upload-1",
  "targets": [
    {
      "part_number": 1,
      "url": "https://example.invalid/signed",
      "expires_at": 1792800900
    }
  ]
}

# PART_URL comes from the parts response; send no Authorization header.
curl -s --upload-file part-0001.bin --dump-header - --output /dev/null \
  "$PART_URL" | grep -i '^etag:'

vtn -X POST "$VTN_API_BASE/api/v1/uploads/upload-1/complete" \
  -H "Content-Type: application/json" \
  -d '{
    "parts": [
      {
        "part_number": 1,
        "etag": "opaque-etag"
      }
    ]
  }'

{
  "upload_id": "upload-1",
  "state": "uploaded",
  "expires_at": 1792807200,
  "part_size": 16777216,
  "part_count": 1,
  "error": null
}

vtn "$VTN_API_BASE/api/v1/uploads/upload-1"

{
  "upload_id": "upload-1",
  "state": "uploaded",
  "expires_at": 1792807200,
  "part_size": 16777216,
  "part_count": 1,
  "error": null
}

vtn -X POST "$VTN_API_BASE/api/v1/uploads/upload-1/abort" \
  -H "Content-Type: application/json" \
  -d '{}'

vtn -X POST "$VTN_API_BASE/api/v1/jobs" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "upload_id": "upload-1",
    "range": {
      "start_seconds": 5,
      "end_seconds": 60
    },
    "audio_language": null,
    "notes_language": "en"
  }'

{
  "job_id": "job-1",
  "state": "preparing",
  "stage": "probe",
  "created_at": 1792800000,
  "expires_at": 1792807200,
  "result_expires_at": null,
  "idempotency_expires_at": 1827360000,
  "poll_after_seconds": 5,
  "status_url": "/api/v1/jobs/job-1",
  "result_url": "/api/v1/jobs/job-1/result",
  "completed_units": 0,
  "total_units": null,
  "charged_seconds": 0,
  "result_available": false,
  "can_resume": false,
  "warnings": [],
  "error": null
}

vtn "$VTN_API_BASE/api/v1/jobs/job-1"

{
  "job_id": "job-1",
  "state": "completed",
  "stage": "terminal",
  "created_at": 1792800000,
  "expires_at": 1792807200,
  "result_expires_at": 1792886400,
  "idempotency_expires_at": 1827360000,
  "poll_after_seconds": 5,
  "status_url": "/api/v1/jobs/job-1",
  "result_url": "/api/v1/jobs/job-1/result",
  "completed_units": 8,
  "total_units": 8,
  "charged_seconds": 1140,
  "result_available": true,
  "can_resume": false,
  "warnings": [],
  "error": null
}

vtn -X POST "$VTN_API_BASE/api/v1/jobs/job-1/cancel" \
  -H "Content-Type: application/json" \
  -d '{}'

vtn -X POST "$VTN_API_BASE/api/v1/jobs/job-1/resume" \
  -H "Content-Type: application/json" \
  -d '{}'

vtn --get "$VTN_API_BASE/api/v1/jobs/job-1/result" \
  --data-urlencode "cursor=$NEXT_CURSOR"   # omit for the first page

{
  "job_id": "job-1",
  "snapshot": "generation-1",
  "items": [
    {
      "index": 0,
      "kind": "transcript",
      "text": "Welcome to the weekly planning meeting.",
      "segments": [
        {
          "text": "Welcome to the weekly planning meeting.",
          "start_seconds": 0,
          "end_seconds": 4.2,
          "timing_quality": "approximate",
          "timing_method": "provider_segment"
        }
      ]
    },
    {
      "index": 0,
      "kind": "notes",
      "text": "## Summary\n\nThe team agreed on the launch plan.\n\n## Key points\n\n- Launch moves to Monday."
    }
  ],
  "next_cursor": "opaque-account-bound-cursor",
  "artifacts": [
    {
      "format": "notes_md",
      "url": "https://example.invalid/signed-notes",
      "expires_at": 1792800600
    }
  ],
  "charged_seconds": 1140,
  "partial": false,
  "expires_at": 1792886400
}