Las API para desarrolladores aún están en fase beta y pueden cambiar en cualquier momento. Por ahora son más adecuadas para pruebas y experimentación personales, y todavía no se recomienda usarlas en producción.
Llama mediante REST a las 59 funciones habilitadas en este despliegue o úsalas en herramientas de IA compatibles con MCP. Se requiere una suscripción activa.
Codex MCP, REST, Claude Code, Cursor y los clientes MCP manuales usan claves API dedicadas. Codex guarda el encabezado Authorization estático en la configuración del usuario; nunca envíes una clave por chat ni por el historial del shell.
Cada solicitud se autentica con una clave API vinculada a tu suscripción.
Authorization: Bearer YOUR_API_KEYUna suscripción caducada devuelve 403 y las claves API existentes vuelven a funcionar tras renovarla. Solo ACCOUNT_SESSION_REFRESH_REQUIRED se corrige iniciando sesión una vez en VidMage; sigue la recuperación específica para los demás errores 401.
Usa una URL de corta duración y vinculada al tamaño para subir imágenes, vídeos o audio locales directamente al almacenamiento. Los bytes del archivo no pasan por el servidor de la aplicación 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.Llama primero a list_capabilities. Para generar, usa un idempotencyKey nuevo y estable, llama a submit_task exactamente una vez y consulta después el mismo taskId. Si se pierde la respuesta, llama primero a get_recent_tasks; reutiliza la clave original solo para reintentar el transporte del mismo envío.
list_models → estimate_model_creditsCada solicitud se autentica con una clave API vinculada a tu suscripción.
list_capabilities (texto a imagen)
→ describe_capability
→ submit_task + idempotencyKey nuevo y estable (una sola vez)
→ get_task_result (consultar la misma tarea)
→ get_recent_tasks (solo si se perdió la respuesta)
→ resultado de imagen nativoTodas las tareas de IA son asíncronas. Cada función ofrece dos endpoints:
| Endpoint | Descripción |
|---|---|
| GET /api/v1/capabilities | Cada solicitud se autentica con una clave API vinculada a tu suscripción. |
| GET /api/v1/openapi.json | Cada solicitud se autentica con una clave API vinculada a tu suscripción. |
| POST /api/v1/files/upload | Crea una URL temporal y restringida de carga directa para un archivo multimedia local. |
| GET /api/v1/tasks/recent | Recupera IDs de tareas recientes tras un tiempo de espera, desconexión o respuesta perdida. |
| POST /api/v1/<capability>/submit | Inicia una tarea y devuelve su ID de inmediato. |
| POST /api/v1/<capability>/query | Consulta una tarea por ID y devuelve su estado y la URL del resultado al finalizar. |
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://..." } }El catálogo de funciones y el documento OpenAPI 3.1 se generan a partir del mismo contrato usado para validar solicitudes. Importa la especificación en Postman, Insomnia, Bruno o un generador de clientes 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"Estos ejemplos envían una tarea una sola vez y consultan el mismo ID hasta que finaliza. Conserva la misma clave de idempotencia al reintentar el mismo envío.
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")Usa el estado HTTP para controlar el flujo y errorType para aplicar la recuperación adecuada. Cada respuesta REST incluye X-Request-Id para seguimiento y soporte.
| Estado | errorType habitual | Acción recomendada |
|---|---|---|
| 400 | INVALID_JSON / VALIDATION_ERROR | Corrige los campos indicados en details; no repitas la misma entrada sin cambios. |
| 401 | AUTHENTICATION_REQUIRED | VidMage no recibió credenciales. Añade Authorization a la configuración de usuario de Codex o al cliente de destino; nunca solicites ni pegues una clave API en el chat. |
| 401 | AUTHORIZATION_HEADER_INVALID | Corrige el Authorization Header para que sea exactamente Bearer <API_KEY>; no se envió ninguna tarea. |
| 401 | API_KEY_INVALID_OR_REVOKED | Crea una clave API nueva y sustituye solo Authorization en la configuración existente; reinicia Codex y verifica en una tarea nueva. |
| 401 | API_KEY_INVALID_CREDENTIAL | Crea una clave API nueva y sustituye la credencial en el cliente de destino; la credencial actual no se puede descifrar. |
| 401 | ACCOUNT_SESSION_REFRESH_REQUIRED | Inicia sesión una vez en VidMage. El servicio actualiza la credencial de cuenta incluida en las claves API existentes; la configuración del cliente no cambia. |
| 401 REST | NEED_API_KEY | Solo para compatibilidad con REST: proporciona una clave API. |
| 402 | NEED_PURCHASE_CREDITS | Añade créditos o elige una operación de menor coste. |
| 403 | NEED_SUBSCRIBE | Activa o renueva la suscripción de la cuenta. |
| 404 | CAPABILITY_NOT_ENABLED | Actualiza el descubrimiento de funciones. La función está desactivada o no existe en este despliegue. |
| 409 | UPLOAD_NOT_READY / IDEMPOTENCY_CONFLICT / IDEMPOTENCY_IN_PROGRESS | Si el envío sigue en proceso, espera el tiempo indicado y reutiliza el mismo idempotencyKey. Crea una clave nueva solo para otra solicitud de generación. |
| 410 | UPLOAD_EXPIRED | Crea una nueva carga temporal; la URL anterior ha caducado. |
| 429 | RATE_LIMITED | Espera el tiempo indicado en Retry-After y reintenta con retroceso exponencial limitado. |
| 503 | CREDENTIAL_STORAGE_UNAVAILABLE | Respeta Retry-After y reintenta solo una vez. Si continúa, detente, informa de requestId y pide a operaciones que restaure Developers MySQL readiness. Conserva la clave API y no reenvíes. |
| 503 / MCP | SUBMISSION_OUTCOME_UNKNOWN / BILLING_OUTCOME_UNKNOWN / REFUND_OUTCOME_UNKNOWN | Sigue primero recovery: GET_RECENT_TASKS significa llamar a get_recent_tasks; QUERY_TASK_ID_OR_CONTACT_SUPPORT significa consultar el mismo taskId o contactar con soporte; CONTACT_SUPPORT_WITH_IDEMPOTENCY_KEY_AND_BUSINESS_ID significa contactar con soporte indicando idempotencyKey y businessId. Nunca crees un idempotencyKey nuevo ni vuelvas a enviar la tarea. |
| 503 / MCP | TASK_PERSISTENCE_UNCERTAIN | Conserva taskId, no vuelvas a enviar la tarea y, si el problema persiste, contacta con soporte indicando taskId. |
| MCP | TASK_QUERY_INTERRUPTED | Continúa consultando el mismo taskId; no envíes otra tarea. |
| MCP | RESULT_MISSING | Sigue consultando el mismo taskId; no vuelvas a enviar la tarea. |
| 404 / MCP | TASK_NOT_FOUND | Llama a get_recent_tasks antes de reintentar; no vuelvas a enviar una tarea de pago. |
| 502 / MCP | BILLING_INVARIANT_FAILED | No reintentes, cambies la clave API, modifiques el Idempotency-Key original ni reenvíes la tarea. Contacta con soporte indicando taskId si aparece, capability y el Idempotency-Key original; con REST, incluye también X-Request-Id. |
| 5xx | *_SERVICE_UNAVAILABLE / UPSTREAM_* | Para otros errores 5xx, reintenta con retroceso exponencial limitado y conserva el ID de tarea. No se aplica a CREDENTIAL_STORAGE_UNAVAILABLE. |
Los parámetros siguientes forman el cuerpo de la solicitud submit. Usa el mismo campo de ID al consultar query.