# Get Balance
Source: https://docs.modelhunter.ai/api-reference/billing/get-balance

GET https://api.modelhunter.ai/api/v1/balance
Retrieve your current account balance and billing details.

## Response Fields

<ResponseField name="success" type="boolean">
  Whether the request was successful.
</ResponseField>

<ResponseField name="data" type="object">
  Account balance details.

  <Expandable title="data properties">
    <ResponseField name="data.balance" type="number">
      Current available balance in USD (e.g. `45.00`).
    </ResponseField>

    <ResponseField name="data.billingMode" type="string">
      Billing mode. One of: `prepaid` (top-up balance), `postpaid` (card on file, invoiced monthly).
    </ResponseField>

    <ResponseField name="data.monthlySpendLimit" type="number | null">
      Monthly spending limit. `null` if not set.
    </ResponseField>

    <ResponseField name="data.autoTopUpEnabled" type="boolean">
      Whether automatic top-up is enabled.
    </ResponseField>

    <ResponseField name="data.autoTopUpThreshold" type="number | null">
      Balance threshold that triggers auto top-up. `null` if not configured.
    </ResponseField>

    <ResponseField name="data.autoTopUpAmount" type="number | null">
      Amount to add when auto top-up is triggered. `null` if not configured.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "balance": 45.00,
      "billingMode": "prepaid",
      "monthlySpendLimit": null,
      "autoTopUpEnabled": false,
      "autoTopUpThreshold": null,
      "autoTopUpAmount": null
    }
  }
  ```
</ResponseExample>


# Text to Speech
Source: https://docs.modelhunter.ai/api-reference/elevenlabs/text-to-speech

POST https://api.modelhunter.ai/api/v1/elevenlabs/text-to-speech
Generate expressive multi-speaker dialogue audio using Eleven v3.

## Body Parameters

<ParamField type="string">
  ElevenLabs model to use in this phase:

  * `elevenlabs/text-to-dialogue-v3` — billed at `$0.12` per `1000` input characters across all dialogue lines
</ParamField>

<ParamField type="object">
  Input parameters for the generation.

  <Expandable title="properties">
    <ParamField type="array">
      Ordered dialogue lines. Provide at least one item and at most `5000` total input characters across all lines.

      Each dialogue item must include:

      * `text` — Dialogue line text. Inline audio tags such as `[whispering]` are supported.
      * `voice` — ElevenLabs voice ID for that line. Use `GET /api/v1/elevenlabs/voices` to list available voices.
    </ParamField>

    <ParamField type="number">
      Delivery stability hint. Range: `0` to `1`.
    </ParamField>

    <ParamField type="string">
      Language hint for the dialogue. Use `auto` to let the model infer the language.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  URL to receive a webhook when the task completes.
</ParamField>

<ParamField type="object">
  Custom key-value metadata to attach to the task.
</ParamField>

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "data": {
      "id": "task_elevenlabs_tts_123",
      "status": "pending",
      "type": "text-to-speech",
      "provider": "elevenlabs",
      "model": "elevenlabs/text-to-dialogue-v3",
      "created_at": "2026-03-16T10:00:00Z",
      "estimated_seconds": 30
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "input.dialogue must contain at least one line"
    }
  }
  ```
</ResponseExample>


# List Voices
Source: https://docs.modelhunter.ai/api-reference/elevenlabs/voices

GET https://api.modelhunter.ai/api/v1/elevenlabs/voices
List available ElevenLabs voices for use in text-to-speech generation.

## Query Parameters

<ParamField type="string">
  Filter voices by name. Case-insensitive partial match.
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "voices": [
        {
          "voice_id": "JBFqnCBsd6RMkjVDRZzb",
          "name": "George",
          "description": "A warm, friendly male voice with a British accent."
        },
        {
          "voice_id": "EXAVITQu4vr4xnSDxMaL",
          "name": "Sarah",
          "description": "A clear, professional female voice."
        }
      ],
      "total": 2
    }
  }
  ```
</ResponseExample>


# Complete File Upload
Source: https://docs.modelhunter.ai/api-reference/files/complete-upload

POST https://api.modelhunter.ai/api/v1/files/{file_id}/complete
Confirm that a file upload is complete and get the CDN URL.

## Path Parameters

<ParamField type="string">
  File ID from the [Get Upload URL](/api-reference/files/get-upload-url) response.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
  Whether the request was successful.
</ResponseField>

<ResponseField name="data" type="object">
  Uploaded file details.

  <Expandable title="data properties">
    <ResponseField name="data.id" type="string">
      Unique file identifier.
    </ResponseField>

    <ResponseField name="data.url" type="string">
      CDN URL for the uploaded file. Use this URL in generation request parameters like `image_url` or `audio_url`.
    </ResponseField>

    <ResponseField name="data.filename" type="string">
      Original filename.
    </ResponseField>

    <ResponseField name="data.content_type" type="string">
      MIME type of the uploaded file.
    </ResponseField>

    <ResponseField name="data.size_bytes" type="number">
      File size in bytes.
    </ResponseField>

    <ResponseField name="data.created_at" type="string">
      ISO 8601 timestamp when the file was uploaded.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "id": "file_abc123",
      "url": "https://cdn.modelhunter.ai/files/file_abc123.jpg",
      "filename": "my-image.jpg",
      "content_type": "image/jpeg",
      "size_bytes": 2048576,
      "created_at": "2025-01-15T10:05:00Z"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "success": false,
    "error": {
      "code": "FILE_NOT_FOUND",
      "message": "File not found or upload URL has expired"
    }
  }
  ```
</ResponseExample>


# Get Upload URL
Source: https://docs.modelhunter.ai/api-reference/files/get-upload-url

POST https://api.modelhunter.ai/api/v1/files/upload-url
Get a signed URL for uploading a file.

## Body Parameters

<ParamField type="string">
  Original filename (e.g. `my-image.jpg`).
</ParamField>

<ParamField type="string">
  MIME type of the file (e.g. `image/jpeg`, `video/mp4`, `audio/mpeg`).
</ParamField>

<ParamField type="number">
  File size in bytes. Max 100 MB.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
  Whether the request was successful.
</ResponseField>

<ResponseField name="data" type="object">
  Upload URL details.

  <Expandable title="data properties">
    <ResponseField name="data.upload_url" type="string">
      Pre-signed URL for uploading the file via HTTP PUT. Valid for 15 minutes.
    </ResponseField>

    <ResponseField name="data.file_id" type="string">
      Unique file identifier. Use this to call [Complete Upload](/api-reference/files/complete-upload) after uploading.
    </ResponseField>

    <ResponseField name="data.expires_at" type="string">
      ISO 8601 timestamp when the upload URL expires.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "upload_url": "https://storage.modelhunter.ai/uploads/file_abc123?X-Amz-Signature=...",
      "file_id": "file_abc123",
      "expires_at": "2025-01-15T11:00:00Z"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid contentType: must be a supported MIME type"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "success": false,
    "error": {
      "code": "FILE_TOO_LARGE",
      "message": "File size exceeds the 100 MB limit"
    }
  }
  ```
</ResponseExample>


# Image to Image
Source: https://docs.modelhunter.ai/api-reference/gemini/image-to-image

POST https://api.modelhunter.ai/api/v1/gemini/image-to-image
Edit and transform images using Google Gemini models.

## Body Parameters

<ParamField type="string">
  Gemini model. Options:

  * `nano-banana-2` — Google Gemini 3.1 Flash Image, \$0.08–\$0.16/image
</ParamField>

<ParamField type="object">
  Input parameters for the generation.

  <Expandable title="properties">
    <ParamField type="string">
      Text description to guide the image editing or generation.
    </ParamField>

    <ParamField type="string[]">
      Reference image URLs (up to 14). Provide one or more images for image-to-image editing.
    </ParamField>

    <ParamField type="string">
      Output aspect ratio. Options: `auto`, `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`, `1:4`, `4:1`, `1:8`, `8:1`
    </ParamField>

    <ParamField type="string">
      Output resolution. Options:

      * `1K` — \$0.08/image
      * `2K` — \$0.12/image
      * `4K` — \$0.16/image
    </ParamField>

    <ParamField type="string">
      Output image format. Options: `jpg`, `png`
    </ParamField>

    <ParamField type="boolean">
      Enable real-time Google Search to enhance generation with up-to-date information. Free of charge.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  URL to receive a webhook when the task completes.
</ParamField>

<ParamField type="object">
  Custom key-value metadata to attach to the task.
</ParamField>

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "data": {
      "id": "task_abc123",
      "status": "pending",
      "type": "image-to-image",
      "provider": "gemini",
      "model": "nano-banana-2",
      "created_at": "2026-02-27T10:00:00Z",
      "estimated_seconds": 10
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid request parameters"
    }
  }
  ```
</ResponseExample>


# Text to Image
Source: https://docs.modelhunter.ai/api-reference/gemini/text-to-image

POST https://api.modelhunter.ai/api/v1/gemini/text-to-image
Generate images from text using Google Gemini models.

## Body Parameters

<ParamField type="string">
  Gemini model. Options:

  * `nano-banana-2` — Google Gemini 3.1 Flash Image, \$0.08–\$0.16/image
</ParamField>

<ParamField type="object">
  Input parameters for the generation.

  <Expandable title="properties">
    <ParamField type="string">
      Text description of the image to generate.
    </ParamField>

    <ParamField type="string">
      Output aspect ratio. Options: `auto`, `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`, `1:4`, `4:1`, `1:8`, `8:1`
    </ParamField>

    <ParamField type="string">
      Output resolution. Options:

      * `1K` — \$0.08/image
      * `2K` — \$0.12/image
      * `4K` — \$0.16/image
    </ParamField>

    <ParamField type="string">
      Output image format. Options: `jpg`, `png`
    </ParamField>

    <ParamField type="boolean">
      Enable real-time Google Search to enhance generation with up-to-date information. Free of charge.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  URL to receive a webhook when the task completes.
</ParamField>

<ParamField type="object">
  Custom key-value metadata to attach to the task.
