Utvikler-API-ene er fortsatt i betaversjon og kan endres når som helst. Foreløpig egner de seg best til personlig testing og utprøving og anbefales ennå ikke til produksjonsbruk.
Kall de 59 funksjonene som er aktivert i denne distribusjonen via REST, eller bruk dem direkte i MCP-kompatible AI-verktøy. Et aktivt abonnement er påkrevd.
Codex MCP, REST, Claude Code, Cursor og manuelle MCP-klienter bruker egne API-nøkler. Codex lagrer den statiske Authorization-headeren i brukerkonfigurasjonen; send aldri en nøkkel via chat eller skallhistorikk.
Hver forespørsel autentiseres med en API-nøkkel som er knyttet til abonnementet ditt.
Authorization: Bearer YOUR_API_KEYEt utløpt abonnement returnerer 403, og eksisterende API-nøkler virker igjen etter fornyelse. Bare ACCOUNT_SESSION_REFRESH_REQUIRED løses ved å logge inn på VidMage én gang; følg angitt gjenoppretting for andre 401-feil.
Bruk en kortvarig, størrelsesbundet URL for å laste opp lokale bilder, videoer eller lyd direkte til lagring. Filbytene går ikke gjennom VidMage-applikasjonsserveren.
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.Kall list_capabilities først. Bruk en ny, stabil idempotencyKey for generering, kall submit_task nøyaktig én gang, og hent deretter samme taskId. Hvis svaret går tapt, kall get_recent_tasks først; bruk bare den opprinnelige nøkkelen til en transportgjentakelse av samme innsending.
list_models → estimate_model_creditsHver forespørsel autentiseres med en API-nøkkel som er knyttet til abonnementet ditt.
list_capabilities (tekst til bilde)
→ describe_capability
→ submit_task + ny stabil idempotencyKey (nøyaktig én gang)
→ get_task_result (hent samme oppgave)
→ get_recent_tasks (bare hvis svaret gikk tapt)
→ opprinnelig bilderesultatAlle AI-oppgaver er asynkrone. Hver funksjon har to endepunkter:
| Endepunkt | Beskrivelse |
|---|---|
| GET /api/v1/capabilities | Hver forespørsel autentiseres med en API-nøkkel som er knyttet til abonnementet ditt. |
| GET /api/v1/openapi.json | Hver forespørsel autentiseres med en API-nøkkel som er knyttet til abonnementet ditt. |
| POST /api/v1/files/upload | Oppretter en begrenset, midlertidig direkteopplastings-URL for en lokal mediefil. |
| GET /api/v1/tasks/recent | Gjenoppretter nylige oppgave-ID-er etter tidsavbrudd, frakobling eller tapt svar. |
| POST /api/v1/<capability>/submit | Starter en oppgave og returnerer oppgave-ID-en umiddelbart. |
| POST /api/v1/<capability>/query | Slår opp en oppgave etter ID og returnerer status og resultat-URL når den er ferdig. |
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://..." } }Funksjonskatalogen og OpenAPI 3.1-dokumentet genereres fra den samme kontrakten som brukes til validering av forespørsler. Importer spesifikasjonen i Postman, Insomnia, Bruno eller en API-klientgenerator.
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"Disse eksemplene sender inn en oppgave én gang og spør etter samme oppgave-ID til den er ferdig. Behold samme idempotency-nøkkel når du prøver den samme innsendingen på nytt.
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")Bruk HTTP-status for kontrollflyt og errorType for konkret gjenoppretting. Alle REST-svar inneholder headeren X-Request-Id for sporing og støtte.
| Status | Vanlig errorType | Anbefalt handling |
|---|---|---|
| 400 | INVALID_JSON / VALIDATION_ERROR | Rett feltene som er oppført i details. Ikke prøv på nytt med de samme uendrede dataene. |
| 401 | AUTHENTICATION_REQUIRED | VidMage mottok ingen legitimasjon. Legg til Authorization i Codex-brukerkonfigurasjonen eller målklienten; be aldri om eller lim inn en API-nøkkel i chatten. |
| 401 | AUTHORIZATION_HEADER_INVALID | Rett Authorization Header til nøyaktig Bearer <API_KEY>; ingen oppgave ble sendt inn. |
| 401 | API_KEY_INVALID_OR_REVOKED | Opprett en ny API-nøkkel og erstatt bare Authorization i eksisterende konfigurasjon; start Codex på nytt og bekreft i en ny oppgave. |
| 401 | API_KEY_INVALID_CREDENTIAL | Opprett en ny API-nøkkel og erstatt legitimasjonen i målklienten; den eksisterende legitimasjonen kan ikke dekrypteres. |
| 401 | ACCOUNT_SESSION_REFRESH_REQUIRED | Logg inn på VidMage én gang. Tjenesten oppdaterer de underliggende kontoopplysningene i eksisterende API-nøkler; klientkonfigurasjonen forblir uendret. |
| 401 REST | NEED_API_KEY | Bare for REST-kompatibilitet: oppgi en API-nøkkel. |
| 402 | NEED_PURCHASE_CREDITS | Legg til kreditter, eller velg en rimeligere operasjon. |
| 403 | NEED_SUBSCRIBE | Aktiver eller forny kontoabonnementet. |
| 404 | CAPABILITY_NOT_ENABLED | Oppdater funksjonsoppdagelsen. Funksjonen er deaktivert eller ikke tilgjengelig i denne distribusjonen. |
| 409 | UPLOAD_NOT_READY / IDEMPOTENCY_CONFLICT / IDEMPOTENCY_IN_PROGRESS | Hvis innsendingen fortsatt behandles, vent den angitte tiden og bruk samme idempotencyKey. Opprett bare en ny nøkkel for en annen genereringsforespørsel. |
| 410 | UPLOAD_EXPIRED | Opprett en ny midlertidig opplasting; den forrige fil-URL-en er utløpt. |
| 429 | RATE_LIMITED | Vent tiden i Retry-After, og prøv igjen med begrenset eksponentiell backoff. |
| 503 | CREDENTIAL_STORAGE_UNAVAILABLE | Følg Retry-After og prøv bare én gang til. Hvis feilen vedvarer, stopp, rapporter requestId og be drift gjenopprette Developers MySQL readiness. Behold API-nøkkelen og ikke send inn på nytt. |
| 503 / MCP | SUBMISSION_OUTCOME_UNKNOWN / BILLING_OUTCOME_UNKNOWN / REFUND_OUTCOME_UNKNOWN | Følg recovery først: GET_RECENT_TASKS betyr å kalle get_recent_tasks; QUERY_TASK_ID_OR_CONTACT_SUPPORT betyr å hente samme taskId eller kontakte kundestøtte; CONTACT_SUPPORT_WITH_IDEMPOTENCY_KEY_AND_BUSINESS_ID betyr å kontakte kundestøtte med idempotencyKey og businessId. Opprett aldri en ny idempotencyKey, send inn på nytt eller forsøk en ny refusjon. |
| 503 / MCP | TASK_PERSISTENCE_UNCERTAIN | Behold taskId, ikke send inn på nytt, og kontakt kundestøtte med taskId hvis problemet vedvarer. |
| MCP | TASK_QUERY_INTERRUPTED | Fortsett å hente samme taskId; ikke send inn en ny oppgave. |
| MCP | RESULT_MISSING | Fortsett å hente samme taskId; ikke send inn oppgaven på nytt. |
| 404 / MCP | TASK_NOT_FOUND | Kall get_recent_tasks før et nytt forsøk; ikke send inn en betalt oppgave på nytt. |
| 502 / MCP | BILLING_INVARIANT_FAILED | Ikke prøv igjen, bytt API-nøkkel, endre den opprinnelige Idempotency-Key eller send inn på nytt. Kontakt kundestøtte med taskId hvis den vises, capability og den opprinnelige Idempotency-Key; for REST tar du også med X-Request-Id. |
| 5xx | *_SERVICE_UNAVAILABLE / UPSTREAM_* | For andre 5xx-feil bruker du begrenset eksponentiell backoff og beholder oppgave-ID-en. Dette gjelder ikke CREDENTIAL_STORAGE_UNAVAILABLE. |
Parameterne nedenfor utgjør request body for submit. Bruk det samme oppgave-ID-feltet ved polling med query.