تخطَّ إلى المحتوى
GhostMind

Start Here

هذا المحتوى غير متوفر بلغتك بعد.

Start Here — Using the GhostMind API

This page covers everything you need to make your first request and become productive with GhostMind in minutes.

1. What GhostMind Is

GhostMind is an AI gateway that provides an OpenAI-compatible API for supported capabilities. It routes requests through your connected AI provider accounts (ChatGPT, Google Savio TTS) with workspace isolation, usage metering, and quota enforcement.

You bring your own provider accounts — GhostMind manages the sessions, routing, and API surface.

2. What You Need

  • A GhostMind account with a workspace
  • A connected ChatGPT account (for chat, vision, files, generated images)
  • A connected Google Savio account (for speech generation, if needed)
  • An API key (gmk_live_...)

3. Connect Your Provider Accounts

Before ChatGPT-dependent APIs work, you must connect a ChatGPT account:

  1. Log in to the User App
  2. Go to Connections
  3. Click Connect ChatGPT
  4. A secure browser opens — log in to ChatGPT manually
  5. Handle any MFA/CAPTCHA prompts yourself
  6. GhostMind stores the authorized session
  7. The connection status becomes healthy

Repeat for Google Savio if you need speech generation.

4. Get an API Key

  1. In the User App, go to API Keys
  2. Click Create Key
  3. Copy the key immediately — it is shown only once
  4. Store it securely (environment variable, secret manager)

5. Base URL

https://ghostmind.optdmsa.com

6. Authentication

All API requests require a Bearer token:

Authorization: Bearer gmk_live_...

API keys start with gmk_live_ and are scoped to a workspace.

7. Discover Capabilities

Always call this first. Do not assume a feature is enabled — check:

Terminal window
curl https://ghostmind.optdmsa.com/v1/capabilities \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY"

The response tells you what is supported (platform-level) vs enabled (effective for your workspace). A feature can be supported: true but enabled: false if no account is connected or the upstream account lacks authorization.

8. Discover Models

Terminal window
curl https://ghostmind.optdmsa.com/v1/models \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY"

Use model: "auto" to let GhostMind select the best available model, or specify a model ID from the list.

9. Your First Chat Request

Terminal window
curl -X POST https://ghostmind.optdmsa.com/v1/chat/completions \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

10. Save the Conversation ID

The response includes an X-GhostMind-Conversation-Id header. Save this — you need it to continue the conversation:

Terminal window
# Capture the conversation ID from the response header
CONV_ID=$(curl -s -D - -X POST https://ghostmind.optdmsa.com/v1/chat/completions \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"What is 2+2?"}]}' \
  | grep -i "x-ghostmind-conversation-id" | awk '{print $2}' | tr -d '\r')

11. Continue the Conversation

Terminal window
curl -X POST https://ghostmind.optdmsa.com/v1/chat/completions \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-GhostMind-Conversation-Id: $CONV_ID" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Now multiply that by 3."}]}'

12. Send a File or Image

Terminal window
# Upload a file to the conversation
curl -X POST "https://ghostmind.optdmsa.com/v1/conversations/$CONV_ID/attachments" \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY" \
  -F "file=@document.pdf"


# Reference it in a chat request
curl -X POST https://ghostmind.optdmsa.com/v1/chat/completions \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-GhostMind-Conversation-Id: $CONV_ID" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Summarize this document."}],
    "attachment_file_ids": ["file_abc123"]
  }'

13. Receive Generated Artifacts

When ChatGPT generates an image or file, the response includes an assets array with structured metadata. Do not parse base64 from message content — use the structured assets array and download through GhostMind:

Terminal window
# Poll asset status until ready
curl https://ghostmind.optdmsa.com/v1/assets/$ASSET_ID \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY"


# Download when status is "ready"
curl https://ghostmind.optdmsa.com/v1/assets/$ASSET_ID/download \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY" \
  -o generated_image.png

14. Transcribe Audio

Terminal window
curl -X POST https://ghostmind.optdmsa.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY" \
  -F "file=@recording.wav" \
  -F "model=ghostmind-transcribe"

15. Generate Speech (TTS)

Terminal window
# Discover available voices (voice names are in Arabic script)
curl https://ghostmind.optdmsa.com/v1/audio/providers/google_ai_studio_savio_tts/voices \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY"


# Create a TTS job — use a voice name from the voices endpoint above
# Voice names are in Arabic script (e.g., يوسف, مالك, رامي)
curl -X POST https://ghostmind.optdmsa.com/v1/audio/speech \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"google_ai_studio_savio_tts","input":"Hello world","voice":"يوسف"}'


# The response returns a job ID and status_url (HTTP 202)
# Poll for completion
curl https://ghostmind.optdmsa.com/v1/audio/generations/$JOB_ID \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY"


# When status is "completed", download the audio
curl https://ghostmind.optdmsa.com/v1/audio/generations/$JOB_ID/content \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY" \
  -o audio.wav

Note: Voice names are in Arabic script (e.g., يوسف, مالك). Always fetch available voices from the voices endpoint first — do not hardcode voice names. The TTS endpoint may return 202 with a job ID even for synchronous requests, requiring polling.

16. Handle Errors

All errors use a canonical envelope with machine-readable codes:

{
  "error": {
    "code": "ACCOUNT_REAUTH_REQUIRED",
    "message": "ChatGPT session expired. Reconnect the account.",
    "type": "account_error",
    "request_id": "req_abc123",
    "retryable": false
  }
}
  • Retry errors where retryable: true with exponential backoff
  • Do not retry retryable: false errors — fix the root cause
  • Save the request_id for troubleshooting
  • In streaming, errors are response.failed lifecycle events — not assistant content

See Errors for the complete reference.

17. Where to Find the Complete Reference