</ParamField>

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "data": {
      "id": "task_abc123",
      "status": "pending",
      "type": "text-to-image",
      "provider": "gemini",
      "model": "nano-banana-2",
      "created_at": "2026-02-27T10:00:00Z",
      "estimated_seconds": 10
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid request parameters"
    }
  }
  ```
</ResponseExample>


# Image to Video
Source: https://docs.modelhunter.ai/api-reference/grok/image-to-video

POST https://api.modelhunter.ai/api/v1/grok/image-to-video
Animate a single input image into a video using Grok Imagine Video.

## Body Parameters

<ParamField type="string">
  Grok model to use. In this phase:

  * `grok-imagine/image-to-video` — Grok Imagine Video image-to-video, output-only pricing at \$0.05/sec (480p) or \$0.07/sec (720p)
</ParamField>

<ParamField type="object">
  Input parameters for the generation.

  <Expandable title="properties">
    <ParamField type="string[]">
      Input image URL array. Must contain exactly 1 public image URL that is directly accessible by the upstream Grok service.
    </ParamField>

    <ParamField type="string">
      Optional motion or scene direction for the animation.
    </ParamField>

    <ParamField type="string">
      Video length in seconds. Options: `6`, `10`, `15`.
    </ParamField>

    <ParamField type="string">
      Output resolution. Options: `480p`, `720p`.
    </ParamField>

    <ParamField type="string">
      Generation style preset. Options: `normal`, `fun`, `spicy`.

      When using external image URLs, `spicy` may be normalized to `normal` by the upstream Grok provider.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  URL to receive a webhook when the task completes.
</ParamField>

<ParamField type="object">
  Custom key-value metadata to attach to the task.
</ParamField>

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "data": {
      "id": "task_grok_i2v_456",
      "status": "pending",
      "type": "image-to-video",
      "provider": "grok",
      "model": "grok-imagine/image-to-video",
      "created_at": "2026-03-13T10:00:00Z",
      "estimated_seconds": 90
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "input.image_urls must contain exactly 1 URL"
    }
  }
  ```
</ResponseExample>


# Text to Video
Source: https://docs.modelhunter.ai/api-reference/grok/text-to-video

POST https://api.modelhunter.ai/api/v1/grok/text-to-video
Generate a video from text using Grok Imagine Video.

## Body Parameters

<ParamField type="string">
  Grok model to use. In this phase:

  * `grok-imagine/text-to-video` — Grok Imagine Video text-to-video, output-only pricing at \$0.05/sec (480p) or \$0.07/sec (720p)
</ParamField>

<ParamField type="object">
  Input parameters for the generation.

  <Expandable title="properties">
    <ParamField type="string">
      Text description of the video to generate.
    </ParamField>

    <ParamField type="string">
      Video length in seconds. Options: `6`, `10`, `15`.
    </ParamField>

    <ParamField type="string">
      Output resolution. Options: `480p`, `720p`.
    </ParamField>

    <ParamField type="string">
      Output aspect ratio. Options: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`.
    </ParamField>

    <ParamField type="string">
      Generation style preset. Options: `normal`, `fun`, `spicy`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  URL to receive a webhook when the task completes.
</ParamField>

<ParamField type="object">
  Custom key-value metadata to attach to the task.
</ParamField>

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "data": {
      "id": "task_grok_t2v_123",
      "status": "pending",
      "type": "text-to-video",
      "provider": "grok",
      "model": "grok-imagine/text-to-video",
      "created_at": "2026-03-13T10:00:00Z",
      "estimated_seconds": 90
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "input.prompt is required"
    }
  }
  ```
</ResponseExample>


# Image to Video
Source: https://docs.modelhunter.ai/api-reference/kling/image-to-video

POST https://api.modelhunter.ai/api/v1/kling/image-to-video
Animate an image into a video using Kling.

## Body Parameters

<ParamField type="string">
  Kling model. Options:

  * `kling-v3` — Per-second billing, multi-shot, element control (3–15s), \$0.084–\$0.168/sec
  * `kling-v2-6` — Fixed pricing, std/pro modes (5s or 10s), \$0.21–\$1.40 per video
</ParamField>

<ParamField type="object">
  Input parameters for the generation.

  <Expandable title="properties">
    <ParamField type="string">
      Input image URL to animate.
    </ParamField>

    <ParamField type="string">
      End frame image URL. When provided, the video transitions from the input image to this image.

      * **V3**: Supported in both `std` and `pro` modes
      * **V2.6**: Only supported in `pro` mode
    </ParamField>

    <ParamField type="string">
      Text description to guide the video generation.
    </ParamField>

    <ParamField type="string">
      Describe what you do not want to see in the output.
    </ParamField>

    <ParamField type="number">
      Video length in seconds.

      * **V3**: Integer from `3` to `15`
      * **V2.6**: `5` or `10`
    </ParamField>

    <ParamField type="string">
      Output aspect ratio. Options: `16:9`, `9:16`, `1:1`
    </ParamField>

    <ParamField type="string">
      Generation quality mode. Options: `std` (standard), `pro` (professional)
    </ParamField>

    <ParamField type="string">
      Enable audio generation with the video. Options: `on`, `off`.

      **Pricing impact (V3):**

      * std + no audio: \$0.084/sec
      * std + audio: \$0.126/sec
      * pro + no audio: \$0.112/sec
      * pro + audio: \$0.168/sec
    </ParamField>

    <ParamField type="string">
      **V3 only.** Enable multi-shot mode. Options:

      * `true` — Enable multi-shot with manual `multi_prompt` segments
      * `intelligence` — AI-powered automatic scene splitting
    </ParamField>

    <ParamField type="object[]">
      **V3 only.** Multi-shot segment prompts. Requires `multi_shot` to be enabled. Maximum 6 segments.

      Each segment object:

      * `index` (number, required) — Shot number, starting from 1, must be consecutive
      * `prompt` (string, required) — Description for this shot
      * `duration` (number) — Duration of this segment in seconds
    </ParamField>

    <ParamField type="object[]">
      **V3 only.** Element control list. Maximum 4 elements. Each element object:

      * `element_id` (number, required) — Positive integer referencing a pre-created element
    </ParamField>

    <ParamField type="object[]">
      Voice list for audio generation. Requires `sound: "on"`. Each voice object:

      * `voice_id` (string) — Voice identifier
      * `text` (string) — Text to speak
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  URL to receive a webhook when the task completes.
</ParamField>

<ParamField type="object">
  Custom key-value metadata to attach to the task.
</ParamField>

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "data": {
      "id": "task_ghi789",
      "status": "pending",
      "type": "image-to-video",
      "provider": "kling",
      "model": "kling-v3",
      "created_at": "2026-02-27T10:00:00Z",
      "estimated_seconds": 60
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid request parameters"
    }
  }
  ```
</ResponseExample>


# Text to Video
Source: https://docs.modelhunter.ai/api-reference/kling/text-to-video

POST https://api.modelhunter.ai/api/v1/kling/text-to-video
Generate a video from text using Kling.

## Body Parameters

<ParamField type="string">
  Kling model. Options:

  * `kling-v3` — Per-second billing, multi-shot, element control (3–15s), \$0.084–\$0.168/sec
  * `kling-v2-6` — Fixed pricing, std/pro modes (5s or 10s), \$0.21–\$1.40 per video
</ParamField>

<ParamField type="object">
  Input parameters for the generation.

  <Expandable title="properties">
    <ParamField type="string">
      Text description of the video to generate.
    </ParamField>

    <ParamField type="string">
      Describe what you do not want to see in the output.
    </ParamField>

    <ParamField type="number">
      Video length in seconds.

      * **V3**: Integer from `3` to `15`
      * **V2.6**: `5` or `10`
    </ParamField>

    <ParamField type="string">
      Output aspect ratio. Options: `16:9`, `9:16`, `1:1`
    </ParamField>

    <ParamField type="string">
      Generation quality mode. Options: `std` (standard), `pro` (professional)
    </ParamField>

    <ParamField type="string">
      Enable audio generation with the video. Options: `on`, `off`.

      **Pricing impact (V3):**

      * std + no audio: \$0.084/sec
      * std + audio: \$0.126/sec
      * pro + no audio: \$0.112/sec
      * pro + audio: \$0.168/sec
    </ParamField>

    <ParamField type="string">
      **V3 only.** Enable multi-shot mode. Options:

      * `true` — Enable multi-shot with manual `multi_prompt` segments
      * `intelligence` — AI-powered automatic scene splitting
    </ParamField>

    <ParamField type="object[]">
      **V3 only.** Multi-shot segment prompts. Requires `multi_shot` to be enabled. Maximum 6 segments.

      Each segment object:

      * `index` (number, required) — Shot number, starting from 1, must be consecutive
      * `prompt` (string, required) — Description for this shot
      * `duration` (number) — Duration of this segment in seconds
    </ParamField>

    <ParamField type="object[]">
      **V3 only.** Element control list. Maximum 4 elements. Each element object:

      * `element_id` (number, required) — Positive integer referencing a pre-created element
    </ParamField>

    <ParamField type="object[]">
      Voice list for audio generation. Requires `sound: "on"`. Each voice object:

      * `voice_id` (string) — Voice identifier
      * `text` (string) — Text to speak
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  URL to receive a webhook when the task completes.
</ParamField>

<ParamField type="object">
  Custom key-value metadata to attach to the task.
</ParamField>

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "data": {
      "id": "task_ghi789",
      "status": "pending",
      "type": "text-to-video",
      "provider": "kling",
      "model": "kling-v3",
      "created_at": "2026-02-27T10:00:00Z",
      "estimated_seconds": 60
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid request parameters"
    }
  }
  ```
</ResponseExample>


# Image to Video
Source: https://docs.modelhunter.ai/api-reference/seedance/image-to-video

POST https://api.modelhunter.ai/api/v1/seedance/image-to-video
Animate an image into a video using ByteDance Seedance models via Volcengine Ark. Supports first frame, first+last frame, and reference image modes.

## Body Parameters

<ParamField type="string">
  Seedance model. Options:

  * `seedance-1-5-pro` — Latest flagship, audio-visual generation, \$0.012–\$0.116/sec
  * `seedance-1-0-pro` — Multi-shot narrative, cinematic quality, \$0.024–\$0.122/sec
  * `seedance-1-0-pro-fast` — 3x faster (first frame only), \$0.010–\$0.049/sec
  * `seedance-1-0-lite-i2v` — Lightweight, supports reference images, \$0.017–\$0.088/sec

  Pricing varies by resolution (480p/720p/1080p). Seedance 1.5 Pro pricing also depends on whether audio generation is enabled.
</ParamField>

