MetaGhost Desktop API
HTTP API for image and video processing with saved presets. Submit files, track jobs and retrieve results from any HTTP client, script or automation platform.
From connection to first result
Open MetaGhost Desktop, sign in and go to Settings > API. Enable the server, keep remote access disabled, generate a key if needed and Apply changes. Keep Desktop open. This guide targets Desktop 1.1.21, API contract 1.
curl.exe "http://127.0.0.1:3847/api/v1/health"{
"status": "ok",
"version": "1.1.21",
"apiVersion": "1",
"activeJobs": 0
}Create a basic local Spoof job using paths on the Desktop computer. Give each execution a unique Idempotency-Key and save it with the exact JSON body. Keep keys in an environment variable or secret store, never in URLs or shared examples.
POST http://127.0.0.1:3847/api/v1/jobs
Authorization: Bearer YOUR_LOCAL_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_WORKFLOW_RUN_ID
{
"operation": "spoof",
"filePath": "C:\\Media\\photo.jpg",
"outputFolder": "C:\\Media\\output",
"batchCount": 1
}A 202 response returns jobId. Save it, poll the job and inspect outcome, errors and artifacts before downloading. The Python 3.10+ and Node.js 22+ starters below use standard libraries, loopback only and a ten-minute polling deadline. They submit once and never overwrite an existing download.
$env:METAGHOST_API_KEY = Read-Host "MetaGhost API key"
python .\quickstart.py "C:\Media\photo.jpg" "C:\Media\output" ".\result.jpg"
# Or:
node .\quickstart.mjs "C:\Media\photo.jpg" "C:\Media\output" ".\result-2.jpg"Connection & access
The API runs inside Desktop at http://127.0.0.1:3847/api/v1 by default. Historical /api routes remain compatible aliases. Use the port displayed in Settings > API. Apply changes restarts the API and cancels active and queued jobs; completed outputs are kept.
Only GET /api/v1/health and /api/health are public. Other operations require Authorization: Bearer YOUR_LOCAL_API_KEY and an authorized MetaGhost account. Missing or invalid keys return 401, denied permissions 403, and temporarily unavailable account verification retryable 503. Existing keys are not rotated automatically; generated keys take effect after Apply changes.
GET http://127.0.0.1:3847/api/v1/capabilities
Authorization: Bearer YOUR_LOCAL_API_KEYFiles, presets & Drive
Choose filePath for one local file, files for several, driveInputFileIds for explicitly granted Drive files, or driveInputFolder for accessible children of a folder. Choose one source only. Local paths must be absolute and exist on the Desktop computer. File-producing jobs need an outputFolder or a supported Drive destination. Inspect /tools for each operation.
Supported images: JPG, JPEG, PNG, WebP, HEIC, BMP, TIFF. Supported videos: MP4, MOV, AVI, MKV, WebM, M4V. Operation-specific restrictions still apply.
POST /api/v1/upload accepts raw bytes with Content-Type: application/octet-stream and X-Filename. No multipart. Its response contains filePath, originalName and size; use filePath in the job. Maximum 500 MiB per file, 20 GiB retained storage, seven-day retention. Oversized input returns structured 413; exhausted storage returns 507.
GET /api/v1/presets returns saved image/video preset names. A mixed batch needs the same name in both lists. Omit preset for basic defaults; unsaved UI controls are not used. Paid diffusion or adversarial presets require confirmCredits: true. Only unchanged historical recipes on POST /api/jobs may retain approval after restoring their original API key.
Connect Drive in Desktop Settings and check GET /api/v1/drive/status. Desktop 1.1.21 accepts up to 250 explicit Picker-granted file IDs; granting a folder does not grant every child. Use folder IDs, not sharing URLs. A missing connection returns 412; inaccessible selections can fail separately. Downloader supports Drive output only; Probe and Risk Analyzer have no Drive output.
{
"operation": "spoof",
"driveInputFileIds": [
"YOUR_GRANTED_FILE_ID"
],
"driveOutputFolder": "YOUR_OUTPUT_FOLDER_ID"
}Inspect drive.uploadResult, confirmed receipts, errors, cancelled, uploadError and drive.recovery before declaring delivery successful. Retrieve Drive results from Drive; local API download returns 409. Recovery files can expire. The local starters intentionally reject Drive bodies.
Jobs, retries & results
After acceptance, retain jobId and inspect skipped. Drive counts may remain unknown until preflight. Poll every few seconds with a finite deadline: queued and processing are in progress; completed, failed and cancelled are terminal. completed may be partial. Check outcome, per-file errors and delivery results. progress.phase describes work, not a separate status.
GET http://127.0.0.1:3847/api/v1/jobs/YOUR_JOB_ID
Authorization: Bearer YOUR_LOCAL_API_KEYUse artifacts[].downloadUrl to select the correct output, including multi-file results. This relative URL resolves against the Desktop server origin. Batch index selects a result; artifact selects a file inside it. Probe, Risk Analyzer and Captions with reason: no_speech and charged: false may return no file.
Retry the same execution with the same Idempotency-Key and unchanged JSON body. Receipts survive restart and history clearing for 24 hours. A changed body returns 409 IDEMPOTENCY_CONFLICT. jobAvailable: false means the receipt prevents re-execution but history is unavailable. A new, expired or missing key can create a new job. Preserve the key when a submission response is lost.
DELETE /api/v1/jobs/{jobId} requests cancellation. Committed GPU work may finish first; completed outputs remain. Stopping your script does not cancel a job. GET /api/v1/jobs returns the latest 50 account jobs. History retains up to 100 terminal jobs for 24 hours. Restart marks interrupted work API_RESTARTED instead of resuming it. DELETE /api/v1/jobs clears finished history, preserving files and idempotency receipts.
Tools, credits & limits
Read GET /api/v1/tools and /api/v1/capabilities before automation. Check available, supported sources and destinations, Drive modes and pricing. Operations include spoof, probe, risk-analyzer, convert, reduce, short-maker, captions, download and conditionally available synthid. Use operation and its options; Short Maker requires an existing template from /short-maker/templates.
Captions and SynthID require confirmCredits: true; Downloader requires confirmExternalNetwork: true. For source-second Captions pricing, call POST /api/v1/captions/quote with a local filePath and optional language, then approve requiredLimit as options.maxCreditsPerVideo. The quote does not start paid processing. Drive files are quoted after download. Legacy runtimes may not offer quotes. There is no credit-balance API route.
Desktop 1.1.21 allows 250 Spoof inputs, 100 repetitions per file and 1,000 total output operations. Collage needs four distinct compatible inputs per media type and creates grouped outputs. Other operations do not support batchCount repetition and can have different input limits. Read limits.operations from /capabilities.
One API job processes at a time with up to 10 waiting jobs; active UI work can delay the queue. In 1.1.21 all JSON bodies are limited to 64 KiB. Uploads are limited to 500 MiB. Inspect capabilities for per-tool and storage limits.
Next update: prepared changes
The next build is planned to accept 1,000 explicit local/Drive inputs and 2 MiB of authenticated job JSON; other JSON endpoints retain 64 KiB. Removal of the old Spoof repetition/output quotas is also prepared. These changes are not part of Desktop 1.1.21. Check the installed build through /capabilities before sending larger jobs.
Network & automation
Any HTTP client or automation platform can call this API. 127.0.0.1 refers to the client machine or container. A remote or cloud client needs a reachable Desktop host over a private network or VPN; its localhost does not point to your computer. For an HTTPS proxy, terminate TLS and restrict source access. Never expose the Desktop HTTP port directly on the public internet.
Scheduling belongs to the calling application. Keep Desktop open, preserve the execution key and jobId, respect queue limits and use bounded polling. A whole-workflow retry with a new key can duplicate work. Recover using the original key and unchanged body. Do not follow redirects with credentials.
API reference
Base URL: http://127.0.0.1:3847/api/v1. Expand an endpoint for its headers, parameters, request body and responses. The OpenAPI 3.1 specification can be imported into HTTP clients or code generators.
GET/health
Check server health
No authentication
{
"responses": {
"200": {
"description": "Server is ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Health"
}
}
}
}
}
}GET/capabilities
Discover API version, compatibility, limits, and features
Authorization: Bearer YOUR_LOCAL_API_KEY
{
"responses": {
"200": {
"description": "Capabilities",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"apiVersion",
"routes",
"compatibility",
"limits",
"features"
],
"additionalProperties": true
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}GET/tools
Discover supported operations and their local, network, and credit requirements
Authorization: Bearer YOUR_LOCAL_API_KEY
{
"responses": {
"200": {
"description": "Tool operation catalogue",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"operations",
"submission"
],
"properties": {
"operations": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/ToolDefinition"
}
},
"submission": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}GET/presets
List image and video preset names
Authorization: Bearer YOUR_LOCAL_API_KEY
{
"responses": {
"200": {
"description": "Preset names",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image",
"video"
],
"properties": {
"image": {
"type": "array",
"items": {
"type": "string"
}
},
"video": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}GET/short-maker/templates
List safe built-in and custom Short Maker template summaries
Authorization: Bearer YOUR_LOCAL_API_KEY
{
"responses": {
"200": {
"description": "Available Short Maker templates",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"templates"
],
"properties": {
"templates": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ShortMakerTemplate"
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"503": {
"description": "Template catalogue is not available in this Desktop session",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}POST/captions/quote
Quote source-second transcription without starting processing or spending credits
Authorization: Bearer YOUR_LOCAL_API_KEY
Available on source-second runtimes. Legacy runtimes return LEGACY_PROTOCOL or QUOTE_UNAVAILABLE. Check the captions pricing catalogue first.
{
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"filePath"
],
"properties": {
"filePath": {
"type": "string"
},
"options": {
"type": "object",
"properties": {
"language": {
"enum": [
"",
"fr",
"en",
"es",
"de",
"it",
"pt",
"nl"
]
}
}
}
}
}
}
}
}
}{
"responses": {
"200": {
"description": "Current source quote; approve requiredLimit as options.maxCreditsPerVideo when creating a job",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"durationMs": {
"type": "number"
},
"units": {
"type": "integer"
},
"totalCredits": {
"type": "integer"
},
"newCredits": {
"type": "integer"
},
"requiredLimit": {
"type": "integer"
},
"priceModel": {
"type": "string"
},
"origin": {
"type": "string"
}
}
}
}
}
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"default": {
"description": "Invalid input, denied authorization or unavailable quote",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}POST/jobs
Create a spoof or Desktop tool job
Authorization: Bearer YOUR_LOCAL_API_KEY
{
"parameters": [
{
"$ref": "#/components/parameters/IdempotencyKey"
},
{
"$ref": "#/components/parameters/RequestId"
}
]
}{
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateJobRequest"
}
}
}
}
}{
"responses": {
"202": {
"description": "Job accepted, or an idempotent replay",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateJobResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"412": {
"$ref": "#/components/responses/PreconditionFailed"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"507": {
"$ref": "#/components/responses/StorageUnavailable"
}
}
}GET/jobs
List up to 50 recent jobs
Authorization: Bearer YOUR_LOCAL_API_KEY
{
"responses": {
"200": {
"description": "Job history and queue state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"jobs",
"queueLength",
"processing"
],
"properties": {
"jobs": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Job"
}
},
"queueLength": {
"type": "integer",
"minimum": 0
},
"processing": {
"type": "boolean"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}DELETE/jobs
Clear terminal jobs from local history
Authorization: Bearer YOUR_LOCAL_API_KEY
Clears terminal history. This is not a read operation.
{
"responses": {
"200": {
"description": "Number of cleared jobs",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"cleared"
],
"properties": {
"cleared": {
"type": "integer",
"minimum": 0
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}GET/jobs/{jobId}
Read job status, progress, outcome, and results
Authorization: Bearer YOUR_LOCAL_API_KEY
{
"parameters": [
{
"$ref": "#/components/parameters/JobId"
}
]
}{
"responses": {
"200": {
"description": "Current job state",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Job"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}DELETE/jobs/{jobId}
Cancel a queued or processing job
Authorization: Bearer YOUR_LOCAL_API_KEY
Cancels the selected job.
{
"parameters": [
{
"$ref": "#/components/parameters/JobId"
}
]
}{
"responses": {
"200": {
"description": "Job is cancelled",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"jobId",
"status"
],
"properties": {
"jobId": {
"type": "string"
},
"status": {
"const": "cancelled"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST/upload
Upload raw image or video bytes
Authorization: Bearer YOUR_LOCAL_API_KEY
{
"parameters": [
{
"name": "X-Filename",
"in": "header",
"required": true,
"schema": {
"type": "string",
"maxLength": 255
}
}
]
}{
"requestBody": {
"required": true,
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary",
"maxLength": 524288000
}
}
}
}
}{
"responses": {
"200": {
"description": "Upload retained for seven days",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"filePath",
"originalName",
"size"
],
"properties": {
"filePath": {
"type": "string"
},
"originalName": {
"type": "string"
},
"size": {
"type": "integer",
"minimum": 1,
"maximum": 524288000
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"415": {
"$ref": "#/components/responses/UnsupportedMediaType"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"507": {
"description": "Retained upload storage ceiling reached",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}GET/download/{jobId}
Download a completed output
Authorization: Bearer YOUR_LOCAL_API_KEY
{
"parameters": [
{
"$ref": "#/components/parameters/JobId"
},
{
"name": "index",
"in": "query",
"description": "Single job artifact index; legacy batch result index.",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
}
},
{
"name": "artifact",
"in": "query",
"description": "Batch only; selects a file inside the selected result.",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
}
}
]
}{
"responses": {
"200": {
"description": "Output bytes",
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}GET/drive/status
Check Desktop Google Drive readiness without exposing tokens
Authorization: Bearer YOUR_LOCAL_API_KEY
{
"responses": {
"200": {
"description": "Google Drive state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"clientConfigured",
"connected"
],
"properties": {
"clientConfigured": {
"type": "boolean"
},
"connected": {
"type": "boolean"
},
"email": {
"type": [
"string",
"null"
]
},
"scope": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}All schemas and reusable parameters
#/components/securitySchemes
bearerAuth
{
"type": "http",
"scheme": "bearer",
"bearerFormat": "MetaGhost API key"
}#/components/parameters
IdempotencyKey
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Unique visible ASCII value retained for 24 hours.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
}RequestId
{
"name": "X-Request-ID",
"in": "header",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 96
}
}JobId
{
"name": "jobId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^job-[A-Za-z0-9_-]+$"
}
}#/components/schemas
Health
{
"type": "object",
"required": [
"status",
"version",
"apiVersion",
"activeJobs"
],
"properties": {
"status": {
"const": "ok"
},
"version": {
"type": "string",
"description": "Desktop application version"
},
"apiVersion": {
"const": "1"
},
"activeJobs": {
"type": "integer",
"minimum": 0
}
}
}CreateJobRequest
{
"oneOf": [
{
"$ref": "#/components/schemas/SpoofJobRequest"
},
{
"$ref": "#/components/schemas/ProbeJobRequest"
},
{
"$ref": "#/components/schemas/RiskAnalyzerJobRequest"
},
{
"$ref": "#/components/schemas/ConvertJobRequest"
},
{
"$ref": "#/components/schemas/ReduceJobRequest"
},
{
"$ref": "#/components/schemas/ShortMakerJobRequest"
},
{
"$ref": "#/components/schemas/CaptionsJobRequest"
},
{
"$ref": "#/components/schemas/DownloadJobRequest"
},
{
"$ref": "#/components/schemas/SynthIdJobRequest"
}
]
}DriveInputFileIds
{
"type": "array",
"minItems": 1,
"maxItems": 250,
"description": "Explicit file IDs already granted through the Google Picker. Duplicates are processed once. Mutually exclusive with local input and driveInputFolder; Drive folder access does not grant every child file.",
"items": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{10,256}$"
}
}LocalOrDriveInput
{
"oneOf": [
{
"type": "object",
"required": [
"filePath"
],
"properties": {
"filePath": {
"type": "string",
"description": "Absolute local input path"
}
}
},
{
"type": "object",
"required": [
"files"
],
"properties": {
"files": {
"type": "array",
"minItems": 1,
"maxItems": 1000,
"items": {
"type": "string"
}
}
}
},
{
"type": "object",
"required": [
"driveInputFolder"
],
"properties": {
"driveInputFolder": {
"type": "string",
"maxLength": 512
}
}
},
{
"type": "object",
"required": [
"driveInputFileIds"
],
"properties": {
"driveInputFileIds": {
"$ref": "#/components/schemas/DriveInputFileIds"
}
}
}
]
}LocalOrDriveOutput
{
"oneOf": [
{
"type": "object",
"required": [
"outputFolder"
],
"properties": {
"outputFolder": {
"type": "string",
"description": "Absolute local output folder"
}
}
},
{
"type": "object",
"required": [
"driveOutputFolder"
],
"properties": {
"driveOutputFolder": {
"type": "string",
"maxLength": 512
}
}
}
]
}SpoofJobRequest
{
"type": "object",
"description": "At most 250 input files, 100 repetitions per file, and 1000 total operations. Other tool jobs have different limits; batchCount repetition is only supported for spoof.",
"additionalProperties": true,
"properties": {
"operation": {
"enum": [
"spoof"
],
"default": "spoof"
},
"confirmCredits": {
"type": "boolean",
"description": "Required true for diffusion/adversarial presets except an unchanged paid recipe approved during key migration on the historical /api/jobs route."
},
"filePath": {
"type": "string"
},
"files": {
"type": "array",
"minItems": 1,
"maxItems": 250,
"items": {
"type": "string"
}
},
"driveInputFolder": {
"type": "string",
"maxLength": 512
},
"driveInputFileIds": {
"$ref": "#/components/schemas/DriveInputFileIds"
},
"outputFolder": {
"type": "string"
},
"driveOutputFolder": {
"type": "string",
"maxLength": 512
},
"preset": {
"type": "string",
"maxLength": 128
},
"batchCount": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 1
}
},
"oneOf": [
{
"required": [
"filePath"
]
},
{
"required": [
"files"
]
},
{
"required": [
"driveInputFolder"
]
},
{
"required": [
"driveInputFileIds"
]
}
],
"anyOf": [
{
"required": [
"outputFolder"
]
},
{
"required": [
"driveOutputFolder"
]
}
]
}ProbeJobRequest
{
"type": "object",
"required": [
"operation"
],
"properties": {
"operation": {
"enum": [
"probe",
"media-probe"
]
},
"filePath": {
"type": "string"
},
"files": {
"type": "array",
"minItems": 1,
"maxItems": 1000,
"items": {
"type": "string"
}
},
"driveInputFolder": {
"type": "string",
"maxLength": 512
},
"driveInputFileIds": {
"$ref": "#/components/schemas/DriveInputFileIds"
},
"options": {
"type": "object",
"properties": {
"includeStreams": {
"type": "boolean",
"default": true
},
"includeMetadata": {
"type": "boolean",
"default": true
}
}
}
},
"oneOf": [
{
"required": [
"filePath"
]
},
{
"required": [
"files"
]
},
{
"required": [
"driveInputFolder"
]
},
{
"required": [
"driveInputFileIds"
]
}
]
}RiskAnalyzerJobRequest
{
"type": "object",
"required": [
"operation"
],
"properties": {
"operation": {
"enum": [
"risk-analyzer",
"risk"
]
},
"originalPath": {
"type": "string"
},
"comparisonPaths": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"items": {
"type": "string"
}
},
"files": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"items": {
"type": "string"
}
},
"driveInputFolder": {
"type": "string",
"maxLength": 512
},
"driveInputFileIds": {
"$ref": "#/components/schemas/DriveInputFileIds"
},
"options": {
"type": "object",
"properties": {
"originalFileName": {
"type": "string",
"maxLength": 260
}
}
}
},
"oneOf": [
{
"required": [
"originalPath",
"comparisonPaths"
]
},
{
"required": [
"originalPath",
"files"
]
},
{
"required": [
"driveInputFolder",
"options"
]
},
{
"required": [
"driveInputFileIds",
"options"
]
}
]
}ConvertJobRequest
{
"type": "object",
"required": [
"operation"
],
"properties": {
"operation": {
"enum": [
"convert",
"converter"
]
},
"filePath": {
"type": "string"
},
"files": {
"type": "array",
"minItems": 1,
"maxItems": 1000,
"items": {
"type": "string"
}
},
"driveInputFolder": {
"type": "string",
"maxLength": 512
},
"driveInputFileIds": {
"$ref": "#/components/schemas/DriveInputFileIds"
},
"outputFolder": {
"type": "string"
},
"driveOutputFolder": {
"type": "string",
"maxLength": 512
},
"format": {
"enum": [
"jpeg",
"jpg",
"png",
"webp",
"bmp",
"tiff",
"mp4",
"mov",
"webm",
"mkv",
"gif"
],
"description": "Compatibility alias for options.format"
},
"options": {
"type": "object",
"properties": {
"forceSoftware": {
"type": "boolean",
"default": false
},
"format": {
"enum": [
"jpeg",
"jpg",
"png",
"webp",
"bmp",
"tiff",
"mp4",
"mov",
"webm",
"mkv",
"gif"
]
},
"framerate": {
"type": "integer",
"minimum": 1,
"maximum": 30,
"default": 15
},
"scale": {
"type": "integer",
"minimum": 64,
"maximum": 1920,
"default": 720
}
}
}
},
"anyOf": [
{
"required": [
"options"
],
"properties": {
"options": {
"required": [
"format"
]
}
}
},
{
"required": [
"format"
]
}
],
"oneOf": [
{
"required": [
"filePath",
"outputFolder"
]
},
{
"required": [
"filePath",
"driveOutputFolder"
]
},
{
"required": [
"files",
"outputFolder"
]
},
{
"required": [
"files",
"driveOutputFolder"
]
},
{
"required": [
"driveInputFolder",
"outputFolder"
]
},
{
"required": [
"driveInputFileIds",
"outputFolder"
]
},
{
"required": [
"driveInputFolder",
"driveOutputFolder"
]
},
{
"required": [
"driveInputFileIds",
"driveOutputFolder"
]
}
]
}ReduceJobRequest
{
"type": "object",
"required": [
"operation"
],
"properties": {
"operation": {
"enum": [
"reduce",
"file-reducer",
"reducer"
]
},
"filePath": {
"type": "string"
},
"files": {
"type": "array",
"minItems": 1,
"maxItems": 1000,
"items": {
"type": "string"
}
},
"driveInputFolder": {
"type": "string",
"maxLength": 512
},
"driveInputFileIds": {
"$ref": "#/components/schemas/DriveInputFileIds"
},
"outputFolder": {
"type": "string"
},
"driveOutputFolder": {
"type": "string",
"maxLength": 512
},
"options": {
"type": "object",
"properties": {
"forceSoftware": {
"type": "boolean",
"default": false
}
}
}
},
"oneOf": [
{
"required": [
"filePath",
"outputFolder"
]
},
{
"required": [
"filePath",
"driveOutputFolder"
]
},
{
"required": [
"files",
"outputFolder"
]
},
{
"required": [
"files",
"driveOutputFolder"
]
},
{
"required": [
"driveInputFolder",
"outputFolder"
]
},
{
"required": [
"driveInputFileIds",
"outputFolder"
]
},
{
"required": [
"driveInputFolder",
"driveOutputFolder"
]
},
{
"required": [
"driveInputFileIds",
"driveOutputFolder"
]
}
]
}ShortMakerJobRequest
{
"type": "object",
"required": [
"operation",
"options"
],
"properties": {
"operation": {
"enum": [
"short-maker",
"shortmaker"
]
},
"filePath": {
"type": "string"
},
"files": {
"type": "array",
"minItems": 1,
"maxItems": 1000,
"items": {
"type": "string"
}
},
"driveInputFolder": {
"type": "string",
"maxLength": 512
},
"driveInputFileIds": {
"$ref": "#/components/schemas/DriveInputFileIds"
},
"outputFolder": {
"type": "string"
},
"driveOutputFolder": {
"type": "string",
"maxLength": 512
},
"options": {
"type": "object",
"required": [
"templateId"
],
"properties": {
"forceSoftware": {
"type": "boolean",
"default": false
},
"templateId": {
"type": "string",
"maxLength": 160
},
"durationMode": {
"enum": [
"smart",
"template"
],
"default": "smart"
},
"maxContentDuration": {
"type": [
"number",
"null"
],
"minimum": 1,
"maximum": 3600
},
"keepSourceAudio": {
"type": "boolean",
"default": false
},
"randomizeTextPos": {
"type": "boolean",
"default": false
},
"randomSeed": {
"type": "string",
"maxLength": 200
},
"spoofEnabled": {
"type": "boolean",
"default": false
},
"spoofTier": {
"enum": [
"fast",
"aggressive"
],
"default": "fast"
},
"usMetadataEnabled": {
"type": "boolean",
"default": false
},
"metadataCountry": {
"type": "string",
"pattern": "^[A-Za-z]{2}$",
"default": "US"
},
"metadataDeviceProfile": {
"enum": [
"iphone",
"rayban"
],
"default": "iphone"
}
}
}
},
"oneOf": [
{
"required": [
"filePath",
"outputFolder"
]
},
{
"required": [
"filePath",
"driveOutputFolder"
]
},
{
"required": [
"files",
"outputFolder"
]
},
{
"required": [
"files",
"driveOutputFolder"
]
},
{
"required": [
"driveInputFolder",
"outputFolder"
]
},
{
"required": [
"driveInputFileIds",
"outputFolder"
]
},
{
"required": [
"driveInputFolder",
"driveOutputFolder"
]
},
{
"required": [
"driveInputFileIds",
"driveOutputFolder"
]
}
]
}CaptionsJobRequest
{
"type": "object",
"required": [
"operation"
],
"allOf": [
{
"$ref": "#/components/schemas/CreditConfirmation"
}
],
"properties": {
"operation": {
"enum": [
"captions",
"auto-captions"
]
},
"confirmCredits": {
"type": "boolean"
},
"filePath": {
"type": "string"
},
"files": {
"type": "array",
"minItems": 1,
"maxItems": 1000,
"items": {
"type": "string"
}
},
"driveInputFolder": {
"type": "string",
"maxLength": 512
},
"driveInputFileIds": {
"$ref": "#/components/schemas/DriveInputFileIds"
},
"outputFolder": {
"type": "string"
},
"driveOutputFolder": {
"type": "string",
"maxLength": 512
},
"options": {
"type": "object",
"properties": {
"language": {
"enum": [
"",
"fr",
"en",
"es",
"de",
"it",
"pt",
"nl"
],
"default": ""
},
"tier": {
"enum": [
"premium",
"fast"
],
"default": "premium"
},
"maxCreditsPerVideo": {
"type": "integer",
"minimum": 0,
"maximum": 90000,
"description": "Explicit ceiling for each video's new source-second charges. Required before a nonzero charge on source-second runtimes; obtain a quote from /captions/quote."
},
"style": {
"enum": [
"punch",
"karaoke",
"clean",
"beast",
"boxed",
"tiktok-clean",
"instagram-clean",
"creator-pop",
"word-focus"
],
"default": "punch"
},
"overrides": {
"type": "object",
"additionalProperties": true
},
"confirmCredits": {
"type": "boolean"
}
}
}
},
"oneOf": [
{
"required": [
"filePath",
"outputFolder"
]
},
{
"required": [
"filePath",
"driveOutputFolder"
]
},
{
"required": [
"files",
"outputFolder"
]
},
{
"required": [
"files",
"driveOutputFolder"
]
},
{
"required": [
"driveInputFolder",
"outputFolder"
]
},
{
"required": [
"driveInputFileIds",
"outputFolder"
]
},
{
"required": [
"driveInputFolder",
"driveOutputFolder"
]
},
{
"required": [
"driveInputFileIds",
"driveOutputFolder"
]
}
]
}DownloadJobRequest
{
"type": "object",
"required": [
"operation"
],
"allOf": [
{
"$ref": "#/components/schemas/NetworkConfirmation"
}
],
"properties": {
"operation": {
"enum": [
"download",
"downloader"
]
},
"confirmExternalNetwork": {
"type": "boolean"
},
"url": {
"type": "string",
"format": "uri",
"maxLength": 4096
},
"urls": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"type": "string",
"format": "uri",
"maxLength": 4096
}
},
"outputFolder": {
"type": "string"
},
"driveOutputFolder": {
"type": "string",
"maxLength": 512
},
"options": {
"type": "object",
"properties": {
"usMetadataEnabled": {
"type": "boolean",
"default": false
},
"metadataCountry": {
"type": "string",
"pattern": "^[A-Za-z]{2}$",
"default": "US"
},
"metadataDeviceProfile": {
"enum": [
"iphone",
"rayban"
],
"default": "iphone"
},
"confirmExternalNetwork": {
"type": "boolean"
}
}
}
},
"oneOf": [
{
"required": [
"url",
"outputFolder"
]
},
{
"required": [
"url",
"driveOutputFolder"
]
},
{
"required": [
"urls",
"outputFolder"
]
},
{
"required": [
"urls",
"driveOutputFolder"
]
}
]
}SynthIdJobRequest
{
"type": "object",
"required": [
"operation",
"preset"
],
"allOf": [
{
"$ref": "#/components/schemas/CreditConfirmation"
}
],
"properties": {
"operation": {
"const": "synthid"
},
"confirmCredits": {
"type": "boolean"
},
"preset": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"filePath": {
"type": "string"
},
"files": {
"type": "array",
"minItems": 1,
"maxItems": 1000,
"items": {
"type": "string"
}
},
"driveInputFolder": {
"type": "string",
"maxLength": 512
},
"driveInputFileIds": {
"$ref": "#/components/schemas/DriveInputFileIds"
},
"outputFolder": {
"type": "string"
},
"driveOutputFolder": {
"type": "string",
"maxLength": 512
},
"options": {
"type": "object",
"properties": {
"confirmCredits": {
"type": "boolean"
}
}
}
},
"oneOf": [
{
"required": [
"filePath",
"outputFolder"
]
},
{
"required": [
"filePath",
"driveOutputFolder"
]
},
{
"required": [
"files",
"outputFolder"
]
},
{
"required": [
"files",
"driveOutputFolder"
]
},
{
"required": [
"driveInputFolder",
"outputFolder"
]
},
{
"required": [
"driveInputFileIds",
"outputFolder"
]
},
{
"required": [
"driveInputFolder",
"driveOutputFolder"
]
},
{
"required": [
"driveInputFileIds",
"driveOutputFolder"
]
}
]
}CreditConfirmation
{
"type": "object",
"description": "Explicit approval at the request root or in options, matching the runtime. Missing or false approvals never authorize a charge.",
"anyOf": [
{
"required": [
"confirmCredits"
],
"properties": {
"confirmCredits": {
"const": true
}
}
},
{
"required": [
"options"
],
"properties": {
"options": {
"type": "object",
"required": [
"confirmCredits"
],
"properties": {
"confirmCredits": {
"const": true
}
}
}
}
}
]
}NetworkConfirmation
{
"type": "object",
"description": "Explicit approval at the request root or in options, matching the runtime.",
"anyOf": [
{
"required": [
"confirmExternalNetwork"
],
"properties": {
"confirmExternalNetwork": {
"const": true
}
}
},
{
"required": [
"options"
],
"properties": {
"options": {
"type": "object",
"required": [
"confirmExternalNetwork"
],
"properties": {
"confirmExternalNetwork": {
"const": true
}
}
}
}
}
]
}CreateJobResponse
{
"type": "object",
"required": [
"jobId",
"operation",
"status",
"inputFiles",
"totalOperations",
"skipped",
"position"
],
"properties": {
"jobId": {
"type": "string"
},
"operation": {
"enum": [
"spoof",
"probe",
"risk-analyzer",
"convert",
"reduce",
"short-maker",
"captions",
"download",
"synthid"
]
},
"status": {
"enum": [
"queued",
"processing",
"completed",
"failed",
"cancelled"
]
},
"inputFiles": {
"type": [
"integer",
"null"
]
},
"batchCount": {
"type": "integer",
"default": 1
},
"totalOperations": {
"type": [
"integer",
"null"
]
},
"skipped": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FileError"
}
},
"position": {
"type": "integer",
"minimum": 1
},
"drive": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"replayed": {
"type": "boolean"
},
"jobAvailable": {
"type": "boolean",
"description": "False when a retained receipt outlives its job history; never rerun implicitly."
},
"outcome": {
"type": [
"string",
"null"
],
"enum": [
"success",
"partial",
"failed",
"cancelled",
null
]
},
"error_code": {
"type": "string"
},
"error": {
"type": "string"
},
"execution": {
"enum": [
"local",
"hybrid",
"network",
"remote-gpu"
]
},
"credits": {
"enum": [
"none",
"one-per-transcription",
"variable"
]
},
"estimatedCredits": {
"type": [
"integer",
"null"
],
"minimum": 0
}
}
}Job
{
"type": "object",
"required": [
"jobId",
"operation",
"status",
"preset",
"progress",
"createdAt"
],
"additionalProperties": true,
"properties": {
"jobId": {
"type": "string"
},
"operation": {
"enum": [
"spoof",
"probe",
"risk-analyzer",
"convert",
"reduce",
"short-maker",
"captions",
"download",
"synthid"
]
},
"status": {
"enum": [
"queued",
"processing",
"completed",
"failed",
"cancelled"
]
},
"outcome": {
"type": [
"string",
"null"
],
"enum": [
"success",
"partial",
"failed",
"cancelled",
null
]
},
"type": {
"enum": [
"single",
"batch"
]
},
"preset": {
"type": [
"string",
"null"
]
},
"progress": {
"type": "object",
"additionalProperties": true
},
"result": {
"$ref": "#/components/schemas/ProcessingResult"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProcessingResult"
}
},
"artifacts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LocalArtifact"
}
},
"drive": {
"$ref": "#/components/schemas/DriveJobState"
},
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FileError"
}
},
"error": {
"type": "string"
},
"error_code": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"startedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}LocalArtifact
{
"type": "object",
"required": [
"resultIndex",
"artifactIndex",
"name",
"localAvailable",
"downloadUrl"
],
"properties": {
"resultIndex": {
"type": "integer",
"minimum": 0
},
"artifactIndex": {
"type": "integer",
"minimum": 0
},
"name": {
"type": "string"
},
"localAvailable": {
"type": "boolean"
},
"downloadUrl": {
"type": "string",
"description": "Relative URL; batch index selects a result and artifact selects a file inside it."
}
}
}ProcessingResult
{
"type": "object",
"additionalProperties": true,
"description": "Operation-specific JSON; file-producing success requires existing non-empty files. Captions no_speech with charged false is a valid empty result.",
"properties": {
"outputPath": {
"type": [
"string",
"null"
]
},
"files": {
"type": "array",
"items": {
"type": "string"
}
},
"localAvailable": {
"type": "boolean"
},
"outcome": {
"enum": [
"success",
"partial",
"failed",
"cancelled"
]
},
"reason": {
"type": "string"
},
"charged": {
"type": "boolean"
},
"delivery": {
"$ref": "#/components/schemas/DriveDelivery"
},
"processing": {
"type": "object",
"additionalProperties": true
}
}
}DriveDelivery
{
"type": "object",
"required": [
"provider",
"status",
"localAvailable"
],
"properties": {
"provider": {
"const": "google-drive"
},
"status": {
"enum": [
"queued",
"uploading",
"uploaded",
"failed",
"cancelled"
]
},
"name": {
"type": "string"
},
"fileId": {
"type": [
"string",
"null"
]
},
"confirmed": {
"type": "boolean"
},
"localAvailable": {
"const": false
},
"recoveryAvailable": {
"type": "boolean"
}
}
}DriveJobState
{
"type": "object",
"required": [
"inputFolderId",
"outputFolderId",
"uploadResult",
"uploadError",
"recovery"
],
"properties": {
"inputFolderId": {
"type": [
"string",
"null"
]
},
"outputFolderId": {
"type": [
"string",
"null"
]
},
"uploadError": {
"type": [
"string",
"null"
]
},
"uploadResult": {
"type": [
"object",
"null"
],
"properties": {
"uploaded": {
"type": "integer",
"minimum": 0
},
"failed": {
"type": "integer",
"minimum": 0
},
"cancelled": {
"type": "boolean"
},
"receipts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DriveDelivery"
}
},
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FileError"
}
}
}
},
"recovery": {
"type": "object",
"required": [
"available"
],
"properties": {
"available": {
"type": "boolean"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
}
}FileError
{
"type": "object",
"required": [
"file",
"error"
],
"properties": {
"file": {
"type": "string"
},
"error": {
"type": "string"
},
"error_code": {
"type": "string"
}
}
}ToolDefinition
{
"type": "object",
"required": [
"operation",
"label",
"execution",
"credits",
"network",
"input",
"output",
"supportsBatch",
"supportsDriveInput",
"supportsDriveOutput",
"available"
],
"properties": {
"operation": {
"type": "string"
},
"label": {
"type": "string"
},
"execution": {
"enum": [
"local",
"hybrid",
"network",
"remote-gpu"
]
},
"credits": {
"enum": [
"none",
"one-per-transcription",
"variable"
]
},
"network": {
"type": "boolean"
},
"input": {
"type": "string"
},
"output": {
"enum": [
"required",
"none"
]
},
"supportsBatch": {
"type": "boolean"
},
"supportsDriveInput": {
"type": "boolean"
},
"supportsDriveOutput": {
"type": "boolean"
},
"available": {
"type": "boolean"
},
"unavailableReason": {
"type": [
"string",
"null"
]
},
"unavailableCode": {
"type": [
"string",
"null"
]
},
"requiresCreditConfirmation": {
"type": "boolean"
},
"requiresNetworkConfirmation": {
"type": "boolean"
},
"dependsOnPreset": {
"type": "boolean"
},
"creditConfirmationScope": {
"enum": [
"paid-presets"
]
},
"limits": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"pricing": {
"type": "object",
"properties": {
"model": {
"type": "string"
},
"creditsPerSecond": {
"type": "number"
},
"requiresCreditLimit": {
"type": "boolean"
},
"limitField": {
"type": "string"
},
"quotePath": {
"type": "string"
}
}
}
}
}ShortMakerTemplate
{
"type": "object",
"required": [
"id",
"name",
"source"
],
"properties": {
"id": {
"type": "string",
"maxLength": 160
},
"name": {
"type": "string",
"maxLength": 240
},
"source": {
"enum": [
"builtin",
"custom"
]
},
"duration": {
"type": [
"number",
"null"
]
},
"description": {
"type": [
"string",
"null"
],
"maxLength": 1000
}
}
}Error
{
"type": "object",
"required": [
"error",
"error_code",
"request_id"
],
"properties": {
"error": {
"type": "string"
},
"error_code": {
"type": "string"
},
"request_id": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}#/components/responses
BadRequest
{
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}Unauthorized
{
"description": "Missing or invalid Bearer key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}Forbidden
{
"description": "Subscription or team permission denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}NotFound
{
"description": "Route, job, or output not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}Conflict
{
"description": "Idempotency conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}PreconditionFailed
{
"description": "Google Drive is not configured or connected",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}PayloadTooLarge
{
"description": "JSON or upload limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}RateLimited
{
"description": "Queue or authentication rate limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}UnsupportedMediaType
{
"description": "Multipart is unsupported; send raw binary bytes with X-Filename.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}StorageUnavailable
{
"description": "Job journal unavailable or retained upload storage exhausted.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}When something does not work
Connection refused
Open Desktop, enable the API, apply settings and verify the port. Keep Desktop running.
401
Check the Bearer API key and update scripts after applying a regenerated key.
400 / 404
Read error_code and check paths, presets, fields, jobId and artifact URLs. History can expire.
403 / 503
Permissions denied or account verification temporarily unavailable. Read retryable and cause_code; an outage does not mean the subscription is invalid.
409
An idempotency key was reused with a changed body, the account session changed, or a Drive output was requested through local download. Read error_code.
412
Connect Drive and check /api/v1/drive/status. Each file or folder needs its own access.
413 / 415 / 507
Oversized JSON/upload, unsupported multipart upload, unavailable journal or exhausted storage. Use raw upload bytes and respect the installed limits.
429 / 500
Check error_code, Retry-After and the queue. Keep request_id and X-Request-ID for support. Preserve the original execution key when recovering a lost response. Never send credentials.
Need a hand with your workflow?
The MetaGhost support team can help.