Skip to main content

​
How It Works

All generation requests in ModelHunter.AI are asynchronous. When you submit a request, you receive a task ID immediately. The actual generation happens in the background.

​
Task Lifecycle

Every task progresses through these states:
StatusDescription
pendingRequest received, queued for processing
queuedSent to the provider, waiting in their queue
runningProvider is actively generating
succeededGeneration complete, result available
failedGeneration failed, error details available
cancelledCancelled by the user before completion
expiredResult URL has expired (re-fetch to get a new one)

​
Getting Results

There are two ways to receive results:

​
Option 1: Polling (Simple)

Poll GET /api/v1/tasks/{id} until the status is succeeded or failed. 
// Submit a generation request
const response = await fetch('https://api.modelhunter.ai/api/v1/vidu/text-to-video', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.MODELHUNTER_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'viduq2-pro-fast',
    input: {
      prompt: 'A sunset over the ocean',
      duration: 4,
    },
  }),
});

const task = await response.json();

// Poll until complete
const result = await fetch(`https://api.modelhunter.ai/api/v1/tasks/${task.data.id}`, {
  headers: { 'Authorization': `Bearer ${process.env.MODELHUNTER_KEY}` },
}).then(r => r.json());

console.log(result.data.result[0].url);
Recommended polling interval: Start at 2 seconds, increase to 5 seconds after 30 seconds. Pass a webhookUrl in the generation request. ModelHunter.AI will POST the result directly to your server when the task completes. 
{
  "model": "viduq2-pro-fast",
  "input": {
    "prompt": "A sunset over the ocean",
    "duration": 4
  },
  "webhookUrl": "https://your-server.com/webhooks/modelhunter"
}
See Webhooks for full details on payload format and signature verification.

​
Result URLs

Result URLs are signed URLs valid for 15 minutes. If a URL expires, fetch the task again to get a fresh URL. 
# Re-fetch to get a new signed URL
curl https://api.modelhunter.ai/api/v1/tasks/{id} \
  -H "Authorization: Bearer river_live_xxx"

​
Cancelling Tasks

Cancel a task that hasn’t completed yet: 
curl -X DELETE https://api.modelhunter.ai/api/v1/tasks/{id} \
  -H "Authorization: Bearer river_live_xxx"
Returns 200 if cancelled successfully, or 409 if the task has already completed.