<ParamField type="object">
  Input parameters for the generation.

  <Expandable title="properties">
    <ParamField type="string">
      First frame image. Accepts a URL or base64-encoded data URI (`data:image/png;base64,...`).

      **Image requirements:**

      * Formats: jpeg, png, webp, bmp, tiff, gif (1.5 Pro also supports heic, heif)
      * Aspect ratio (width/height): 0.4 to 2.5
      * Dimensions: 300px to 6000px per side
      * Max size: 30 MB
    </ParamField>

    <ParamField type="string">
      Last frame image for first+last frame mode. Same format and requirements as `image`.

      **Supported models:** 1.5 Pro, 1.0 Pro, 1.0 Lite I2V.

      The first and last frame images can be the same. If aspect ratios differ, the last frame is auto-cropped to match the first.
    </ParamField>

    <ParamField type="string[]">
      Reference images for reference-image mode (1-4 images). **Seedance 1.0 Lite I2V only.**

      Use `[图1]`, `[图2]` etc. in the prompt to reference specific images for better results.
    </ParamField>

    <ParamField type="string">
      Text description to guide the video generation. Supports Chinese and English.
    </ParamField>

    <ParamField type="number">
      Video length in seconds.

      * **1.0 series**: integer from `2` to `12`
      * **1.5 Pro**: integer from `4` to `12`
    </ParamField>

    <ParamField type="string">
      Video resolution. Options: `480p`, `720p`, `1080p`

      Note: 1.0 Lite I2V reference image mode does not support `1080p`.
    </ParamField>

    <ParamField type="string">
      Aspect ratio. Options: `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`, `adaptive`

      Default is `adaptive` for I2V (matches first frame). Reference image mode does not support `adaptive`.
    </ParamField>

    <ParamField type="number">
      Random seed for reproducibility. Range: `-1` to `4294967295`. `-1` means random.
    </ParamField>

    <ParamField type="boolean">
      Whether to fix the camera position. Not supported in reference image mode.
    </ParamField>

    <ParamField type="boolean">
      Whether to add a watermark to the video.
    </ParamField>

    <ParamField type="boolean">
      **Seedance 1.5 Pro only.** Generate synchronized audio with the video.
    </ParamField>

    <ParamField type="boolean">
      Return the last frame of the generated video. Useful for chaining continuous videos.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  URL to receive a webhook when the task completes.
</ParamField>

<ParamField type="object">
  Custom key-value metadata to attach to the task.
</ParamField>

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "data": {
      "id": "task_abc123",
      "status": "pending",
      "type": "image-to-video",
      "provider": "seedance",
      "model": "seedance-1-0-pro",
      "created_at": "2026-01-15T10:00:00Z",
      "estimated_seconds": 40
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid request parameters"
    }
  }
  ```
</ResponseExample>


# Seedance 2.0 Multimodal Video
Source: https://docs.modelhunter.ai/api-reference/seedance/multimodal-video

POST https://api.modelhunter.ai/api/v1/seedance/multimodal-video
Generate controllable cinematic videos with Seedance 2.0 using text, optional image, video, and audio references.

## Body Parameters

<ParamField type="string">
  Seedance 2.0 model to use:

  * `bytedance/seedance-2`
</ParamField>

<ParamField type="object">
  Input parameters for the generation.

  <Expandable title="properties">
    <ParamField type="string">
      Text description of the video to generate. Maximum length: 5000 characters.
    </ParamField>

    <ParamField type="string">
      Optional first frame image URL. Must be a public HTTP(S) URL.
    </ParamField>

    <ParamField type="string">
      Optional last frame image URL. Must be a public HTTP(S) URL.
    </ParamField>

    <ParamField type="string[]">
      Optional image reference URLs. Provide 1 to 9 public HTTP(S) URLs.
    </ParamField>

    <ParamField type="string[]">
      Optional video reference URLs. Provide 1 to 3 public HTTP(S) URLs.

      Video-reference requests use the video-reference price tier and are billed on input plus output seconds.
    </ParamField>

    <ParamField type="string[]">
      Optional audio reference URLs. Provide 1 to 3 public HTTP(S) URLs. Supported audio files are MPEG, WAV, X-WAV, AAC, MP4, or OGG, max 15MB each.

      Audio references must be used with at least one visual reference: `first_frame_url`, `last_frame_url`, `reference_image_urls`, or `reference_video_urls`.
    </ParamField>

    <ParamField type="boolean">
      Whether to generate synchronized AI audio for the output video.
    </ParamField>

    <ParamField type="string">
      Output resolution. Options: `480p`, `720p`, `1080p`.
    </ParamField>

    <ParamField type="string">
      Output aspect ratio. Options: `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`.
    </ParamField>

    <ParamField type="number">
      Output duration in seconds. Must be an integer from `4` to `15`.
    </ParamField>

    <ParamField type="boolean">
      Whether to use online search.
    </ParamField>

    <ParamField type="boolean">
      Whether to enable the NSFW checker.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  URL to receive a webhook when the task completes.
</ParamField>

<ParamField type="object">
  Custom key-value metadata to attach to the task.
</ParamField>

## Pricing

Seedance 2.0 is billed per second by resolution:

| Request type         |         480p |        720p |      1080p |
| -------------------- | -----------: | ----------: | ---------: |
| No video reference   |  \$0.095/sec | \$0.205/sec | \$0.51/sec |
| With video reference | \$0.0575/sec | \$0.125/sec | \$0.31/sec |

When `reference_video_urls` is provided, billing uses input plus output seconds. Image, first/last frame, and audio references without a video reference use the no-video-reference tier.

## Example

```bash theme={null}
curl -X POST https://api.modelhunter.ai/api/v1/seedance/multimodal-video \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2",
    "input": {
      "prompt": "A cinematic product reveal with smooth camera motion and realistic lighting",
      "first_frame_url": "https://cdn.example.com/first-frame.png",
      "reference_audio_urls": ["https://cdn.example.com/reference-audio.mp3"],
      "generate_audio": false,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "duration": 5
    },
    "metadata": {
      "project": "launch-video"
    }
  }'
```

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "data": {
      "id": "task_abc123",
      "status": "pending",
      "type": "multimodal-video",
      "provider": "seedance",
      "model": "bytedance/seedance-2",
      "created_at": "2026-05-15T10:00:00Z",
      "estimated_seconds": 300
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "input.reference_audio_urls must be used with an image or video reference"
    }
  }
  ```
</ResponseExample>


# Text to Video
Source: https://docs.modelhunter.ai/api-reference/seedance/text-to-video

POST https://api.modelhunter.ai/api/v1/seedance/text-to-video
Generate a video from text using ByteDance Seedance models via Volcengine Ark.

## Body Parameters

<ParamField type="string">
  Seedance model. Options:

  * `seedance-1-5-pro` — Latest flagship, audio-visual generation, \$0.012–\$0.116/sec
  * `seedance-1-0-pro` — Multi-shot narrative, cinematic quality, \$0.024–\$0.122/sec
  * `seedance-1-0-pro-fast` — 3x faster, lower cost, \$0.010–\$0.049/sec
  * `seedance-1-0-lite-t2v` — Lightweight, cost-effective, \$0.017–\$0.088/sec

  Pricing varies by resolution (480p/720p/1080p). Seedance 1.5 Pro pricing also depends on whether audio generation is enabled.
</ParamField>

<ParamField type="object">
  Input parameters for the generation.

  <Expandable title="properties">
    <ParamField type="string">
      Text description of the video to generate. Supports Chinese and English. Recommended max 500 characters.
    </ParamField>

    <ParamField type="number">
      Video length in seconds.

      * **1.0 series**: integer from `2` to `12`
      * **1.5 Pro**: integer from `4` to `12`
    </ParamField>

    <ParamField type="string">
      Video resolution. Options: `480p`, `720p`, `1080p`

      Default: `720p` for 1.5 Pro and 1.0 Lite, `1080p` for 1.0 Pro and Pro Fast.
    </ParamField>

    <ParamField type="string">
      Aspect ratio. Options: `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`, `adaptive`

      `adaptive` auto-selects the best ratio based on the prompt (1.5 Pro only for T2V).
    </ParamField>

    <ParamField type="number">
      Random seed for reproducibility. Range: `-1` to `4294967295`. `-1` means random.
    </ParamField>

    <ParamField type="boolean">
      Whether to fix the camera position.
    </ParamField>

    <ParamField type="boolean">
      Whether to add a watermark to the video.
    </ParamField>

    <ParamField type="boolean">
      **Seedance 1.5 Pro only.** Generate synchronized audio with the video. Supports voice, sound effects, and background music. Place dialogue in double quotes for best results.
    </ParamField>

    <ParamField type="boolean">
      Return the last frame of the generated video as an image. Useful for chaining multiple videos together.
    </ParamField>

    <ParamField type="boolean">
      **Seedance 1.5 Pro only.** Enable draft mode for faster generation at lower quality. Useful for rapid iteration.
    </ParamField>

    <ParamField type="string">
      Service tier. Options: `default` (standard priority), `flex` (lower priority, may queue longer).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  URL to receive a webhook when the task completes.
</ParamField>

<ParamField type="object">
  Custom key-value metadata to attach to the task.
</ParamField>

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "data": {
      "id": "task_abc123",
      "status": "pending",
      "type": "text-to-video",
      "provider": "seedance",
      "model": "seedance-1-5-pro",
      "created_at": "2026-01-15T10:00:00Z",
      "estimated_seconds": 40
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid request parameters"
    }
  }
  ```
</ResponseExample>


# Image to Image
Source: https://docs.modelhunter.ai/api-reference/seedream/image-to-image

POST https://api.modelhunter.ai/api/v1/seedream/image-to-image
Edit and transform images using ByteDance Seedream models via Volcengine Ark. Supports reference-based generation with single or multiple input images.

## Body Parameters

<ParamField type="string">
  Seedream model. Options:

  * `seedream-5-0-lite` — Latest, web search support, \$0.04/image
  * `seedream-4-5` — Flagship, multi-image reference input (up to 14), \$0.04/image
  * `seedream-4-0` — Multi-image reference input (up to 14), \$0.03/image
</ParamField>

<ParamField type="object">
  Input parameters for the generation.

  <Expandable title="properties">
    <ParamField type="string">
      Text description to guide the image editing or generation. Supports Chinese and English.

      **Recommended limits:** 300 Chinese characters or 600 English words.
    </ParamField>

    <ParamField type="string">
      Input image for editing or reference. Accepts a URL or base64-encoded data URI (`data:image/png;base64,...`).

      **Image requirements:**

      * Formats: jpeg, png (4.0/4.5 also support webp, bmp, tiff, gif)
      * Max size: 10 MB
      * Max dimensions: 6000x6000 pixels
    </ParamField>

    <ParamField type="string[]">
      Multiple reference images (up to 14). Each image as URL or base64. Supported on all models (5.0 Lite, 4.5, 4.0).

      Use this for multi-image reference generation where the model considers all provided images.
    </ParamField>

    <ParamField type="string">
      Output image size. Options: `1K`, `2K`, `4K`, or `WxH` pixels (128-aligned). Default `2K`.

      * **4.0**: Total pixels (w×h) in \[921,600 \~ 16,777,216], aspect ratio \[1:16 \~ 16:1]
      * **4.5**: Total pixels (w×h) in \[3,686,400 \~ 16,777,216], aspect ratio \[1:16 \~ 16:1]
    </ParamField>

    <ParamField type="number">
      Output width in pixels. Alternative to `size`. Must satisfy total pixel and aspect ratio constraints above. 128-aligned.
    </ParamField>

    <ParamField type="number">
      Output height in pixels. Use together with `width`. Must satisfy total pixel and aspect ratio constraints above. 128-aligned.
    </ParamField>

    <ParamField type="boolean">
      Whether to add a watermark to the generated image.
    </ParamField>

    <ParamField type="string">
      Prompt optimization mode.

      * **Seedream 4.0/4.5**: Options: `standard`, `fast`
      * **Seedream 5.0**: Only supports `standard`
    </ParamField>

    <ParamField type="string">
      **Seedream 5.0 only.** Output image format. Options: `png`, `jpeg`.
    </ParamField>

    <ParamField type="boolean">
      **Seedream 5.0 only.** Enable real-time web search to enhance generation with up-to-date information.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  URL to receive a webhook when the task completes.
</ParamField>

<ParamField type="object">
  Custom key-value metadata to attach to the task.
</ParamField>

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "data": {
      "id": "task_abc123",
      "status": "pending",
      "type": "image-to-image",
      "provider": "seedream",
      "model": "seedream-4-5",
      "created_at": "2026-01-15T10:00:00Z",
      "estimated_seconds": 10
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid request parameters"
    }
  }
  ```
