Geliştirici API'leri hâlâ beta aşamasındadır ve her an değişebilir. Şu an için kişisel test ve denemelere daha uygundur ve üretim ortamında kullanılması henüz önerilmez.
Bu dağıtımda etkinleştirilen 59 özelliği REST üzerinden çağırın veya MCP uyumlu yapay zekâ araçlarında doğrudan kullanın. Etkin abonelik gerekir.
Codex MCP, REST, Claude Code, Cursor ve manuel MCP istemcileri özel API anahtarları kullanır. Codex, statik Authorization başlığını kullanıcı yapılandırmasında saklar; anahtarı asla sohbet veya kabuk geçmişi üzerinden göndermeyin.
Her istek aboneliğinize bağlı bir API anahtarıyla doğrulanır.
Authorization: Bearer YOUR_API_KEYSüresi dolan abonelik 403 döndürür ve mevcut API anahtarları yenilemeden sonra yeniden çalışır. Yalnızca ACCOUNT_SESSION_REFRESH_REQUIRED, VidMage’e bir kez giriş yapılarak düzeltilir; diğer 401 hataları için ilgili kurtarma eylemini izleyin.
Yerel görsel, video veya sesi doğrudan depolamaya yüklemek için kısa ömürlü ve boyuta bağlı bir URL kullanın. Dosya baytları VidMage uygulama sunucusundan geçmez.
curl -X POST "https://vidmage.ai/api/v1/files/upload" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "capability": "video-upscaler", "parameter": "videoURL", "duration": 7.25, "fileName": "input.mp4", "localPath": "./input.mp4", "contentType": "video/mp4", "fileSize": 12345678 }'
# -> { "uploadCommand": "curl ...", "fileUrl": "https://..." }
# Run uploadCommand once, then use fileUrl in the generation request.# ~/.codex/config.toml
# Direct, persistent user-level MCP registration; this is not a plugin install.
# Replace any existing [mcp_servers.vidmage] table; do not append a duplicate.
[mcp_servers.vidmage]
url = "https://vidmage.ai/api/mcp"
http_headers = { Authorization = "Bearer YOUR_API_KEY" }
enabled = true
required = true
startup_timeout_sec = 30
tool_timeout_sec = 120
# Save this file, then confirm persistence with: codex mcp get vidmage
# Restrict the user-level file after saving: chmod 600 ~/.codex/config.toml
# Diagnose this direct server from VidMage startup errors; a remote Plugins catalog 401 is unrelated.
# Fully restart Codex, create a new task, and call list_capabilities.Önce list_capabilities çağrısı yapın. Üretim için yeni ve kararlı bir idempotencyKey kullanın, submit_task işlevini tam bir kez çağırın ve ardından aynı taskId’yi sorgulayın. Yanıt kaybolursa önce get_recent_tasks çağrısı yapın; özgün anahtarı yalnızca aynı gönderimin aktarım tekrarında kullanın.
list_models → estimate_model_creditsHer istek aboneliğinize bağlı bir API anahtarıyla doğrulanır.
list_capabilities (metinden görsele)
→ describe_capability
→ submit_task + yeni kararlı idempotencyKey (tam bir kez)
→ get_task_result (aynı görevi sorgula)
→ get_recent_tasks (yalnızca yanıt kaybolduysa)
→ özgün görsel sonucuTüm yapay zekâ görevleri asenkrondur. Her özellik iki endpoint sunar:
| Endpoint | Açıklama |
|---|---|
| GET /api/v1/capabilities | Her istek aboneliğinize bağlı bir API anahtarıyla doğrulanır. |
| GET /api/v1/openapi.json | Her istek aboneliğinize bağlı bir API anahtarıyla doğrulanır. |
| POST /api/v1/files/upload | Yerel bir medya dosyası için kısıtlı ve geçici bir doğrudan yükleme URL’si oluşturur. |
| GET /api/v1/tasks/recent | Zaman aşımı, bağlantı kesilmesi veya kayıp yanıttan sonra son görev kimliklerini kurtarır. |
| POST /api/v1/<capability>/submit | Bir görev başlatır ve görev kimliğini hemen döndürür. |
| POST /api/v1/<capability>/query | Görevi kimliğine göre kontrol eder; tamamlandığında durumunu ve sonuç URL'sini döndürür. |
curl -X POST "https://vidmage.ai/api/v1/face-swap/submit" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"targetImageUrl":"https://vidmage.ai/assets/images/samples/blue-eyed-woman-sunlight.webp","referenceFaceImageUrl":"https://vidmage.ai/assets/images/samples/smiling-man-sweater.webp"}'
# -> { "success": true, "taskId": "...", "creditsRequired": ..., "creditsConsumed": 0, "usageDeferred": true }curl -X POST "https://vidmage.ai/api/v1/face-swap/query" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "taskId": "TASK_ID_FROM_SUBMIT" }'
# -> { "success": true, "data": { "status": "...", "imageUrl": "https://..." } }Özellik kataloğu ve OpenAPI 3.1 belgesi, istek doğrulamasında kullanılan aynı sözleşmeden oluşturulur. Spesifikasyonu Postman, Insomnia, Bruno veya bir API istemci oluşturucusuna aktarın.
curl -H "Authorization: Bearer YOUR_API_KEY" "https://vidmage.ai/api/v1/capabilities"curl -H "Authorization: Bearer YOUR_API_KEY" "https://vidmage.ai/api/v1/openapi.json" --output vidmage-openapi.jsoncurl -H "Authorization: Bearer YOUR_API_KEY" "https://vidmage.ai/api/v1/tasks/recent?limit=10"Bu örnekler görevi bir kez gönderir ve tamamlanana kadar aynı görev kimliğini sorgular. Aynı gönderimi yeniden denerken idempotency anahtarını değiştirmeyin.
const submitResponse = await fetch('https://vidmage.ai/api/v1/face-swap/submit', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.VIDMAGE_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"targetImageUrl": "https://vidmage.ai/assets/images/samples/blue-eyed-woman-sunlight.webp",
"referenceFaceImageUrl": "https://vidmage.ai/assets/images/samples/smiling-man-sweater.webp"
}),
})
const submitted = await submitResponse.json()
if (!submitResponse.ok || !submitted.success) {
throw new Error(submitted.message ?? submitted.error ?? 'Task submission failed')
}
const taskId = submitted["taskId"]
if (!taskId) throw new Error('Submit succeeded without a task id')
while (true) {
await new Promise(resolve => setTimeout(resolve, 5000))
const queryResponse = await fetch('https://vidmage.ai/api/v1/face-swap/query', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.VIDMAGE_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ taskId: taskId }),
})
const queried = await queryResponse.json()
if (!queryResponse.ok || !queried.success) {
throw new Error(queried.message ?? queried.error ?? 'Task query failed')
}
const data = queried.data ?? queried
const status = String(data.status ?? '').toLowerCase()
if (['success', 'succeeded', 'completed'].includes(status)) {
console.log(queried.result ?? queried["imageUrl"] ?? data["imageUrl"])
break
}
if (['failed', 'error'].includes(status)) {
throw new Error(data.errorDetail ?? data.error ?? 'Task failed')
}
}import os
import time
import requests
submit_response = requests.post(
"https://vidmage.ai/api/v1/face-swap/submit",
headers={
"Authorization": f"Bearer {os.environ['VIDMAGE_API_KEY']}",
},
json={
"targetImageUrl": "https://vidmage.ai/assets/images/samples/blue-eyed-woman-sunlight.webp",
"referenceFaceImageUrl": "https://vidmage.ai/assets/images/samples/smiling-man-sweater.webp",
},
timeout=60,
)
submitted = submit_response.json()
if not submit_response.ok or not submitted.get("success"):
raise RuntimeError(submitted.get("message") or submitted.get("error") or "Task submission failed")
task_id = submitted["taskId"]
if not task_id:
raise RuntimeError("Submit succeeded without a task id")
while True:
time.sleep(5)
query_response = requests.post(
"https://vidmage.ai/api/v1/face-swap/query",
headers={"Authorization": f"Bearer {os.environ['VIDMAGE_API_KEY']}"},
json={"taskId": task_id},
timeout=60,
)
queried = query_response.json()
if not query_response.ok or not queried.get("success"):
raise RuntimeError(queried.get("message") or queried.get("error") or "Task query failed")
data = queried.get("data") or queried
status = str(data.get("status") or "").lower()
if status in {"success", "succeeded", "completed"}:
print(queried.get("result") or queried.get("imageUrl") or data.get("imageUrl"))
break
if status in {"failed", "error"}:
raise RuntimeError(data.get("errorDetail") or data.get("error") or "Task failed")Kontrol akışı için HTTP durumunu, özel kurtarma davranışı için errorType değerini kullanın. Her REST yanıtı izleme ve destek için X-Request-Id header'ını içerir.
| Durum | Yaygın errorType | Önerilen işlem |
|---|---|---|
| 400 | INVALID_JSON / VALIDATION_ERROR | details içinde belirtilen alanları düzeltin; aynı girdiyi değiştirmeden yeniden denemeyin. |
| 401 | AUTHENTICATION_REQUIRED | VidMage kimlik bilgisi almadı. Codex kullanıcı yapılandırmasına veya hedef istemciye Authorization ekleyin; sohbette asla API anahtarı istemeyin veya yapıştırmayın. |
| 401 | AUTHORIZATION_HEADER_INVALID | Authorization Header değerini tam olarak Bearer <API_KEY> biçimine düzeltin; görev gönderilmedi. |
| 401 | API_KEY_INVALID_OR_REVOKED | Yeni bir API anahtarı oluşturun ve mevcut yapılandırmada yalnızca Authorization değerini değiştirin; Codex’i yeniden başlatıp yeni görevde doğrulayın. |
| 401 | API_KEY_INVALID_CREDENTIAL | Yeni bir API anahtarı oluşturun ve hedef istemcideki kimlik bilgisini değiştirin; mevcut kimlik bilgisinin şifresi çözülemiyor. |
| 401 | ACCOUNT_SESSION_REFRESH_REQUIRED | VidMage’e bir kez giriş yapın. Hizmet, mevcut API anahtarlarında sarılı arka uç hesap kimlik bilgisini yeniler; istemci yapılandırması değişmez. |
| 401 REST | NEED_API_KEY | Yalnızca REST uyumluluğu: bir API anahtarı sağlayın. |
| 402 | NEED_PURCHASE_CREDITS | Kredi ekleyin veya daha düşük maliyetli bir işlem seçin. |
| 403 | NEED_SUBSCRIBE | Hesap aboneliğini etkinleştirin veya yenileyin. |
| 404 | CAPABILITY_NOT_ENABLED | Özellik keşfini yenileyin. Özellik devre dışı veya bu dağıtımda kullanılamıyor. |
| 409 | UPLOAD_NOT_READY / IDEMPOTENCY_CONFLICT / IDEMPOTENCY_IN_PROGRESS | Gönderim hâlâ işleniyorsa belirtilen süreyi bekleyin ve aynı idempotencyKey değerini yeniden kullanın. Yeni anahtarı yalnızca farklı bir üretim isteği için oluşturun. |
| 410 | UPLOAD_EXPIRED | Yeni bir geçici yükleme oluşturun; önceki dosya URL’sinin süresi doldu. |
| 429 | RATE_LIMITED | Retry-After süresi kadar bekleyin, ardından sınırlı üstel backoff ile yeniden deneyin. |
| 503 | CREDENTIAL_STORAGE_UNAVAILABLE | Retry-After değerine uyun ve yalnızca bir kez yeniden deneyin. Sorun sürerse durun, requestId değerini bildirin ve operatörden Developers MySQL readiness durumunu düzeltmesini isteyin. API anahtarını koruyun ve yeniden göndermeyin. |
| 503 / MCP | SUBMISSION_OUTCOME_UNKNOWN / BILLING_OUTCOME_UNKNOWN / REFUND_OUTCOME_UNKNOWN | Önce recovery değerini izleyin: GET_RECENT_TASKS, get_recent_tasks çağrısı yapmayı; QUERY_TASK_ID_OR_CONTACT_SUPPORT, aynı taskId’yi sorgulamayı veya desteğe başvurmayı; CONTACT_SUPPORT_WITH_IDEMPOTENCY_KEY_AND_BUSINESS_ID, idempotencyKey ve businessId ile desteğe başvurmayı ifade eder. Asla yeni bir idempotencyKey oluşturmayın, yeniden göndermeyin veya başka bir geri ödeme denemeyin. |
| 503 / MCP | TASK_PERSISTENCE_UNCERTAIN | taskId değerini saklayın, görevi yeniden göndermeyin ve sorun sürerse taskId ile desteğe başvurun. |
| MCP | TASK_QUERY_INTERRUPTED | Aynı taskId değerini sorgulamaya devam edin; başka bir görev göndermeyin. |
| MCP | RESULT_MISSING | Aynı taskId’yi sorgulamayı sürdürün; görevi yeniden göndermeyin. |
| 404 / MCP | TASK_NOT_FOUND | Yeniden denemeden önce get_recent_tasks çağrısı yapın; ücretli bir görevi yeniden göndermeyin. |
| 502 / MCP | BILLING_INVARIANT_FAILED | Yeniden denemeyin, API anahtarını değiştirmeyin, özgün Idempotency-Key değerini değiştirmeyin veya yeniden göndermeyin. Varsa taskId, capability ve özgün Idempotency-Key ile desteğe başvurun; REST için X-Request-Id değerini de ekleyin. |
| 5xx | *_SERVICE_UNAVAILABLE / UPSTREAM_* | Diğer 5xx hatalarında sınırlı üstel backoff kullanın ve görev kimliğini saklayın. Bu, CREDENTIAL_STORAGE_UNAVAILABLE için geçerli değildir. |
Aşağıdaki parametreler submit için request body’yi oluşturur. query ile sorgularken aynı görev kimliği alanını kullanın.