Skip to main content

​
Overview

All generate endpoints (Video to Video, Video Effects, Face Swap, Image APIs, etc.) accept an optional custom_callback_url field inside args. When provided, GoEnhance sends a POST request to that URL every time the task status changes, so you don’t need to poll the Get Job Status API. 
{
  "args": {
    "prompt": "a cute cat",
    "custom_callback_url": "https://your-server.com/goenhance/callback"
  }
}

​
Requirements

  • The URL must be a publicly accessible HTTPS endpoint.
  • Your server must respond with HTTP 200 within 3 seconds. Do any heavy processing asynchronously after responding.

​
Callback Payload

The request body is identical to the response of Get Job Status (GET /api/v1/jobs/detail), so you can reuse the same parsing logic: 
{
  "code": 0,
  "msg": "Success",
  "data": {
    "img_uuid": "37c82d82-8765-4031-8cb3-722df8a668e6",
    "status": "success",
    "type": "mx-image-face-swap",
    "start_time": "2024-10-11T10:55:32.596Z",
    "end_time": "2024-10-11T10:56:00.338Z",
    "model_id": "-1",
    "json": [
      {
        "type": "image",
        "value": "https://openapi-static.goenhance.ai/user/2024/10/11/9dfdb4b5-7ef7-4fe7-93ff-b9eb76cc431d_0.jpg"
      }
    ],
    "job_type": "mx-image-face-swap"
  }
}
The data.status field is one of:
  • pending: Job is queued and waiting to be processed
  • processing: Job is currently being processed
  • success: Job has finished successfully — results are in data.json
  • failed: Job has failed with an error

​
Retry Policy

If your server does not respond with HTTP 200 (including timeouts and connection errors), the notification is retried up to 3 times, with a 3-second timeout per attempt. If all attempts fail, the notification is dropped — you can always fall back to polling Get Job Status.

​
Best Practices

  1. Respond with 200 immediately after receiving the payload, then process it asynchronously.
  2. Make your handler idempotent — deduplicate by img_uuid + status, as the same notification may be delivered more than once due to retries.
  3. Keep polling as a fallback for critical workflows, in case your endpoint is temporarily unreachable.