</ResponseExample>


# Text to Image
Source: https://docs.modelhunter.ai/api-reference/seedream/text-to-image

POST https://api.modelhunter.ai/api/v1/seedream/text-to-image
Generate images from text using ByteDance Seedream models via Volcengine Ark. Supports up to 4K resolution and multi-image input.

## Body Parameters

<ParamField type="string">
  Seedream model. Options:

  * `seedream-5-0-lite` — Latest, web search support, \$0.04/image
  * `seedream-4-5` — Flagship, multi-image input, streaming, \$0.04/image
  * `seedream-4-0` — Multi-image input, \$0.03/image
  * `seedream-3-0-t2i` — Text-to-image only, seed & guidance control, \$0.03/image
</ParamField>

<ParamField type="object">
  Input parameters for the generation.

  <Expandable title="properties">
    <ParamField type="string">
      Text description of the image to generate. Supports Chinese and English.

      **Recommended limits:** 300 Chinese characters or 600 English words.
    </ParamField>

    <ParamField type="string">
      Output image size. Options:

      **Presets:**

      * `1K` — 1024x1024
      * `2K` — 2048x2048 (default for 4.0/4.5/5.0)
      * `3K` — 3072x3072 (5.0 only)
      * `4K` — 4096x4096 (4.0/4.5 only)

      **Custom:** `WxH` in pixels (e.g., `1920x1080`), 128-aligned.

      * **4.0**: Total pixels (w×h) in \[921,600 \~ 16,777,216], aspect ratio \[1:16 \~ 16:1]
      * **4.5**: Total pixels (w×h) in \[3,686,400 \~ 16,777,216], aspect ratio \[1:16 \~ 16:1]
      * **3.0-t2i**: Range \[512x512, 2048x2048], 64-aligned, default 1024x1024
    </ParamField>

    <ParamField type="number">
      Image width in pixels (alternative to `size`). Must satisfy total pixel and aspect ratio constraints above. 128-aligned.
    </ParamField>

    <ParamField type="number">
      Image height in pixels (alternative to `size`). Must satisfy total pixel and aspect ratio constraints above. 128-aligned.
    </ParamField>

    <ParamField type="number">
      **Seedream 3.0 only.** Random seed for reproducibility. Range: `-1` to `2147483647`. `-1` means random.
    </ParamField>

    <ParamField type="number">
      **Seedream 3.0 only.** How closely to follow the prompt. Range: `1` to `10`.
    </ParamField>

    <ParamField type="boolean">
      Whether to add a watermark to the generated image.
    </ParamField>

    <ParamField type="string">
      Prompt optimization mode. Enhances the prompt for better generation results.

      * **Seedream 4.0/4.5**: Options: `standard`, `fast`
      * **Seedream 5.0**: Only supports `standard`
    </ParamField>

    <ParamField type="string">
      **Seedream 5.0 only.** Output image format. Options: `png`, `jpeg`.
    </ParamField>

    <ParamField type="boolean">
      **Seedream 5.0 only.** Enable real-time web search to enhance generation with up-to-date information.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  URL to receive a webhook when the task completes.
</ParamField>

<ParamField type="object">
  Custom key-value metadata to attach to the task.
</ParamField>

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "data": {
      "id": "task_abc123",
      "status": "pending",
      "type": "text-to-image",
      "provider": "seedream",
      "model": "seedream-4-5",
      "created_at": "2026-01-15T10:00:00Z",
      "estimated_seconds": 10
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid request parameters"
    }
  }
  ```
</ResponseExample>


# Get Task Status
Source: https://docs.modelhunter.ai/api-reference/tasks/get-task

GET https://api.modelhunter.ai/api/v1/tasks/{id}
Retrieve the current status and result of a generation task.

## Path Parameters

<ParamField type="string">
  Task ID returned from the generation request.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
  Whether the request was successful.
</ResponseField>

<ResponseField name="data" type="object">
  Task details.

  <Expandable title="data properties">
    <ResponseField name="data.id" type="string">
      Unique task identifier (e.g. `task_abc123`).
    </ResponseField>

    <ResponseField name="data.type" type="string">
      Media type. One of: `video`, `image`, `audio`, `music`.
    </ResponseField>

    <ResponseField name="data.status" type="string">
      Current task status. One of: `pending`, `queued`, `running`, `succeeded`, `failed`, `cancelled`, `expired`.
    </ResponseField>

    <ResponseField name="data.provider" type="string">
      Provider that processed the request (e.g. `vidu`, `kling`, `seedream`).
    </ResponseField>

    <ResponseField name="data.model" type="string">
      Model used for generation (e.g. `viduq3-turbo`, `gen3-alpha-turbo`).
    </ResponseField>

    <ResponseField name="data.result" type="object[]">
      Array of output items. Only present when status is `succeeded`.

      <Expandable title="result item properties">
        <ResponseField name="url" type="string">
          Signed download URL for the output file. Valid for 15 minutes.
        </ResponseField>

        <ResponseField name="duration" type="number">
          Output duration in seconds (video/audio only).
        </ResponseField>

        <ResponseField name="format" type="string">
          Output file format (e.g. `mp4`, `png`, `jpg`, `mp3`).
        </ResponseField>

        <ResponseField name="size_bytes" type="number">
          Output file size in bytes.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="data.error" type="object">
      Error details. Only present when status is `failed`.

      <Expandable title="error properties">
        <ResponseField name="data.error.code" type="string">
          Machine-readable error code (e.g. `PROVIDER_ERROR`).
        </ResponseField>

        <ResponseField name="data.error.message" type="string">
          Human-readable error message.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="data.created_at" type="string">
      ISO 8601 timestamp when the task was created.
    </ResponseField>

    <ResponseField name="data.completed_at" type="string">
      ISO 8601 timestamp when the task completed (succeeded, failed, or cancelled).
    </ResponseField>

    <ResponseField name="data.metadata" type="object">
      Custom key-value metadata attached when the task was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Succeeded theme={null}
  {
    "success": true,
    "data": {
      "id": "task_abc123",
      "type": "video",
      "status": "succeeded",
      "provider": "vidu",
      "model": "viduq3-turbo",
      "result": [
        {
          "url": "https://cdn.modelhunter.ai/results/task_abc123.mp4",
          "duration": 4,
          "format": "mp4",
          "size_bytes": 12582912
        }
      ],
      "created_at": "2025-01-15T10:00:00Z",
      "completed_at": "2025-01-15T10:00:32Z",
      "metadata": { "project": "demo" }
    }
  }
  ```

  ```json 200 Running theme={null}
  {
    "success": true,
    "data": {
      "id": "task_abc123",
      "type": "video",
      "status": "running",
      "provider": "vidu",
      "model": "viduq3-turbo",
      "created_at": "2025-01-15T10:00:00Z",
      "metadata": { "project": "demo" }
    }
  }
  ```

  ```json 404 theme={null}
  {
    "success": false,
    "error": {
      "code": "TASK_NOT_FOUND",
      "message": "Task not found"
    }
  }
  ```
</ResponseExample>


# List Tasks
Source: https://docs.modelhunter.ai/api-reference/tasks/list-tasks

GET https://api.modelhunter.ai/api/v1/tasks
List all generation tasks with filtering and cursor-based pagination.

## Query Parameters

<ParamField type="string">
  Filter by task status. One of: `pending`, `queued`, `running`, `succeeded`, `failed`, `cancelled`, `expired`.
</ParamField>

<ParamField type="string">
  Filter by provider. Options: `vidu`, `kling`, `seedream`, `seedance`, `gemini`, `wan`.
</ParamField>

<ParamField type="string">
  Filter by model ID (e.g., `viduq3-turbo`, `kling-v3`).
</ParamField>

<ParamField type="string">
  Filter tasks created after this date (ISO 8601 format).
</ParamField>

<ParamField type="string">
  Filter tasks created before this date (ISO 8601 format).
</ParamField>

<ParamField type="string">
  Search by task ID prefix.
</ParamField>

<ParamField type="number">
  Items per page. Range: 1–100.
</ParamField>

