# MetaGhost Cloud API

Process images and videos from your server. Send a file, approve a credit quote and retrieve the result.

In your account, open Cloud API and create a key with Read credits permission. Set METAGHOST_API_KEY and METAGHOST_BASE_URL on your server using the values shown there. This first request reads the balance without spending credits.

Business and Scale include API access by default. Team permissions and existing grants also apply. Choose Never to keep your key across renewals. It works only while the original account or team has API access. You can revoke it at any time. Store the key on your server and send it as a Bearer token.

Use the Base URL from your account ending in `/api/cloud/v1`.

[Web guide](https://metaghost.io/docs/api/cloud) · [OpenAPI JSON](https://metaghost.io/docs/api/cloud/openapi.json) · [OpenAPI YAML](https://metaghost.io/docs/api/cloud/openapi.yaml)

## Quickstart

### cURL

```sh
curl --fail-with-body --request GET \
  "$METAGHOST_BASE_URL/credits" \
  --header "Authorization: Bearer $METAGHOST_API_KEY"
```

### Python

```python
import os
import json
import urllib.request

base = os.environ["METAGHOST_BASE_URL"].rstrip("/")
headers = {
  "Authorization": "Bearer " + os.environ["METAGHOST_API_KEY"]
}
request = urllib.request.Request(
    base + "/credits",
    method="GET", headers=headers
)
with urllib.request.urlopen(request, timeout=30) as response:
    print(json.load(response))
```

### Node.js

```javascript
// Node.js 24: run on your server.
const base = process.env.METAGHOST_BASE_URL?.replace(/\/$/, "");
const token = process.env.METAGHOST_API_KEY;
if (!base || !token) throw new Error("Missing API configuration");

const response = await fetch(base + "/credits", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${token}`
  },
  signal: AbortSignal.timeout(30_000),
});
const result = await response.json();
if (!response.ok) throw new Error(JSON.stringify(result));
console.log(result);
```

## Process an image

This Python 3.10+ example sends one JPEG up to 5 MiB and saves the result to a new file. Give its Cloud key the assets:write, quotes:write, batches:write and jobs:read permissions. The command submits the batch only if its quote fits the credit limit you set.

1. `POST /assets`. Create an upload, send the bytes to the signed URL with its required headers, then finalize and wait for ready.
2. `POST /quotes`. Quote one output using the verified asset ID, version and the image.spoof.simple operation.
3. `POST /batches`. Submit the quote ID and approved amount. Save the Idempotency-Key and exact request body so a lost response can be recovered.
4. `GET /results/{resultId}`. After the batch succeeds, read its jobs, get the signed download URL and verify the SHA-256 before saving.

```sh
python3 quickstart.py image.jpg result.jpg --max-credits 20
```

```python
"""Process one small JPEG with the MetaGhost Cloud API using Python 3.10+."""

import argparse
import hashlib
import json
import os
from pathlib import Path
import sys
import time
from urllib.error import HTTPError, URLError
from urllib.parse import urlsplit
from urllib.request import HTTPRedirectHandler, Request, build_opener
from uuid import uuid4


