डेवलपर API अभी बीटा चरण में हैं और कभी भी बदल सकते हैं। फिलहाल, ये व्यक्तिगत परीक्षण और प्रयोग के लिए अधिक उपयुक्त हैं और प्रोडक्शन में उपयोग के लिए अभी अनुशंसित नहीं हैं।
इस डिप्लॉयमेंट के लिए सक्षम 59 क्षमताओं को REST से कॉल करें या MCP-संगत AI टूल में सीधे उपयोग करें। सक्रिय सदस्यता आवश्यक है।
Codex MCP, REST, Claude Code, Cursor और मैन्युअल MCP क्लाइंट समर्पित API कुंजियाँ उपयोग करते हैं। Codex स्थिर Authorization हेडर को उपयोगकर्ता कॉन्फ़िगरेशन में सहेजता है; कुंजी को चैट या शेल इतिहास में कभी न भेजें।
हर अनुरोध आपकी सदस्यता से जुड़ी API कुंजी द्वारा प्रमाणित किया जाता है।
Authorization: Bearer YOUR_API_KEYसदस्यता समाप्त होने पर 403 लौटता है और नवीनीकरण के बाद मौजूदा API कुंजियाँ फिर चलती हैं। केवल ACCOUNT_SESSION_REFRESH_REQUIRED को VidMage में एक बार साइन इन करके सुधारा जाता है; अन्य 401 के लिए संबंधित पुनर्प्राप्ति कार्रवाई अपनाएँ।
स्थानीय इमेज, वीडियो या ऑडियो को सीधे स्टोरेज में अपलोड करने के लिए कम अवधि और तय आकार वाला URL उपयोग करें। फ़ाइल बाइट्स VidMage ऐप्लिकेशन सर्वर से नहीं गुजरते।
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.पहले list_capabilities कॉल करें। जनरेशन के लिए नया और स्थिर idempotencyKey उपयोग करें, submit_task ठीक एक बार कॉल करें, फिर उसी taskId को पोल करें। जवाब खो जाए तो पहले get_recent_tasks कॉल करें; मूल कुंजी का पुनः उपयोग केवल उसी सबमिशन के ट्रांसपोर्ट रीट्राई में करें।
list_models → estimate_model_creditsहर अनुरोध आपकी सदस्यता से जुड़ी API कुंजी द्वारा प्रमाणित किया जाता है।
list_capabilities (टेक्स्ट से इमेज)
→ describe_capability
→ submit_task + नया स्थिर idempotencyKey (केवल एक बार)
→ get_task_result (उसी टास्क को पोल करें)
→ get_recent_tasks (केवल जवाब खोने पर)
→ मूल इमेज परिणामसभी AI टास्क असिंक्रोनस हैं। हर क्षमता दो endpoint देती है:
| Endpoint | विवरण |
|---|---|
| GET /api/v1/capabilities | हर अनुरोध आपकी सदस्यता से जुड़ी API कुंजी द्वारा प्रमाणित किया जाता है। |
| GET /api/v1/openapi.json | हर अनुरोध आपकी सदस्यता से जुड़ी API कुंजी द्वारा प्रमाणित किया जाता है। |
| POST /api/v1/files/upload | स्थानीय मीडिया फ़ाइल के लिए सीमित अस्थायी डायरेक्ट-अपलोड URL बनाता है। |
| GET /api/v1/tasks/recent | टाइमआउट, डिस्कनेक्ट या खोए हुए उत्तर के बाद हाल की टास्क ID वापस पाता है। |
| POST /api/v1/<capability>/submit | टास्क शुरू करता है और तुरंत उसका टास्क ID लौटाता है। |
| POST /api/v1/<capability>/query | ID से टास्क जाँचता है और पूरा होने पर स्थिति तथा परिणाम URL लौटाता है। |
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://..." } }क्षमता कैटलॉग और OpenAPI 3.1 दस्तावेज़ उसी कॉन्ट्रैक्ट से बनते हैं जिसका उपयोग अनुरोध सत्यापित करने में होता है। स्पेसिफ़िकेशन को Postman, Insomnia, Bruno या API क्लाइंट जनरेटर में इम्पोर्ट करें।
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"ये उदाहरण टास्क को एक बार सबमिट करते हैं और पूरा होने तक उसी टास्क ID की स्थिति जाँचते हैं। उसी सबमिशन को दोबारा आज़माते समय idempotency key को न बदलें।
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")कंट्रोल फ़्लो के लिए HTTP स्थिति और विशेष रिकवरी के लिए errorType का उपयोग करें। हर REST प्रतिक्रिया में ट्रेसिंग और सहायता के लिए X-Request-Id header होता है।
| स्थिति | सामान्य errorType | सुझाई गई कार्रवाई |
|---|---|---|
| 400 | INVALID_JSON / VALIDATION_ERROR | details में दिए गए फ़ील्ड ठीक करें; वही अपरिवर्तित इनपुट दोबारा न भेजें। |
| 401 | AUTHENTICATION_REQUIRED | VidMage को कोई क्रेडेंशियल नहीं मिला। Codex उपयोगकर्ता कॉन्फ़िगरेशन या लक्ष्य क्लाइंट में Authorization जोड़ें; चैट में API कुंजी कभी न माँगें या चिपकाएँ। |
| 401 | AUTHORIZATION_HEADER_INVALID | Authorization Header को ठीक Bearer <API_KEY> करें; कोई टास्क सबमिट नहीं हुआ। |
| 401 | API_KEY_INVALID_OR_REVOKED | नई API कुंजी बनाएँ और मौजूदा कॉन्फ़िगरेशन में केवल Authorization बदलें; Codex रीस्टार्ट करके नए टास्क में सत्यापित करें। |
| 401 | API_KEY_INVALID_CREDENTIAL | नई API कुंजी बनाएँ और लक्षित क्लाइंट में क्रेडेंशियल बदलें; मौजूदा क्रेडेंशियल को डिक्रिप्ट नहीं किया जा सकता। |
| 401 | ACCOUNT_SESSION_REFRESH_REQUIRED | VidMage में एक बार लॉगिन करें। सेवा मौजूदा API कुंजियों में सुरक्षित बैकएंड खाता क्रेडेंशियल रीफ़्रेश करती है; क्लाइंट कॉन्फ़िगरेशन नहीं बदलता। |
| 401 REST | NEED_API_KEY | केवल REST संगतता के लिए: API कुंजी दें। |
| 402 | NEED_PURCHASE_CREDITS | क्रेडिट जोड़ें या कम लागत वाला ऑपरेशन चुनें। |
| 403 | NEED_SUBSCRIBE | खाते की सदस्यता सक्रिय करें या नवीनीकृत करें। |
| 404 | CAPABILITY_NOT_ENABLED | क्षमता discovery रीफ़्रेश करें। क्षमता बंद है या इस डिप्लॉयमेंट में उपलब्ध नहीं है। |
| 409 | UPLOAD_NOT_READY / IDEMPOTENCY_CONFLICT / IDEMPOTENCY_IN_PROGRESS | यदि सबमिशन अभी चल रहा है, बताए गए समय तक प्रतीक्षा करें और वही idempotencyKey दोबारा उपयोग करें। नई कुंजी केवल अलग जनरेशन अनुरोध के लिए बनाएँ। |
| 410 | UPLOAD_EXPIRED | नया अस्थायी अपलोड बनाएँ; पिछली फ़ाइल URL की समय-सीमा समाप्त हो गई है। |
| 429 | RATE_LIMITED | Retry-After अवधि तक प्रतीक्षा करें, फिर सीमित exponential backoff के साथ दोबारा कोशिश करें। |
| 503 | CREDENTIAL_STORAGE_UNAVAILABLE | Retry-After का पालन करें और केवल एक बार पुनः प्रयास करें। समस्या बनी रहे तो रुकें, requestId रिपोर्ट करें और ऑपरेटर से Developers MySQL readiness बहाल करने को कहें। API कुंजी रखें और दोबारा सबमिट न करें। |
| 503 / MCP | SUBMISSION_OUTCOME_UNKNOWN / BILLING_OUTCOME_UNKNOWN / REFUND_OUTCOME_UNKNOWN | पहले recovery का पालन करें: GET_RECENT_TASKS का अर्थ get_recent_tasks कॉल करना है; QUERY_TASK_ID_OR_CONTACT_SUPPORT का अर्थ उसी taskId को क्वेरी करना या सहायता टीम से संपर्क करना है; CONTACT_SUPPORT_WITH_IDEMPOTENCY_KEY_AND_BUSINESS_ID का अर्थ idempotencyKey और businessId के साथ सहायता टीम से संपर्क करना है। नया idempotencyKey न बनाएँ, दोबारा सबमिट न करें और फिर से रिफ़ंड का प्रयास न करें। |
| 503 / MCP | TASK_PERSISTENCE_UNCERTAIN | taskId सुरक्षित रखें, टास्क दोबारा सबमिट न करें और समस्या बनी रहने पर taskId के साथ सहायता टीम से संपर्क करें। |
| MCP | TASK_QUERY_INTERRUPTED | उसी taskId को फिर से पोल करना जारी रखें; दूसरा टास्क सबमिट न करें। |
| MCP | RESULT_MISSING | उसी taskId को पोल करते रहें; टास्क दोबारा सबमिट न करें। |
| 404 / MCP | TASK_NOT_FOUND | रीट्राई से पहले get_recent_tasks कॉल करें; भुगतान वाला टास्क दोबारा सबमिट न करें। |
| 502 / MCP | BILLING_INVARIANT_FAILED | दोबारा प्रयास न करें, API कुंजी न बदलें, मूल Idempotency-Key में बदलाव न करें और टास्क दोबारा सबमिट न करें। सहायता टीम को taskId उपलब्ध होने पर, capability और मूल Idempotency-Key दें; REST के लिए X-Request-Id भी दें। |
| 5xx | *_SERVICE_UNAVAILABLE / UPSTREAM_* | अन्य 5xx त्रुटियों के लिए सीमित exponential backoff अपनाएँ और टास्क ID रखें। यह CREDENTIAL_STORAGE_UNAVAILABLE पर लागू नहीं होता। |
नीचे दिए गए पैरामीटर submit के लिए request body बनाते हैं। query से polling करते समय उसी टास्क ID फ़ील्ड का उपयोग करें।