<ParamField type="string">
  Cursor for pagination. Pass the `cursor` value from a previous response to get the next page.
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "task_abc123",
        "type": "video",
        "status": "succeeded",
        "provider": "vidu",
        "model": "viduq3-turbo",
        "progress": 100,
        "cost": 0.32,
        "created_at": "2026-01-15T10:00:00Z",
        "started_at": "2026-01-15T10:00:02Z",
        "completed_at": "2026-01-15T10:00:32Z",
        "metadata": { "project": "demo" }
      },
      {
        "id": "task_def456",
        "type": "image",
        "status": "failed",
        "provider": "seedream",
        "model": "seedream-5-0-lite",
        "progress": 0,
        "error": {
          "code": "PROVIDER_ERROR",
          "message": "Content policy violation"
        },
        "created_at": "2026-01-15T09:50:00Z",
        "started_at": "2026-01-15T09:50:01Z",
        "completed_at": "2026-01-15T09:50:08Z"
      }
    ],
    "pagination": {
      "cursor": "2026-01-15T09:50:00Z",
      "hasMore": true,
      "total": 42
    }
  }
  ```
</ResponseExample>


# Retry Task
Source: https://docs.modelhunter.ai/api-reference/tasks/retry-task

POST https://api.modelhunter.ai/api/v1/tasks/{id}/retry
Retry a failed task. Creates a new task with the same parameters and charges your balance again.

## Path Parameters

<ParamField type="string">
  The ID of the failed task to retry.
</ParamField>

## Notes

* Tasks with status `failed` or `expired` can be retried.
* A new task is created with the same provider, model, and input parameters.
* Your balance will be charged again for the new task.
* The original task remains unchanged.

<ResponseExample>
  ```json 201 theme={null}
  {
    "success": true,
    "data": {
      "id": "task_new789",
      "original_task_id": "task_abc123",
      "status": "pending",
      "type": "video",
      "provider": "vidu",
      "model": "viduq3-turbo",
      "created_at": "2026-01-15T12:00:00Z"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": {
      "code": "TASK_NOT_RETRYABLE",
      "message": "Only failed or expired tasks can be retried"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "success": false,
    "error": {
      "code": "TASK_NOT_FOUND",
      "message": "Task not found"
    }
  }
  ```
</ResponseExample>


# Image to Video
Source: https://docs.modelhunter.ai/api-reference/veo/image-to-video

POST https://api.modelhunter.ai/api/v1/veo/image-to-video
Animate one or two input images into a video using Veo 3.1.

## Body Parameters

<ParamField type="string">
  Veo model to use. In this phase:

  * `veo3` — billed at `$3.20` per request
  * `veo3_fast` — billed at `$1.20` per request

  This endpoint currently bills a fixed default `8s` clip.
</ParamField>

<ParamField type="object">
  Input parameters for the generation.

  <Expandable title="properties">
    <ParamField type="string">
      Motion or scene direction for the generated video.
    </ParamField>

    <ParamField type="string[]">
      Public image URL array. Provide `1` or `2` directly accessible HTTP(S) image URLs.
    </ParamField>

    <ParamField type="string">
      Output aspect ratio. Options: `16:9`, `9:16`, `Auto`.
    </ParamField>

    <ParamField type="number">
      Optional deterministic seed. Must be an integer between `10000` and `99999`.
    </ParamField>

    <ParamField type="boolean">
      Enable upstream prompt translation before generation.
    </ParamField>

    <ParamField type="string">
      Optional watermark mode passed through to the upstream Veo provider.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  URL to receive a webhook when the task completes.
</ParamField>

<ParamField type="object">
  Custom key-value metadata to attach to the task.
</ParamField>

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "data": {
      "id": "task_veo_i2v_456",
      "status": "pending",
      "type": "image-to-video",
      "provider": "veo",
      "model": "veo3_fast",
      "created_at": "2026-03-14T10:00:00Z",
      "estimated_seconds": 90
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "input.image_urls must contain 1 or 2 URLs"
    }
  }
  ```
</ResponseExample>


# Text to Video
Source: https://docs.modelhunter.ai/api-reference/veo/text-to-video

POST https://api.modelhunter.ai/api/v1/veo/text-to-video
Generate a video from text using Veo 3.1.

## Body Parameters

<ParamField type="string">
  Veo model to use. In this phase:

  * `veo3` — billed at `$3.20` per request
  * `veo3_fast` — billed at `$1.20` per request

  This endpoint currently bills a fixed default `8s` clip.
</ParamField>

<ParamField type="object">
  Input parameters for the generation.

  <Expandable title="properties">
    <ParamField type="string">
      Text description of the video to generate.
    </ParamField>

    <ParamField type="string">
      Output aspect ratio. Options: `16:9`, `9:16`, `Auto`.
    </ParamField>

    <ParamField type="number">
      Optional deterministic seed. Must be an integer between `10000` and `99999`.
    </ParamField>

    <ParamField type="boolean">
      Enable upstream prompt translation before generation.
    </ParamField>

    <ParamField type="string">
      Optional watermark mode passed through to the upstream Veo provider.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  URL to receive a webhook when the task completes.
</ParamField>

<ParamField type="object">
  Custom key-value metadata to attach to the task.
</ParamField>

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "data": {
      "id": "task_veo_t2v_123",
      "status": "pending",
      "type": "text-to-video",
      "provider": "veo",
      "model": "veo3",
      "created_at": "2026-03-14T10:00:00Z",
      "estimated_seconds": 180
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "input.prompt is required"
    }
  }
  ```
</ResponseExample>


# Image to Video
Source: https://docs.modelhunter.ai/api-reference/vidu/image-to-video

POST https://api.modelhunter.ai/api/v1/vidu/image-to-video
Animate a static image into a video using Vidu.

<Note>
  Check out [Vidu pricing](/pricing#video-models) — enable `off_peak: true` for **50% off**.
</Note>

## Body Parameters

<ParamField type="string">
  Vidu model to use. Options:

  * `viduq3-pro` — Latest flagship, supports audio sync (1–16s), \$0.07–\$0.16/sec
  * `viduq3-turbo` — Fast Q3, supports audio sync (1–16s), \$0.04–\$0.08/sec

  Pricing varies by resolution. Enable `off_peak: true` for 50% off.
</ParamField>

<ParamField type="object">
  Provider-specific parameters for the generation request.

  <Expandable title="properties">
    <ParamField type="string[]">
      Image array for the start frame. Only 1 image is accepted. Supports public URL or base64 format.

      * Formats: `png`, `jpeg`, `jpg`, `webp`
      * Aspect ratio must be between 1:4 and 4:1
      * Max image size: 50 MB
    </ParamField>

    <ParamField type="string">
      Text description to guide the video generation. Max 5,000 characters.

      Note: If `is_rec` is enabled, the model will ignore this prompt.
    </ParamField>

    <ParamField type="number">
      Video length in seconds (1–16).
    </ParamField>

    <ParamField type="string">
      Output resolution. Options: `540p`, `720p`, `1080p`
    </ParamField>

    <ParamField type="boolean">
      Enable audio-video sync output. Default `true` for Q3 models.

      When enabled, the video will include dialogue and sound effects.
    </ParamField>

    <ParamField type="string">
      Voice ID for audio generation. Only effective when `audio` is `true`.

      See [Vidu Voice List](https://shengshu.feishu.cn/sheets/WM45sosS7hEj2mtAATvclDAWnNb) for available voices. You can also use the Voice Clone API to create custom voices.
    </ParamField>

    <ParamField type="boolean">
      Use Vidu's recommended prompt instead of user-provided prompt.

      Note: Enabling this consumes an additional 10 credits per task.
    </ParamField>

    <ParamField type="boolean">
      Add background music to the generated video.

      Note: Not available for Q3 models. Ineffective when Q2 duration is 9–10s.
    </ParamField>

    <ParamField type="string">
      Movement amplitude of objects in the frame. Options: `auto`, `small`, `medium`, `large`

      Note: Ineffective for Q2 and Q3 models.
    </ParamField>

    <ParamField type="number">
      Random seed for reproducibility.
    </ParamField>

    <ParamField type="boolean">
      Enable off-peak mode for 50% discount. Tasks complete within 48 hours.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  URL to receive a webhook when the task completes.
</ParamField>

<ParamField type="object">
  Custom key-value metadata to attach to the task.
</ParamField>

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "data": {
      "id": "task_abc123",
      "status": "pending",
      "type": "image-to-video",
      "provider": "vidu",
      "model": "viduq3-turbo",
      "created_at": "2025-01-15T10:00:00Z",
      "estimated_seconds": 30
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid request parameters"
    }
  }
  ```
</ResponseExample>


# Text to Video
Source: https://docs.modelhunter.ai/api-reference/vidu/text-to-video

POST https://api.modelhunter.ai/api/v1/vidu/text-to-video
Generate a video from a text prompt using Vidu.

<Note>
  Check out [Vidu pricing](/pricing#video-models) — enable `off_peak: true` for **50% off**.
</Note>

## Body Parameters

<ParamField type="string">
  Vidu model to use. Options:

  * `viduq3-pro` — Latest flagship, supports audio sync (1–16s), \$0.07–\$0.16/sec
  * `viduq3-turbo` — Fast Q3, supports audio sync (1–16s), \$0.04–\$0.08/sec

  Pricing varies by resolution. Enable `off_peak: true` for 50% off.
</ParamField>

<ParamField type="object">
  Provider-specific parameters for the generation request.

  <Expandable title="properties">
    <ParamField type="string">
      Text description of the video to generate. Max 2,000 characters.
    </ParamField>

    <ParamField type="number">
      Video length in seconds (1–16).
    </ParamField>

    <ParamField type="string">
      Output aspect ratio. Options: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`
    </ParamField>

    <ParamField type="string">
      Output resolution. Options: `540p`, `720p`, `1080p`
    </ParamField>

    <ParamField type="string">
      Visual style. Options: `general`, `anime`
    </ParamField>

    <ParamField type="boolean">
      Enable audio-video sync output. Supported on `viduq3-pro` and `viduq3-turbo`. Default `true` for Q3 models.
    </ParamField>

    <ParamField type="number">
      Random seed for reproducibility.
    </ParamField>

    <ParamField type="boolean">
      Enable off-peak mode for 50% discount. Tasks complete within 48 hours.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  URL to receive a webhook when the task completes.
</ParamField>

<ParamField type="object">
  Custom key-value metadata to attach to the task.
</ParamField>

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "data": {
      "id": "task_abc123",
      "status": "pending",
      "type": "text-to-video",
      "provider": "vidu",
      "model": "viduq3-turbo",
      "created_at": "2025-01-15T10:00:00Z",
      "estimated_seconds": 30
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid request parameters"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "success": false,
    "error": {
      "code": "INSUFFICIENT_BALANCE",
      "message": "Your balance is too low for this request"
    }
  }
  ```
</ResponseExample>


# Image to Video
Source: https://docs.modelhunter.ai/api-reference/wan/image-to-video

POST https://api.modelhunter.ai/api/v1/wan/image-to-video
Animate a single input image into a video using Wan 2.6.

## Body Parameters

<ParamField type="string">
  Wan model to use. In this phase:

  * `wan/2-6-image-to-video`
</ParamField>

<ParamField type="object">
  Input parameters for the generation.

  <Expandable title="properties">
    <ParamField type="string">
      Prompt that describes target motion and scene transformation.
    </ParamField>

    <ParamField type="string[]">
      Input image URL array. Must contain exactly 1 public URL that is directly accessible by the upstream Wan service.
    </ParamField>

    <ParamField type="string">
      Video length in seconds. Options: `5`, `10`, `15`.
    </ParamField>

    <ParamField type="string">
      Output resolution. Options: `720p`, `1080p`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  URL to receive a webhook when the task completes.
</ParamField>

<ParamField type="object">
  Custom key-value metadata to attach to the task.
</ParamField>

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "data": {
      "id": "task_def456",
      "status": "pending",
      "type": "image-to-video",
      "provider": "wan",
      "model": "wan/2-6-image-to-video",
      "created_at": "2026-03-04T10:00:00Z",
      "estimated_seconds": 45
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "input.image_urls must contain exactly one URL"
    }
  }
  ```
</ResponseExample>


# Text to Video
Source: https://docs.modelhunter.ai/api-reference/wan/text-to-video

POST https://api.modelhunter.ai/api/v1/wan/text-to-video
Generate a video from text using Wan 2.6 official async tasks.

## Body Parameters

<ParamField type="string">
  Wan model to use. In this phase:

  * `wan/2-6-text-to-video`
</ParamField>

<ParamField type="object">
  Input parameters for the generation.

  <Expandable title="properties">
    <ParamField type="string">
      Text description of the video to generate.
    </ParamField>

    <ParamField type="string">
      Video length in seconds. Options: `5`, `10`, `15`.
    </ParamField>

    <ParamField type="string">
      Output resolution. Options: `720p`, `1080p`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  URL to receive a webhook when the task completes.
</ParamField>

<ParamField type="object">
  Custom key-value metadata to attach to the task.
</ParamField>

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "data": {
      "id": "task_abc123",
      "status": "pending",
      "type": "text-to-video",
      "provider": "wan",
      "model": "wan/2-6-text-to-video",
      "created_at": "2026-03-04T10:00:00Z",
      "estimated_seconds": 45
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid request parameters"
    }
  }
  ```