class NoRedirect(HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None


def wait_for(read, pending, ready):
    deadline = time.monotonic() + 180
    while time.monotonic() < deadline:
        value = read()
        state = value["state"]
        if state == ready:
            return value
        if state not in pending:
            raise ValueError(f"Stopped in state {state} ({value.get('errorCode', 'no error code')}).")
        time.sleep(2)
    raise TimeoutError("Wait limit reached. Check the existing asset or batch before trying again.")


def process(source, output, credit_limit):
    base = os.environ["METAGHOST_BASE_URL"].rstrip("/")
    token = os.environ["METAGHOST_API_KEY"]
    parsed = urlsplit(base)
    local = parsed.scheme == "http" and parsed.hostname in ("127.0.0.1", "localhost", "::1")
    if (not parsed.hostname or parsed.username or parsed.password or parsed.query or parsed.fragment
            or parsed.path != "/api/cloud/v1" or (parsed.scheme != "https" and not local)):
        raise ValueError("Use the Cloud API base URL shown in your account.")
    if not token or any(c.isspace() for c in token):
        raise ValueError("Set METAGHOST_API_KEY to your Cloud API key.")
    if source.suffix.lower() not in (".jpeg", ".jpg") or output.exists() or not output.parent.is_dir():
        raise ValueError("Choose a JPEG and a new output file in an existing directory.")
    with source.open("rb") as file:
        data = file.read(5 * 1024**2 + 1)
    if not 0 < len(data) <= 5 * 1024**2 or not data.startswith(b"\xff\xd8\xff"):
        raise ValueError("This example accepts a JPEG up to 5 MiB.")

    opener = build_opener(NoRedirect())

    def call(path, body=None, request_key=None):
        headers = {"Authorization": f"Bearer {token}"}
        if body is not None:
            headers.update({"Content-Type": "application/json", "Idempotency-Key": request_key or uuid4().hex})
        request = Request(base + path, data=json.dumps(body).encode() if body is not None else None,
                          headers=headers)
        with opener.open(request, timeout=30) as response:
            return json.load(response)

    def storage_request(url, **kwargs):
        target = urlsplit(url)
        if target.scheme != "https" or not target.hostname or target.username or target.password:
            raise ValueError("The API did not return a valid HTTPS transfer URL.")
        return opener.open(Request(url, **kwargs), timeout=30)

    proof = {"byteLength": len(data), "sha256": hashlib.sha256(data).hexdigest()}
    upload = call("/assets", {**proof, "filename": source.name, "mediaType": "image/jpeg"})
    asset_path = "/assets/" + upload["asset"]["assetId"]
    with storage_request(upload["uploadUrl"], method="PUT", data=data, headers=upload["requiredHeaders"]):
        pass
    call(asset_path + "/finalize", proof)
    print(f"Asset: {upload['asset']['assetId']}", flush=True)
    asset = wait_for(lambda: call(asset_path), {"uploading", "inspecting"}, "ready")

    quote = call("/quotes", {"operation": "image.spoof.simple", "options": {}, "inputs": [
        {"asset": {"assetId": asset["assetId"], "version": asset["version"]}, "variants": 1},
    ]})
    quoted = quote["maxCredits"]
    if type(quoted) is not int or not 0 <= quoted <= credit_limit:
        raise ValueError(f"Quote is {quoted} credits and exceeds the accepted limit of {credit_limit}.")
    batch_body = {"quoteId": quote["quoteId"], "maxCredits": quoted}
    batch_key = uuid4().hex
    print(f"Submitting {json.dumps(batch_body)} with Idempotency-Key {batch_key}.", flush=True)
    batch = call("/batches", batch_body, batch_key)
    batch_path = "/batches/" + batch["batchId"]
    print(f"Batch: {batch['batchId']}", flush=True)
    completed = wait_for(lambda: call(batch_path), {"queued", "running", "cancelling"}, "succeeded")
    job, = call(batch_path + "/jobs")["jobs"]
    if job["state"] != "succeeded":
        raise ValueError("The job has not produced a result. Check the existing batch.")
    result = call("/results/" + job["resultId"])
    length = result["byteLength"]
    if not 0 < length <= 20 * 1024**2:
        raise ValueError("Result is too large for this example. Use the result endpoint to download it.")
    with storage_request(result["downloadUrl"]) as response:
        saved = response.read(length + 1)
    if len(saved) != length or hashlib.sha256(saved).hexdigest() != result["sha256"]:
        raise ValueError("The downloaded bytes do not match the result checksum.")
    with output.open("xb") as file:
        file.write(saved)
    print(f"Saved {output}. Charged credits: {completed['capturedCredits']}.")


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("source", type=Path)
    parser.add_argument("output", type=Path)
    parser.add_argument("--max-credits", type=int, required=True, help="Maximum approved credits for this example")
    args = parser.parse_args()
    if args.max_credits < 0:
        parser.error("--max-credits must be zero or more.")
    try:
        process(args.source, args.output, args.max_credits)
    except HTTPError as error:
        print(f"HTTP {error.code}. Check the request and any existing batch before retrying.", file=sys.stderr)
        sys.exit(1)
    except URLError:
        print("Connection interrupted. Recover any submitted batch before retrying.", file=sys.stderr)
        sys.exit(1)
    except (OSError, ValueError, KeyError) as error:
        print(str(error), file=sys.stderr)
        sys.exit(1)
```

Check GET /capabilities for active operations and limits. Video SynthID accepts up to 10 seconds per source, including in Advanced and Spoof Pro when they run SynthID.

## Credit pricing

Simple images cost 10 credits per megapixel per output, rounded up to a whole credit. Simple video costs 3 credits per second per output at 1920 × 1080 and 30 fps.

Resolution, frame rate, outputs and AI options affect the total. The server quote is authoritative. Submitting a batch reserves credits. Recent API usage shows charges for completed work.

## API reference

Use the OpenAPI JSON above for the full request and response schemas.

### Quickstart routes

- [GET /credits](https://metaghost.io/docs/api/cloud#operation-get-credits) · credits:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /capabilities](https://metaghost.io/docs/api/cloud#operation-get-capabilities) · jobs:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /assets](https://metaghost.io/docs/api/cloud#operation-post-assets) · assets:write · HTTP 201, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /assets/{assetId}/finalize](https://metaghost.io/docs/api/cloud#operation-post-assets-assetid-finalize) · assets:write · HTTP 202, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /assets/{assetId}](https://metaghost.io/docs/api/cloud#operation-get-assets-assetid) · assets:write · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /quotes](https://metaghost.io/docs/api/cloud#operation-post-quotes) · quotes:write · HTTP 201, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /batches](https://metaghost.io/docs/api/cloud#operation-post-batches) · batches:write, jobs:read · HTTP 202, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /batches/{batchId}](https://metaghost.io/docs/api/cloud#operation-get-batches-batchid) · jobs:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /batches/{batchId}/jobs](https://metaghost.io/docs/api/cloud#operation-get-batches-batchid-jobs) · jobs:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /results/{resultId}](https://metaghost.io/docs/api/cloud#operation-get-results-resultid) · jobs:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503

### Files, presets and jobs

- [GET /jobs/{jobId}/caption-review](https://metaghost.io/docs/api/cloud#operation-get-jobs-jobid-caption-review) · jobs:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [PATCH /jobs/{jobId}/caption-review](https://metaghost.io/docs/api/cloud#operation-patch-jobs-jobid-caption-review) · batches:write, jobs:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /jobs/{jobId}/caption-review/submit](https://metaghost.io/docs/api/cloud#operation-post-jobs-jobid-caption-review-submit) · batches:write, jobs:read · HTTP 202, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /presets/import](https://metaghost.io/docs/api/cloud#operation-post-presets-import) · projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /presets/export](https://metaghost.io/docs/api/cloud#operation-post-presets-export) · projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /presets](https://metaghost.io/docs/api/cloud#operation-get-presets) · projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /presets](https://metaghost.io/docs/api/cloud#operation-post-presets) · projects:write, projects:read · HTTP 201, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /presets/{presetId}](https://metaghost.io/docs/api/cloud#operation-get-presets-presetid) · projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [PATCH /presets/{presetId}](https://metaghost.io/docs/api/cloud#operation-patch-presets-presetid) · projects:write, projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [DELETE /presets/{presetId}](https://metaghost.io/docs/api/cloud#operation-delete-presets-presetid) · projects:write, projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /presets/{presetId}/rename](https://metaghost.io/docs/api/cloud#operation-post-presets-presetid-rename) · projects:write, projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /catalog](https://metaghost.io/docs/api/cloud#operation-get-catalog) · jobs:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [DELETE /assets/{assetId}](https://metaghost.io/docs/api/cloud#operation-delete-assets-assetid) · assets:write · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /quotes/{quoteId}](https://metaghost.io/docs/api/cloud#operation-get-quotes-quoteid) · jobs:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /batches/{batchId}/cancel](https://metaghost.io/docs/api/cloud#operation-post-batches-batchid-cancel) · batches:write, jobs:read · HTTP 202, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /jobs/{jobId}](https://metaghost.io/docs/api/cloud#operation-get-jobs-jobid) · jobs:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503

### Studio and media library

- [POST /library-rebuilds](https://metaghost.io/docs/api/cloud#operation-post-library-rebuilds) · projects:write, projects:read · HTTP 202, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /library-rebuilds/{rebuildId}](https://metaghost.io/docs/api/cloud#operation-get-library-rebuilds-rebuildid) · projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [DELETE /library-rebuilds/{rebuildId}](https://metaghost.io/docs/api/cloud#operation-delete-library-rebuilds-rebuildid) · projects:write, projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /library-items/{libraryId}/preview](https://metaghost.io/docs/api/cloud#operation-get-library-items-libraryid-preview) · projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /library-items](https://metaghost.io/docs/api/cloud#operation-post-library-items) · projects:write, projects:read · HTTP 201, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /library-items](https://metaghost.io/docs/api/cloud#operation-get-library-items) · projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /library-uploads](https://metaghost.io/docs/api/cloud#operation-post-library-uploads) · projects:write, projects:read, assets:write · HTTP 201, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /library-uploads/{assetId}/finalize](https://metaghost.io/docs/api/cloud#operation-post-library-uploads-assetid-finalize) · projects:write, projects:read, assets:write · HTTP 202, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /library-items/stats](https://metaghost.io/docs/api/cloud#operation-get-library-items-stats) · projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /library-items/{libraryId}](https://metaghost.io/docs/api/cloud#operation-get-library-items-libraryid) · projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [PATCH /library-items/{libraryId}](https://metaghost.io/docs/api/cloud#operation-patch-library-items-libraryid) · projects:write, projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [DELETE /library-items/{libraryId}](https://metaghost.io/docs/api/cloud#operation-delete-library-items-libraryid) · projects:write, projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /library-items/{libraryId}/content](https://metaghost.io/docs/api/cloud#operation-get-library-items-libraryid-content) · projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /studio-imports](https://metaghost.io/docs/api/cloud#operation-post-studio-imports) · projects:write, projects:read, assets:write · HTTP 201, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /studio-transfers/{transferId}](https://metaghost.io/docs/api/cloud#operation-get-studio-transfers-transferid) · projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [DELETE /studio-transfers/{transferId}](https://metaghost.io/docs/api/cloud#operation-delete-studio-transfers-transferid) · projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /studio-transfers/{transferId}/finalize](https://metaghost.io/docs/api/cloud#operation-post-studio-transfers-transferid-finalize) · projects:write, projects:read, assets:write · HTTP 202, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /studio-transfers/{transferId}/result](https://metaghost.io/docs/api/cloud#operation-get-studio-transfers-transferid-result) · projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /studio-templates/{templateId}/export](https://metaghost.io/docs/api/cloud#operation-post-studio-templates-templateid-export) · projects:read · HTTP 202, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /studio-templates](https://metaghost.io/docs/api/cloud#operation-get-studio-templates) · projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /studio-templates](https://metaghost.io/docs/api/cloud#operation-post-studio-templates) · projects:write, projects:read · HTTP 201, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /studio-templates/{templateId}/preview](https://metaghost.io/docs/api/cloud#operation-get-studio-templates-templateid-preview) · projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [PUT /studio-templates/{templateId}/preview](https://metaghost.io/docs/api/cloud#operation-put-studio-templates-templateid-preview) · projects:write, projects:read, jobs:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /studio-templates/{templateId}](https://metaghost.io/docs/api/cloud#operation-get-studio-templates-templateid) · projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [PATCH /studio-templates/{templateId}](https://metaghost.io/docs/api/cloud#operation-patch-studio-templates-templateid) · projects:write, projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [DELETE /studio-templates/{templateId}](https://metaghost.io/docs/api/cloud#operation-delete-studio-templates-templateid) · projects:write, projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503

### Captions and translation

- [POST /translations](https://metaghost.io/docs/api/cloud#operation-post-translations) · projects:write, projects:read · HTTP 202, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /translations/{translationId}](https://metaghost.io/docs/api/cloud#operation-get-translations-translationid) · projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [DELETE /translations/{translationId}](https://metaghost.io/docs/api/cloud#operation-delete-translations-translationid) · projects:write, projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /translations/{translationId}/result](https://metaghost.io/docs/api/cloud#operation-get-translations-translationid-result) · projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /caption-projects](https://metaghost.io/docs/api/cloud#operation-get-caption-projects) · projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /caption-projects](https://metaghost.io/docs/api/cloud#operation-post-caption-projects) · projects:write, projects:read · HTTP 201, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /caption-projects/{projectId}](https://metaghost.io/docs/api/cloud#operation-get-caption-projects-projectid) · projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [PATCH /caption-projects/{projectId}](https://metaghost.io/docs/api/cloud#operation-patch-caption-projects-projectid) · projects:write, projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [DELETE /caption-projects/{projectId}](https://metaghost.io/docs/api/cloud#operation-delete-caption-projects-projectid) · projects:write, projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /caption-projects/{projectId}/subtitles](https://metaghost.io/docs/api/cloud#operation-post-caption-projects-projectid-subtitles) · projects:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /transcripts](https://metaghost.io/docs/api/cloud#operation-post-transcripts) · quotes:write, assets:write, jobs:read · HTTP 201, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /transcripts/{transcriptId}](https://metaghost.io/docs/api/cloud#operation-get-transcripts-transcriptid) · jobs:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [DELETE /transcripts/{transcriptId}](https://metaghost.io/docs/api/cloud#operation-delete-transcripts-transcriptid) · quotes:write · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /transcripts/{transcriptId}/start](https://metaghost.io/docs/api/cloud#operation-post-transcripts-transcriptid-start) · batches:write, jobs:read · HTTP 202, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /captions/font-preview](https://metaghost.io/docs/api/cloud#operation-post-captions-font-preview) · jobs:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503

### Downloader

- [POST /download-sessions](https://metaghost.io/docs/api/cloud#operation-post-download-sessions) · assets:write · HTTP 201, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /download-sessions](https://metaghost.io/docs/api/cloud#operation-get-download-sessions) · assets:write · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /download-sessions/{sessionId}](https://metaghost.io/docs/api/cloud#operation-get-download-sessions-sessionid) · assets:write · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [DELETE /download-sessions/{sessionId}](https://metaghost.io/docs/api/cloud#operation-delete-download-sessions-sessionid) · assets:write · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /download-batches](https://metaghost.io/docs/api/cloud#operation-post-download-batches) · assets:write · HTTP 202, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /download-batches/{batchId}](https://metaghost.io/docs/api/cloud#operation-get-download-batches-batchid) · assets:write · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [DELETE /download-batches/{batchId}](https://metaghost.io/docs/api/cloud#operation-delete-download-batches-batchid) · assets:write · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /downloads](https://metaghost.io/docs/api/cloud#operation-post-downloads) · assets:write · HTTP 202, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /downloads/{downloadId}](https://metaghost.io/docs/api/cloud#operation-get-downloads-downloadid) · assets:write · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [DELETE /downloads/{downloadId}](https://metaghost.io/docs/api/cloud#operation-delete-downloads-downloadid) · assets:write · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /downloads/{downloadId}/result](https://metaghost.io/docs/api/cloud#operation-get-downloads-downloadid-result) · assets:write · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503

### Google Drive

- [POST /drive/connections/{connectionId}/outputs](https://metaghost.io/docs/api/cloud#operation-post-drive-connections-connectionid-outputs) · drive:write, drive:read · HTTP 202, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /drive/outputs/{collectionId}](https://metaghost.io/docs/api/cloud#operation-get-drive-outputs-collectionid) · drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [DELETE /drive/outputs/{collectionId}](https://metaghost.io/docs/api/cloud#operation-delete-drive-outputs-collectionid) · drive:write, drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /drive/outputs/{collectionId}/items](https://metaghost.io/docs/api/cloud#operation-get-drive-outputs-collectionid-items) · drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /drive/outputs/{collectionId}/recover](https://metaghost.io/docs/api/cloud#operation-post-drive-outputs-collectionid-recover) · drive:write, drive:read · HTTP 202, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /drive/connections/{connectionId}/inputs](https://metaghost.io/docs/api/cloud#operation-post-drive-connections-connectionid-inputs) · drive:write, drive:read, assets:write · HTTP 202, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /drive/inputs/{collectionId}](https://metaghost.io/docs/api/cloud#operation-get-drive-inputs-collectionid) · drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [DELETE /drive/inputs/{collectionId}](https://metaghost.io/docs/api/cloud#operation-delete-drive-inputs-collectionid) · drive:write, drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /drive/inputs/{collectionId}/items](https://metaghost.io/docs/api/cloud#operation-get-drive-inputs-collectionid-items) · drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /drive/connections/{connectionId}/transfers](https://metaghost.io/docs/api/cloud#operation-post-drive-connections-connectionid-transfers) · drive:write, drive:read · HTTP 202, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /drive/transfers/{transferId}](https://metaghost.io/docs/api/cloud#operation-get-drive-transfers-transferid) · drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [DELETE /drive/transfers/{transferId}](https://metaghost.io/docs/api/cloud#operation-delete-drive-transfers-transferid) · drive:write, drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /drive/transfers/{transferId}/recover](https://metaghost.io/docs/api/cloud#operation-post-drive-transfers-transferid-recover) · drive:write, drive:read · HTTP 202, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /drive/connections/{connectionId}/mutations](https://metaghost.io/docs/api/cloud#operation-post-drive-connections-connectionid-mutations) · drive:write, drive:read · HTTP 202, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /drive/mutations/{mutationId}](https://metaghost.io/docs/api/cloud#operation-get-drive-mutations-mutationid) · drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [DELETE /drive/mutations/{mutationId}](https://metaghost.io/docs/api/cloud#operation-delete-drive-mutations-mutationid) · drive:write, drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /drive/mutations/{mutationId}/reconcile](https://metaghost.io/docs/api/cloud#operation-post-drive-mutations-mutationid-reconcile) · drive:write, drive:read · HTTP 202, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /drive/connections/{connectionId}/thumbnail](https://metaghost.io/docs/api/cloud#operation-get-drive-connections-connectionid-thumbnail) · drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /drive/connections/{connectionId}/pickers](https://metaghost.io/docs/api/cloud#operation-post-drive-connections-connectionid-pickers) · drive:write, drive:read · HTTP 201, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /drive/pickers/{pickerId}](https://metaghost.io/docs/api/cloud#operation-get-drive-pickers-pickerid) · drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [DELETE /drive/pickers/{pickerId}](https://metaghost.io/docs/api/cloud#operation-delete-drive-pickers-pickerid) · drive:write, drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /drive/pickers/{pickerId}/items](https://metaghost.io/docs/api/cloud#operation-get-drive-pickers-pickerid-items) · drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /drive/connections/{connectionId}/favorites](https://metaghost.io/docs/api/cloud#operation-get-drive-connections-connectionid-favorites) · drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [PUT /drive/connections/{connectionId}/favorites](https://metaghost.io/docs/api/cloud#operation-put-drive-connections-connectionid-favorites) · drive:write, drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [DELETE /drive/connections/{connectionId}/favorites](https://metaghost.io/docs/api/cloud#operation-delete-drive-connections-connectionid-favorites) · drive:write, drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /drive/connections/{connectionId}/files/query](https://metaghost.io/docs/api/cloud#operation-post-drive-connections-connectionid-files-query) · drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /drive/connections/{connectionId}/file](https://metaghost.io/docs/api/cloud#operation-get-drive-connections-connectionid-file) · drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /drive/authorizations](https://metaghost.io/docs/api/cloud#operation-post-drive-authorizations) · drive:write, drive:read · HTTP 201, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /drive/authorizations/{authorizationId}](https://metaghost.io/docs/api/cloud#operation-get-drive-authorizations-authorizationid) · drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /drive/connection](https://metaghost.io/docs/api/cloud#operation-get-drive-connection) · drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /drive/connections/{connectionId}](https://metaghost.io/docs/api/cloud#operation-get-drive-connections-connectionid) · drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [DELETE /drive/connections/{connectionId}](https://metaghost.io/docs/api/cloud#operation-delete-drive-connections-connectionid) · drive:write, drive:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503

### Teams

- [GET /team/activity](https://metaghost.io/docs/api/cloud#operation-get-team-activity) · teams:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /team/activity/status](https://metaghost.io/docs/api/cloud#operation-get-team-activity-status) · teams:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /team/members](https://metaghost.io/docs/api/cloud#operation-get-team-members) · teams:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /team/invitations](https://metaghost.io/docs/api/cloud#operation-get-team-invitations) · teams:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /team/permissions](https://metaghost.io/docs/api/cloud#operation-get-team-permissions) · teams:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /team/audit](https://metaghost.io/docs/api/cloud#operation-get-team-audit) · teams:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /team/presets](https://metaghost.io/docs/api/cloud#operation-get-team-presets) · teams:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /team/presets](https://metaghost.io/docs/api/cloud#operation-post-team-presets) · teams:write, teams:read · HTTP 201, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [GET /team/presets/{presetId}](https://metaghost.io/docs/api/cloud#operation-get-team-presets-presetid) · teams:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [PATCH /team/presets/{presetId}](https://metaghost.io/docs/api/cloud#operation-patch-team-presets-presetid) · teams:write, teams:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [DELETE /team/presets/{presetId}](https://metaghost.io/docs/api/cloud#operation-delete-team-presets-presetid) · teams:write, teams:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503
- [POST /team/presets/{presetId}/lock](https://metaghost.io/docs/api/cloud#operation-post-team-presets-presetid-lock) · teams:write, teams:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503

### Account and limits

- [GET /performance](https://metaghost.io/docs/api/cloud#operation-get-performance) · jobs:read · HTTP 200, 400, 401, 402, 403, 404, 409, 410, 413, 415, 422, 429, 503

## Troubleshooting

- **401** Check that the Cloud key is present, valid and still active.
- **403** Check your subscription, team permissions and the scopes of the key.
- **409** Check the quote and replay the exact request with its original Idempotency-Key if the response was lost.
- **429** Wait for the delay in Retry-After before making another request.

## Cloud MCP

Copy the MCP URL from the Cloud API page in your account. In your assistant, add a remote MCP server, choose Streamable HTTP and paste the URL. Enter your Cloud API key in the connector’s Bearer token field. The Desktop app can stay closed.

Use metaghost_cloud_getCredits with Read credits to check the connection. Give the key Process media to use quotes, batches and results. Add Projects or Google Drive for the corresponding workflows. Get a quote before starting a batch and set maxCredits. Upload the file with the signed upload URL or use a file already granted through Google Drive. The MCP returns temporary result links.

Drive recovery can verify an existing delivery or resume its upload. Open the consent and Picker links returned by the assistant in your browser, then return to the assistant to continue.

To connect an authenticated Downloader session, import its cookie file directly with POST /download-sessions outside the assistant. The MCP can then list, use and revoke the session by ID.