</ResponseExample>


# Video to Video
Source: https://docs.modelhunter.ai/api-reference/wan/video-to-video

POST https://api.modelhunter.ai/api/v1/wan/video-to-video
Transform one to three source videos using Wan 2.6.

## Body Parameters

<ParamField type="string">
  Wan model to use. In this phase:

  * `wan/2-6-video-to-video`
</ParamField>

<ParamField type="object">
  Input parameters for the generation.

  <Expandable title="properties">
    <ParamField type="string">
      Prompt that describes the target style, motion, or transformation.
    </ParamField>

    <ParamField type="string[]">
      Source video URL array. Provide 1 to 3 public URLs that are directly accessible by the upstream Wan service.
    </ParamField>

    <ParamField type="string">
      Video length in seconds. Options: `5`, `10`.
    </ParamField>

    <ParamField type="string">
      Output resolution. Options: `720p`, `1080p`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  URL to receive a webhook when the task completes.
</ParamField>

<ParamField type="object">
  Custom key-value metadata to attach to the task.
</ParamField>

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "data": {
      "id": "task_ghi789",
      "status": "pending",
      "type": "video-to-video",
      "provider": "wan",
      "model": "wan/2-6-video-to-video",
      "created_at": "2026-03-04T10:00:00Z",
      "estimated_seconds": 40
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "input.video_urls must contain 1 to 3 URLs"
    }
  }
  ```
</ResponseExample>


# Authentication
Source: https://docs.modelhunter.ai/authentication

Authenticate your API requests with Bearer tokens

## Bearer Token Authentication

All API requests must include a valid API key in the `Authorization` header:

```http theme={null}
Authorization: Bearer river_live_xxxxxxxxxxxxx
```

## API Key Format

API keys follow the pattern:

```
river_{environment}_{random32}
```

| Prefix        | Environment | Usage                                   |
| ------------- | ----------- | --------------------------------------- |
| `river_live_` | Production  | Live API calls, charged to your account |
| `river_test_` | Sandbox     | Testing, no charges incurred            |

## Managing API Keys

### Create a Key

Create API keys from the [Dashboard](https://modelhunter.ai/dashboard/api-keys) or via the API:

```bash theme={null}
curl -X POST https://api.modelhunter.ai/api/v1/api-keys \
  -H "Authorization: Bearer river_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Backend",
    "spendLimit": 1000,
    "expiresAt": "2027-01-01T00:00:00Z"
  }'
```

<Warning>
  The full API key is only shown once at creation time. Store it securely — you cannot retrieve it later.
</Warning>

### Rotate a Key

To rotate a key, create a new one, update your application, then delete the old key.

### Delete a Key

```bash theme={null}
curl -X DELETE https://api.modelhunter.ai/api/v1/api-keys/{key_id} \
  -H "Authorization: Bearer river_live_xxx"
```

## Permissions

Each API key can be scoped with fine-grained permissions:

| Permission    | Description                              | Example                    |
| ------------- | ---------------------------------------- | -------------------------- |
| `permissions` | Permission object restricting key access | `{ "video:create": true }` |
| `ipWhitelist` | IP addresses allowed to use this key     | `["203.0.113.50"]`         |
| `spendLimit`  | Maximum spend limit in USD               | `1000`                     |

When no permissions are set, the key has full access to all providers and types.

## Security Best Practices

<AccordionGroup>
  <Accordion title="Use environment variables">
    Never hardcode API keys in your source code.

    ```bash theme={null}
    # .env
    MODELHUNTER_KEY=river_live_xxxxxxxxxxxxx
    ```

    ```javascript theme={null}
    const response = await fetch('https://api.modelhunter.ai/api/v1/...', {
      headers: {
        'Authorization': `Bearer ${process.env.MODELHUNTER_KEY}`,
      },
    });
    ```
  </Accordion>

  <Accordion title="Never commit keys to Git">
    Add `.env` to your `.gitignore` file. If a key is accidentally committed, rotate it immediately from the Dashboard.
  </Accordion>

  <Accordion title="Use scoped keys">
    Create separate keys for different environments and services. Scope each key to only the providers and types it needs.
  </Accordion>

  <Accordion title="Set spend limits">
    Use `spendLimit` to cap usage per key and prevent unexpected charges.
  </Accordion>
</AccordionGroup>

## Error Responses

| Status | Code                    | Description                    |
| ------ | ----------------------- | ------------------------------ |
| 401    | `AUTH_REQUIRED`         | No API key provided            |
| 401    | `AUTH_INVALID_TOKEN`    | Invalid or malformed API key   |
| 401    | `AUTH_TOKEN_EXPIRED`    | API key has expired            |
| 403    | `KEY_PERMISSION_DENIED` | Key lacks required permissions |
| 403    | `KEY_REVOKED`           | Key has been deleted           |


# Changelog
Source: https://docs.modelhunter.ai/changelog

Latest updates and changes to ModelHunter.AI

## March 2026

### v1.6 — ElevenLabs Audio

* **ElevenLabs**: Added `eleven-v3` for `text-to-speech`
* Added a dedicated API reference page for ElevenLabs text-to-speech
* Sidebar navigation now includes an Audio group for ElevenLabs

### v1.5 — Grok Imagine Video

* **Grok**: Added `grok-imagine-video` for text-to-video and image-to-video
* Added dedicated API reference pages for Grok text-to-video and image-to-video
* Sidebar navigation now includes a Grok group under Videos

### v1.4 — Veo 3.1

* **Gemini**: Added public models `veo-3.1` and `veo-3.1-fast` for text-to-video and image-to-video
* Added dedicated API reference pages for Veo text-to-video and image-to-video
* Sidebar navigation now includes a Gemini group under Videos for Veo

## February 2026

### v1.3 — Vidu and Kling

* **Vidu**: Added `viduq3-pro` and `viduq3-turbo` for text-to-video and image-to-video
* **Kling**: Added `kling-v3.0` and `kling-v2.6` for text-to-video and image-to-video
* Sidebar navigation now includes Vidu and Kling groups

### v1.2 — Seedream and Gemini Image

* **Seedream**: Added `seedream-5.0-lite`, `seedream-4.5`, `seedream-4.0`, and `seedream-3.0`
* **Gemini**: Added `nano-banana-2` for text-to-image and image-to-image
* Sidebar navigation now includes Seedream and Gemini image groups

### v1.1 — Seedance and Wan

* **Seedance**: Added `seedance-2.0`, `seedance-1.5-pro`, `seedance-1.0-pro`, `seedance-1.0-pro-fast`, and `seedance-1.0-lite`
* **Seedance 2.0**: Added the `multimodal-video` API for `bytedance/seedance-2`
* **Wan**: Added `wan-2.6` for text-to-video, image-to-video, and video-to-video

### v1.0 — Initial Release

* Unified API for AI video and image generation
* Supported providers: Seedance (video), Seedream (image)
* Async task model with polling and webhook notifications
* File upload with signed URLs
* API key authentication
* Interactive API Reference powered by OpenAPI
* JavaScript and Python code examples


# Async Tasks
Source: https://docs.modelhunter.ai/core-concepts/async-tasks

Understand the asynchronous task model used by all generation requests

## 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.

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant ModelHunter
    participant Provider

    Client->>ModelHunter: POST /api/v1/{provider}/{capability}
    ModelHunter-->>Client: 202 Accepted (task_id)
    ModelHunter->>Provider: Forward request
    Provider-->>ModelHunter: Generation complete
    Client->>ModelHunter: GET /api/v1/tasks/{id}
    ModelHunter-->>Client: 200 OK (result)
```

## Task Lifecycle

Every task progresses through these states:

| Status      | Description                                        |
| ----------- | -------------------------------------------------- |
| `pending`   | Request received, queued for processing            |
| `queued`    | Sent to the provider, waiting in their queue       |
| `running`   | Provider is actively generating                    |
| `succeeded` | Generation complete, result available              |
| `failed`    | Generation failed, error details available         |
| `cancelled` | Cancelled by the user before completion            |
| `expired`   | Result 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`.

<CodeGroup>
  ```javascript JavaScript theme={null}
  // 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: 'viduq3-turbo',
      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);
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
  }

  # Submit a generation request
  response = requests.post(
      'https://api.modelhunter.ai/api/v1/vidu/text-to-video',
      headers=headers,
      json={
          'model': 'viduq3-turbo',
          'input': {
              'prompt': 'A sunset over the ocean',
              'duration': 4,
          },
      },
  )

  task = response.json()

  # Poll until complete
  result = requests.get(
      f"https://api.modelhunter.ai/api/v1/tasks/{task['data']['id']}",
      headers=headers,
  ).json()

  print(result['data']['result'][0]['url'])
  ```
</CodeGroup>

**Recommended polling interval**: Start at 2 seconds, increase to 5 seconds after 30 seconds.

### Option 2: Webhooks (Recommended for Production)

Pass a `webhookUrl` in the generation request. ModelHunter.AI will POST the result directly to your server when the task completes.

```json theme={null}
{
  "model": "viduq3-turbo",
  "input": {
    "prompt": "A sunset over the ocean",
    "duration": 4
  },
  "webhookUrl": "https://your-server.com/webhooks/modelhunter"
}
```

See [Webhooks](/core-concepts/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.

```bash theme={null}
# Re-fetch to get a new signed URL
curl https://api.modelhunter.ai/api/v1/tasks/{id} \
  -H "Authorization: Bearer river_live_xxx"
```


# Error Handling
Source: https://docs.modelhunter.ai/core-concepts/error-handling

Understand error responses, error codes, and retry strategies

## Error Response Format

All errors follow a consistent JSON structure:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "prompt",
      "reason": "Required field is missing"
    }
  }
}
```

## HTTP Status Codes

| Status | Meaning               | When                       |
| ------ | --------------------- | -------------------------- |
| `400`  | Bad Request           | Invalid parameters         |
| `401`  | Unauthorized          | Missing or invalid API key |
| `402`  | Payment Required      | Insufficient balance       |
| `403`  | Forbidden             | Key lacks permissions      |
| `404`  | Not Found             | Resource does not exist    |
| `409`  | Conflict              | Resource state conflict    |
| `422`  | Unprocessable Entity  | Business logic error       |
| `429`  | Too Many Requests     | Rate limit exceeded        |
| `500`  | Internal Server Error | Unexpected server error    |
| `502`  | Bad Gateway           | Provider returned an error |
| `503`  | Service Unavailable   | Provider temporarily down  |

## Error Codes

### Authentication Errors (401)

| Code                 | Description                            |
| -------------------- | -------------------------------------- |
| `AUTH_REQUIRED`      | No Authorization header provided       |
| `AUTH_INVALID_TOKEN` | API key is malformed or does not exist |
| `AUTH_TOKEN_EXPIRED` | API key has passed its expiry date     |

### Permission Errors (403)

| Code                    | Description                                     |
| ----------------------- | ----------------------------------------------- |
| `FORBIDDEN`             | Action not allowed                              |
| `KEY_PERMISSION_DENIED` | API key lacks required provider/type permission |
| `KEY_EXPIRED`           | API key has expired                             |
| `KEY_REVOKED`           | API key has been deleted                        |

### Resource Errors (404)

| Code                 | Description                    |
| -------------------- | ------------------------------ |
| `NOT_FOUND`          | Generic resource not found     |
| `MODEL_NOT_FOUND`    | Requested model does not exist |
| `TASK_NOT_FOUND`     | Task ID does not exist         |
| `PROVIDER_NOT_FOUND` | Provider does not exist        |

### Validation Errors (400/422)

| Code                | Description                                     |
| ------------------- | ----------------------------------------------- |
| `VALIDATION_ERROR`  | Request body failed validation                  |
| `INVALID_PARAMETER` | A parameter value is out of range or wrong type |
| `MISSING_PARAMETER` | A required parameter is missing                 |

### Payment Errors (402)

| Code                   | Description                              |
| ---------------------- | ---------------------------------------- |
| `INSUFFICIENT_BALANCE` | Account balance too low for this request |
| `PAYMENT_REQUIRED`     | No payment method on file                |
| `PAYMENT_FAILED`       | Charge attempt failed                    |

### Business Logic Errors (422)

| Code                 | Description                            |
| -------------------- | -------------------------------------- |
| `QUOTA_EXCEEDED`     | Monthly quota for this API key reached |
| `FILE_TOO_LARGE`     | Uploaded file exceeds size limit       |
| `UNSUPPORTED_FORMAT` | File format not supported              |

### Rate Limit Errors (429)

| Code                  | Description                   |
| --------------------- | ----------------------------- |
| `RATE_LIMIT_EXCEEDED` | Too many requests — slow down |

### Conflict Errors (409)

| Code                 | Description                      |
| -------------------- | -------------------------------- |
| `TASK_NOT_RETRYABLE` | Only failed tasks can be retried |

### Provider Errors (502)

| Code                    | Description                         |
| ----------------------- | ----------------------------------- |
| `PROVIDER_ERROR`        | Upstream provider returned an error |
| `PROVIDER_UNAVAILABLE`  | Provider is temporarily offline     |
| `PROVIDER_TIMEOUT`      | Provider did not respond in time    |
| `PROVIDER_RATE_LIMITED` | Provider's own rate limit hit       |

### Internal Errors (500)

| Code             | Description             |
| ---------------- | ----------------------- |
| `INTERNAL_ERROR` | Unexpected server error |

## Retry Strategy

### Retryable vs Non-Retryable

| Retryable               | Non-Retryable              |
| ----------------------- | -------------------------- |
| `429` Rate limited      | `400` Validation error     |
| `500` Internal error    | `401` Authentication error |
| `502` Provider error    | `402` Payment error        |
| `503` Unavailable       | `403` Permission error     |
| `PROVIDER_TIMEOUT`      | `404` Not found            |
| `PROVIDER_RATE_LIMITED` | `409` Conflict             |

### Exponential Backoff

For retryable errors, use exponential backoff:

```javascript theme={null}
async function requestWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries || !isRetryable(error.status)) {
        throw error;
      }
      const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}

function isRetryable(status) {
  return [429, 500, 502, 503].includes(status);
}
```

### Rate Limit Handling

When you receive a `429`, check the `X-RateLimit-Reset` header for when you can retry:

```javascript theme={null}
if (response.status === 429) {
  const resetTimestamp = response.headers.get("X-RateLimit-Reset");
  const waitMs = parseInt(resetTimestamp, 10) * 1000 - Date.now();
  await new Promise((resolve) => setTimeout(resolve, Math.max(waitMs, 1000)));
}
```


# File Uploads
Source: https://docs.modelhunter.ai/core-concepts/file-uploads

Upload images and videos for use in generation requests

## Overview

Some generation types require file inputs (images for image-to-video, videos for video extension, etc.). ModelHunter.AI uses a **two-step upload flow** with signed URLs.

## Upload Flow

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant ModelHunter
    participant R2 Storage

    Client->>ModelHunter: POST /api/v1/files/upload-url
    ModelHunter-->>Client: { upload_url, file_id }
    Client->>R2 Storage: PUT upload_url (file bytes)
    R2 Storage-->>Client: 200 OK
    Client->>ModelHunter: POST /api/v1/files/{file_id}/complete
    ModelHunter-->>Client: { id, url }
```

### Step 1: Get a Signed Upload URL

```bash theme={null}
curl -X POST https://api.modelhunter.ai/api/v1/files/upload-url \
  -H "Authorization: Bearer river_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "sizeBytes": 2048576
  }'
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "upload_url": "https://storage.modelhunter.ai/uploads/file_abc123?X-Amz-Signature=xxx",
    "file_id": "file_abc123",
    "expires_at": "2025-01-15T10:15:00Z"
  }
}
```

### Step 2: Upload the File

Upload the file directly to the signed URL using a `PUT` request:

```bash theme={null}
curl -X PUT "https://storage.modelhunter.ai/uploads/file_abc123?X-Amz-Signature=xxx" \
  -H "Content-Type: image/jpeg" \
  --data-binary @my-image.jpg
```

### Step 3: Confirm the Upload

```bash theme={null}
curl -X POST https://api.modelhunter.ai/api/v1/files/file_abc123/complete \
  -H "Authorization: Bearer river_live_xxx"
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "id": "file_abc123",
    "url": "https://cdn.modelhunter.ai/files/file_abc123.jpg",
    "filename": "my-image.jpg",
    "content_type": "image/jpeg",
    "size_bytes": 2048576,
    "created_at": "2025-01-15T10:00:30Z"
  }
}
```

## Using Uploaded Files

Pass the file URL in your generation request:

```bash theme={null}
curl -X POST https://api.modelhunter.ai/api/v1/vidu/image-to-video \
  -H "Authorization: Bearer river_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3-turbo",
    "input": {
      "image_url": "https://cdn.modelhunter.ai/files/file_abc123.jpg",
      "prompt": "A cat walking gracefully",
      "duration": 4
    }
  }'
```

<Tip>
  You can also pass any publicly accessible URL as `image_url` or `video_url` — file upload is only needed for local files.
</Tip>

## Supported Formats

### Images

| Property         | Requirement          |
| ---------------- | -------------------- |
| Formats          | PNG, JPEG, JPG, WebP |
| Min resolution   | 128 x 128            |
| Max aspect ratio | 4:1 or 1:4           |
| Max file size    | 50 MB                |

### Video

| Property      | Requirement     |
| ------------- | --------------- |
| Formats       | MP4             |
| Duration      | 1 — 600 seconds |
| Max file size | 500 MB          |


# Task Status
Source: https://docs.modelhunter.ai/core-concepts/task-status

Query task status and results with the unified tasks API

## Get Task Status

Retrieve the current status and result of a generation task.

### Request

```http theme={null}
GET /api/v1/tasks/{id}
Authorization: Bearer river_live_xxx
```

### Response

<CodeGroup>
  ```json Succeeded theme={null}
  {
    "success": true,
    "data": {
      "id": "task_abc123",
      "type": "video",
      "status": "succeeded",
      "provider": "vidu",
      "model": "viduq3-turbo",
      "result": [
        {
          "url": "https://cdn.modelhunter.ai/results/task_abc123.mp4?signature=xxx",
          "duration": 4,
          "format": "mp4",
          "size_bytes": 12582912
        }
      ],
      "created_at": "2025-01-15T10:00:00Z",
      "completed_at": "2025-01-15T10:00:45Z"
    }
  }
  ```

  ```json Running theme={null}
  {
    "success": true,
    "data": {
      "id": "task_abc123",
      "type": "video",
      "status": "running",
      "provider": "vidu",
      "model": "viduq3-turbo",
      "created_at": "2025-01-15T10:00:00Z"
    }
  }
  ```

  ```json Failed theme={null}
  {
    "success": true,
    "data": {
      "id": "task_abc123",
      "type": "video",
      "status": "failed",
      "provider": "vidu",
      "model": "viduq3-turbo",
      "error": {
        "code": "PROVIDER_ERROR",
        "message": "Content moderation: prompt contains restricted content"
      },
      "created_at": "2025-01-15T10:00:00Z",
      "completed_at": "2025-01-15T10:00:10Z"
    }
  }
  ```
</CodeGroup>

### Status Values

| Status      | Description                   | `result` present?    |
| ----------- | ----------------------------- | -------------------- |
| `pending`   | Queued on ModelHunter.AI side | No                   |
| `queued`    | Sent to provider, waiting     | No                   |
| `running`   | Actively generating           | No                   |
| `succeeded` | Complete                      | Yes                  |
| `failed`    | Error occurred                | No (`error` present) |
| `cancelled` | Cancelled by user             | No                   |
| `expired`   | Result URL expired            | Re-fetch for new URL |

### Result Fields

When status is `succeeded`, the `result` field contains an **array** of output items. Each item has:

| Field        | Type     | Description                                      |
| ------------ | -------- | ------------------------------------------------ |
| `url`        | `string` | Signed URL for the output file (valid 15 min)    |
| `duration`   | `number` | Video/audio length in seconds (video/audio only) |
| `format`     | `string` | File format (`mp4`, `png`, `jpg`, `mp3`, etc.)   |
| `size_bytes` | `number` | File size in bytes                               |


# Webhooks
Source: https://docs.modelhunter.ai/core-concepts/webhooks

Receive real-time notifications when tasks complete

## Overview

Instead of polling for task status, configure a webhook to receive notifications when events occur. ModelHunter.AI will POST a JSON payload to your URL.

## Register a Webhook

```bash theme={null}
curl -X POST https://api.modelhunter.ai/api/v1/webhooks \
  -H "Authorization: Bearer river_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/modelhunter",
    "events": ["task.completed", "task.failed"]
  }'
```

### Event Types

| Event            | Description                             |
| ---------------- | --------------------------------------- |
| `task.completed` | A generation task finished successfully |
| `task.failed`    | A generation task failed                |

## Webhook Payload

### Headers

```http theme={null}
Content-Type: application/json
X-Webhook-ID: evt_abc123
X-Webhook-Timestamp: 1705312800
X-Webhook-Signature: sha256=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
```

### Body

<CodeGroup>
  ```json task.completed theme={null}
  {
    "id": "evt_abc123",
    "type": "task.completed",
    "created_at": "2025-01-15T10:00:45Z",
    "data": {
      "task": {
        "id": "task_abc123",
        "type": "video",
        "status": "succeeded",
        "provider": "vidu",
        "model": "viduq3-turbo",
        "result": [
          {
            "url": "https://cdn.modelhunter.ai/results/task_abc123.mp4?signature=xxx",
            "duration": 4,
            "format": "mp4",
            "size_bytes": 12582912
          }
        ],
        "created_at": "2025-01-15T10:00:00Z",
        "completed_at": "2025-01-15T10:00:45Z",
        "metadata": { "user_id": "u_123" }
      }
    }
  }
  ```

  ```json task.failed theme={null}
  {
    "id": "evt_def456",
    "type": "task.failed",
    "created_at": "2025-01-15T10:00:10Z",
    "data": {
      "task": {
        "id": "task_def456",
        "type": "video",
        "status": "failed",
        "provider": "vidu",
        "model": "viduq3-turbo",
        "error": {
          "code": "PROVIDER_ERROR",
          "message": "Content policy violation"
        },
        "created_at": "2025-01-15T10:00:00Z",
        "completed_at": "2025-01-15T10:00:10Z"
      }
    }
  }
  ```
</CodeGroup>

## Per-Job Webhooks vs Configured Webhooks

There are two types of webhook delivery:

* **Configured webhooks** (registered via `POST /api/v1/webhooks`) include `X-Webhook-Signature` for verification and support automatic retries.
* **Per-job webhooks** (via `webhookUrl` in a generation request) do **not** include `X-Webhook-Signature` (no shared secret), but include additional headers: `X-Webhook-Event` (e.g. `task.completed`) and `X-Job-ID`.

## Signature Verification

Configured webhooks include an `X-Webhook-Signature` header. Verify it to ensure the request is authentic.

The signature is computed as `HMAC-SHA256(timestamp + "." + body, secret)`.

<CodeGroup>
  ```javascript JavaScript theme={null}
  import crypto from "crypto";

  function verifyWebhookSignature(req, secret) {
    const timestamp = req.headers["x-webhook-timestamp"];
    const signature = req.headers["x-webhook-signature"];
    const body = JSON.stringify(req.body);

    const expected = crypto
      .createHmac("sha256", secret)
      .update(`${timestamp}.${body}`)
      .digest("hex");

    const expectedSignature = `sha256=${expected}`;

    if (signature !== expectedSignature) {
      throw new Error("Invalid webhook signature");
    }

    // Reject timestamps older than 5 minutes
    const age = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10);
    if (age > 300) {
      throw new Error("Webhook timestamp too old");
    }

    return true;
  }
  ```

  ```python Python theme={null}
  import hmac
  import hashlib
  import time
  import json

  def verify_webhook_signature(headers, body, secret):
      timestamp = headers["X-Webhook-Timestamp"]
      signature = headers["X-Webhook-Signature"]

      payload = f"{timestamp}.{json.dumps(body)}"
      expected = hmac.new(
          secret.encode(),
          payload.encode(),
          hashlib.sha256,
      ).hexdigest()

      expected_signature = f"sha256={expected}"

      if not hmac.compare_digest(signature, expected_signature):
          raise ValueError("Invalid webhook signature")

      # Reject timestamps older than 5 minutes
      age = int(time.time()) - int(timestamp)
      if age > 300:
          raise ValueError("Webhook timestamp too old")

      return True
  ```
</CodeGroup>

## Retry Policy

If your endpoint does not return a `2xx` status, ModelHunter.AI retries with exponential backoff:

| Attempt | Delay      |
| ------- | ---------- |
| 1       | 1 minute   |
| 2       | 5 minutes  |
| 3       | 30 minutes |

After 3 failed attempts, the delivery is marked as failed. You can replay it from the Dashboard.

## Test a Webhook

Send a test event to verify your endpoint:

```bash theme={null}
curl -X POST https://api.modelhunter.ai/api/v1/webhooks/{webhook_id}/test \
  -H "Authorization: Bearer river_live_xxx"
```

## Manage Webhooks

```bash theme={null}
# List webhooks
curl https://api.modelhunter.ai/api/v1/webhooks \
  -H "Authorization: Bearer river_live_xxx"

# Delete a webhook
curl -X DELETE https://api.modelhunter.ai/api/v1/webhooks/{webhook_id} \
  -H "Authorization: Bearer river_live_xxx"
```


# Introduction
Source: https://docs.modelhunter.ai/introduction

Unified API for AI video and image generation

# Welcome to ModelHunter.AI

ModelHunter.AI is a **unified multimodal AI generation platform** that gives you a single API to access the best video and image generation models from multiple providers.

## Why ModelHunter.AI?

<CardGroup>
  <Card title="Single API Key" icon="key">
    One API key to access Gemini, Grok, Vidu, Kling, Seedance, Wan, Seedream, and more. No need to manage accounts with every provider.
  </Card>

  <Card title="Unified Task Model" icon="list-check">
    All generation requests follow the same async task pattern. Submit a request, poll or receive a webhook — works the same across every provider.
  </Card>

  <Card title="Multi-Provider Routing" icon="shuffle">
    When the same model is available from multiple suppliers, ModelHunter.AI automatically routes to the most available one — you never notice.
  </Card>

  <Card title="Pay-as-you-go" icon="credit-card">
    Simple per-unit pricing with no subscriptions. Top up your balance or bind a card for automatic billing.
  </Card>
</CardGroup>

## Supported Categories

| Category  | Providers                                      | Use Cases                                                                          |
| --------- | ---------------------------------------------- | ---------------------------------------------------------------------------------- |
| **Video** | Gemini (Veo), Grok, Vidu, Kling, Seedance, Wan | Text-to-video, image-to-video, reference-to-video, video-to-video, video extension |
| **Image** | Seedream, Gemini (Nano Banana)                 | Text-to-image, image-to-image                                                      |

## Quick Navigation

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Generate your first video in 3 minutes
  </Card>

  <Card title="Models" icon="cube" href="/api-reference/veo/text-to-video">
    Browse all available models
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Full OpenAPI specification
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.modelhunter.ai/quickstart

Generate your first AI video in 3 minutes

## Get Started

<Steps>
  <Step title="Get your API Key">
    Sign up at [ModelHunter.AI Dashboard](https://modelhunter.ai/register) and create an API key from the **API Keys** page.
  </Step>

  <Step title="Set up your environment">
    Set your API key as an environment variable:

    ```bash theme={null}
    export MODELHUNTER_KEY="mh_live_xxx"
    ```
  </Step>

  <Step title="Generate a video">
    Submit a text-to-video request and poll for the result.

    <CodeGroup>
      ```javascript JavaScript theme={null}
      const API_KEY = process.env.MODELHUNTER_KEY;
      const BASE = 'https://api.modelhunter.ai/api/v1';

      // 1. Submit a generation request
      const response = await fetch(`${BASE}/vidu/text-to-video`, {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          model: 'viduq3-turbo',
          input: {
            prompt: 'A futuristic city at sunset, flying cars, neon lights',
            duration: 4,
            aspect_ratio: '16:9',
            resolution: '1080p',
          },
        }),
      });

      const task = await response.json();
      const taskId = task.data.id;
      console.log('Task ID:', taskId);

      // 2. Poll until complete
      let result;
      while (true) {
        await new Promise(r => setTimeout(r, 3000)); // wait 3s
        const poll = await fetch(`${BASE}/tasks/${taskId}`, {
          headers: { 'Authorization': `Bearer ${API_KEY}` },
        }).then(r => r.json());

        console.log('Status:', poll.data.status);
        if (poll.data.status === 'succeeded') {
          result = poll.data;
          break;
        }
        if (poll.data.status === 'failed') {
          throw new Error(poll.data.error?.message || 'Task failed');
        }
      }

      console.log('Video URL:', result.result[0].url);
      ```

      ```python Python theme={null}
      import requests, time

      API_KEY = 'mh_live_xxx'
      BASE = 'https://api.modelhunter.ai/api/v1'
      headers = {
          'Authorization': f'Bearer {API_KEY}',
          'Content-Type': 'application/json',
      }

      # 1. Submit a generation request
      response = requests.post(
          f'{BASE}/vidu/text-to-video',
          headers=headers,
          json={
              'model': 'viduq3-turbo',
              'input': {
                  'prompt': 'A futuristic city at sunset, flying cars, neon lights',
                  'duration': 4,
                  'aspect_ratio': '16:9',
                  'resolution': '1080p',
              },
          },
      )

      task = response.json()
      task_id = task['data']['id']
      print('Task ID:', task_id)

      # 2. Poll until complete
      while True:
          time.sleep(3)
          poll = requests.get(
              f'{BASE}/tasks/{task_id}',
              headers=headers,
          ).json()

          status = poll['data']['status']
          print('Status:', status)
          if status == 'succeeded':
              print('Video URL:', poll['data']['result'][0]['url'])
              break
          if status == 'failed':
              raise Exception(poll['data'].get('error', {}).get('message', 'Task failed'))
      ```

      ```bash cURL theme={null}
      # 1. Submit a generation request
      curl -X POST https://api.modelhunter.ai/api/v1/vidu/text-to-video \
        -H "Authorization: Bearer mh_live_xxx" \
        -H "Content-Type: application/json" \
        -d '{
          "model": "viduq3-turbo",
          "input": {
            "prompt": "A futuristic city at sunset, flying cars, neon lights",
            "duration": 4,
            "aspect_ratio": "16:9",
            "resolution": "1080p"
          }
        }'
      # Returns: { "data": { "id": "task_abc123", ... } }

      # 2. Poll until complete (replace task_abc123 with your task ID)
      curl https://api.modelhunter.ai/api/v1/tasks/task_abc123 \
        -H "Authorization: Bearer mh_live_xxx"
      # Repeat every few seconds until status is "succeeded" or "failed"
      ```
    </CodeGroup>
  </Step>
</Steps>

## What's Next?

<CardGroup>
  <Card title="Async Tasks" icon="clock" href="/core-concepts/async-tasks">
    Understand the task lifecycle and polling patterns
  </Card>

  <Card title="Webhooks" icon="bell" href="/core-concepts/webhooks">
    Get notified when tasks complete instead of polling
  </Card>

  <Card title="Video Models" icon="video" href="/api-reference/veo/text-to-video">
    Explore all video generation models
  </Card>

  <Card title="Image Models" icon="image" href="/api-reference/seedream/text-to-image">
    Generate images with Seedream
  </Card>
</CardGroup>